/aspire

name: aspire
description: "Build, upgrade, and operate Aspire 13.4.x C# or TypeScript application hosts with the current CLI, AppHost, ServiceDefaults, integrations, dashboard, testing, MCP, and deployment patterns for distributed apps. USE FOR: Aspire.AppHost.Sdk, Aspire.Hosting.*, DistributedApplication.CreateBuilder, apphost.mts, createBuilder, WithReference, WaitFor, AddProject, AddRedis, AddPostgres, aspire run, aspire init, aspire. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Best for current Aspire 13.4.x tooling with .NET 10 or a supported Node.js runtime for TypeScript AppHosts; use version-aware upgrade guidance for older 8.x or 9.x solutions."

Aspire

Trigger On

• `Aspire.AppHost.Sdk`, `Aspire.Hosting.*`, `DistributedApplication.CreateBuilder`, `apphost.mts`, `createBuilder`, `WithReference`, `WaitFor`, `AddProject`, `addNodeApp`, `addViteApp`, `AddRedis`, `AddPostgres`, `aspire run`, `aspire init`, `aspire add`, or `aspire update`
• `Aspire.Hosting.Testing`, `DistributedApplicationTestingBuilder`, or a test harness that mixes an Aspire AppHost with `WebApplicationFactory`
• orchestrating multiple services and resources with an AppHost for local development or cloud deployment
• setting up `ServiceDefaults`, service discovery, OpenTelemetry, health checks, or the Aspire Dashboard
• choosing between official first-party Aspire integrations and `CommunityToolkit/Aspire`
• upgrading older 8.x or 9.x Aspire solutions to the current CLI and AppHost SDK model
• wiring polyglot services into an Aspire topology, especially when Go, Bun, Java, Python, or extra dev-time tools enter the picture

Workflow

1. Classify the task first: new AppHost creation, existing-solution enlistment, integration wiring, testing and observability, deployment, or version upgrade. 2. Prefer the current Aspire toolchain. Choose a C# AppHost for .NET-first repositories or a TypeScript `apphost.mts` for JavaScript/TypeScript-first repositories; both are first-class in 13.4. Use the Aspire CLI and current SDK-generated app model instead of writing new guidance around the deprecated legacy workload. 3. Treat 13.4.x releases as servicing and feature updates for the current CLI-first app model, not a topology rewrite. Keep the Aspire CLI, `Aspire.AppHost.Sdk`, and closely coupled hosting or testing packages on the same line, then rerun the AppHost and deployment checks after `aspire update`. 4. Keep the AppHost code-first and topology-focused. Model services, resources, dependencies, endpoints, lifetimes, and parameters there; keep business logic out. 5. Keep `ServiceDefaults` narrow. It exists for telemetry, health checks, resilience, and service discovery, not shared domain models or general utility code. 6. Prefer official first-party Aspire integrations when they cover the requirement. Use `CommunityToolkit/Aspire` only when the capability gap is real: unsupported language hosts, extra dev infrastructure, or extension packages the official project does not provide. 7. Validate the whole distributed system, not one project in isolation. Local success means the AppHost starts cleanly, dependencies resolve through `WithReference`, the dashboard shows the expected resource graph, and end-to-end tests can exercise the topology. 8. For integration tests, keep one shared AppHost fixture per test session. Use `Aspire.Hosting.Testing` to boot the distributed app, create `HttpClient` or SignalR clients from the AppHost, and layer `WebApplicationFactory` on top only when tests need direct Host DI, grains, or runtime services. 9. When publishing, switch from local containers or emulators to managed resources deliberately and verify which services truly need external endpoints.

Architecture

flowchart LR
  A["Distributed-app task"] --> B{"Need code-first orchestration?"}
  B -->|No| C["Stay in service-level skills such as ASP.NET Core, Worker, or Orleans"]
  B -->|Yes| D["Create or update the AppHost"]
  D --> E["Model resources and services with `WithReference` and `WaitFor`"]
  E --> F{"Official Aspire integration exists?"}
  F -->|Yes| G["Use first-party Aspire integration"]
  F -->|No or gap remains| H["Evaluate `CommunityToolkit/Aspire`"]
  G --> I["Apply `ServiceDefaults`, dashboard, and tests"]
  H --> I
  I --> J{"Publishing now?"}
  J -->|No| K["Run locally with `aspire run` or the AppHost project"]
  J -->|Yes| L["Choose `azd`, App Service, or the CLI deploy/publish pipeline"]

Current Guidance

• AppHost shape: recognize three current first-class forms: an SDK-style C# AppHost project using `Aspire.AppHost.Sdk/<version>`, a file-based C# `apphost.cs`, or a TypeScript `apphost.mts`. For TypeScript, `aspire init --language typescript` writes `aspire.config.json` and the generated `.aspire/modules/` SDK; do not hand-edit generated modules, and run `aspire restore` after package/integration changes.
• TypeScript AppHosts: use the async lower-camel-case app model (`createBuilder`, `addNodeApp`, `addViteApp`, `withReference`, `waitFor`, `build().run()`). In an existing repository with a root `package.json`, expect the CLI to create a nested `aspire-apphost/` package so the application and orchestration toolchains stay separate.
• Polyglot hosting: Aspire 13.4 adds first-party Go and Bun support. Prefer the official hosting surface for new Go or Bun resources before considering older toolkit integrations; keep community integrations for languages and capabilities that still have a real first-party gap.
• CLI entry points: use `aspire new` for starter projects, `aspire init` to add Aspire support to an existing solution or create a single-file AppHost, `aspire add` to add integrations or starter pieces, `aspire run` for local orchestration, `aspire start`/`aspire stop`/`aspire ps