Add Aspire to an existing app
Add Aspire to the app you already have instead of rebuilding your solution around a new template. The fastest path is aspire init paired with an AI coding agent that automatically discovers your services and wires them into an AppHost. If you prefer full control, manual steps are provided below.
Why add Aspire to an existing app?
Section titled “Why add Aspire to an existing app?”As distributed applications grow, local development often turns into a collection of fragile scripts, copied connection strings, and startup-order tribal knowledge. Aspire gives you a single orchestration layer for the resources you already own. Define the relationships once in code, and Aspire handles service discovery, configuration injection, startup ordering, and dashboard visibility.
You can also adopt Aspire incrementally. Start by modeling the parts that are hardest to keep aligned by hand, such as containers, databases, caches, queues, background workers, and local dev commands. Add telemetry when you’re ready, then deepen the model as your app grows.
Prerequisites
Section titled “Prerequisites”Before you begin, make sure you have:
- Aspire CLI installed
- An existing application or workspace to add Aspire to
- The runtimes and tools your existing services already need
AppHost-specific requirements
Section titled “AppHost-specific requirements”- Node.js 22.x or 24.x LTS
- A supported AppHost-root package manager: npm, pnpm, Yarn 4+, or Bun
- .NET SDK 10.0 or later
- Visual Studio 2022 17.13 or later, Visual Studio Code, or JetBrains Rider (optional)
- Go 1.26 or later with
goon yourPATH - A supported container runtime if your AppHost uses container resources, as described in the prerequisites
Recommended: Use an AI coding agent with the “aspireify” skill
Section titled “Recommended: Use an AI coding agent with the “aspireify” skill”The fastest way to add Aspire to an existing app is to let aspire init scaffold the skeleton, then hand off wiring to the aspireify agent skill. The skill handles resource discovery, dependency wiring, OpenTelemetry setup, and validation automatically.
-
Run
aspire initin your repo root:Initialize Aspire aspire initChoose your AppHost language (C#, TypeScript, or Go) when prompted, or pass
--language csharp/--language typescript/--language go. The command creates a minimal AppHost, anaspire.config.json, and installs theaspireifyskill into your agent’s skill directory. For existing JavaScript or TypeScript apps with a rootpackage.json, the TypeScript AppHost is created in anaspire-apphost/subfolder so Aspire doesn’t change the existing app package’s module settings. -
Ask your AI coding agent to run the
aspireifyskill. The agent will:- Scan your repo and discover existing projects, services, containers, and infrastructure
- Ask you to confirm the resources it found, which ones you want included, and other clarifying questions before starting
- Wire resources into the AppHost with
WithReferencewithReferenceWithReference,WaitForwaitForWaitFor, endpoints, and volumes - Add ServiceDefaults and configure OpenTelemetry for each service
- Validate the setup by running
aspire start
-
Once the agent reports success, run
aspire startyourself and open the dashboard to verify everything looks correct. Something not right? Tell the agent-it has plenty of tools from Aspire to troubleshoot!
For more details on the aspire init command and the aspireify skill, see the CLI reference: aspire init.
Wire your AppHost manually
Section titled “Wire your AppHost manually”If you prefer full control over the wiring, or want to understand what the aspireify skill does under the hood, follow the manual steps below. This is also the reference for anyone extending or customizing an AppHost after the initial setup.
Choose your AppHost
Section titled “Choose your AppHost”The AppHost is the orchestration layer. Your choice here changes how you express orchestration, not what Aspire can orchestrate.
Use a TypeScript AppHost when your repo already centers on a Node.js workspace or when you prefer path-based orchestration in TypeScript.
- Lives in
apphost.mts; for existing JavaScript and TypeScript apps,aspire initcreates it underaspire-apphost/ - Runs under supported package managers including npm, pnpm, Yarn 4+, and Bun
- Fits naturally into existing package-manager and monorepo workflows
Aspire offers two C# AppHost styles:
File-based AppHost — a single apphost.cs file that uses #:package directives. No .csproj, no solution integration required. Best for repos with polyglot code or quick setups.
Project-based AppHost — a traditional AppHost.csproj that lives inside a .sln alongside your other C# projects. Best when your repo is already a .NET solution and you want IDE-integrated orchestration.
Both styles use the same AppHost packages and hosting APIs, and both add .NET projects by path with AddDotnetProject.
Use a Go AppHost when your team works in Go or when you want the AppHost to be a regular, compiled Go program.
- Lives in
apphost.gowith its owngo.mod; when your repo already has a rootgo.mod,aspire initcreates the AppHost underaspire-apphost/and leaves your module untouched - Uses the generated Go SDK in
.aspire/modules, imported asapphost/modules/aspire - Starts through
aspire runoraspire start, which build and launch the AppHost for you
For the project layout and conventions, see Go AppHost project structure.
Set up your AppHost
Section titled “Set up your AppHost”-
Run
aspire initfrom your workspace root with the TypeScript language option:Initialize Aspire with a TypeScript AppHost aspire init --language typescript -
Add hosting integrations:
Add hosting integrations aspire add redisaspire add postgres -
Wire the resources in
aspire-apphost/apphost.mts:apphost.mts import {createBuilder } from './.aspire/modules/aspire.mjs';function createBuilder(): IDistributedApplicationBuilderCreates a new distributed application builder
constbuilder = awaitconst builder: IDistributedApplicationBuildercreateBuilder();function createBuilder(): IDistributedApplicationBuilderCreates a new distributed application builder
constcache = awaitconst cache: RedisResourcebuilder.const builder: IDistributedApplicationBuilderaddRedis('cache');IDistributedApplicationBuilder.addRedis(name: string, options?: {port?: number;password?: string | ParameterResource;}): RedisResource (+1 overload)Adds a Redis container to the application model.
constdb = (awaitconst db: PostgresDatabaseResourcebuilder.const builder: IDistributedApplicationBuilderaddPostgres('postgres')).IDistributedApplicationBuilder.addPostgres(name: string, options?: {userName?: string | ParameterResource;password?: string | ParameterResource;port?: number;}): PostgresServerResource (+1 overload)Adds a PostgreSQL resource to the application model. A container is used for local development.
addDatabase('mydb');PostgresServerResource.addDatabase(name: string, options?: {databaseName?: string;} | undefined): PostgresDatabaseResource (+1 overload)Adds a PostgreSQL database to the application model.
constapi = awaitconst api: DotnetProjectResourcebuilderconst builder: IDistributedApplicationBuilder.addDotnetProject('api', '../src/Api/MyApp.Api.csproj')IDistributedApplicationBuilder.addDotnetProject(name: string, path: string, options?: DotnetProjectOptions): DotnetProjectResourceAdds a .NET application resource.
.withReference(ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: {connectionName?: string;optional?: boolean;name?: string;} | undefined): DotnetProjectResource (+1 overload)Adds a reference to another resource
db)const db: PostgresDatabaseResource.withReference(ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: {connectionName?: string;optional?: boolean;name?: string;} | undefined): DotnetProjectResource (+1 overload)Adds a reference to another resource
cache)const cache: RedisResource.waitFor(ExecutableResource.waitFor(dependency: IResource | IResourceWithConnectionString, waitBehavior?: WaitBehavior): DotnetProjectResourceWaits for another resource to be ready
db);const db: PostgresDatabaseResourceawaitbuilderconst builder: IDistributedApplicationBuilder.addViteApp('web', '../services/web')IDistributedApplicationBuilder.addViteApp(name: string, appDirectory: string, options?: {runScriptName?: string;}): ViteAppResource (+1 overload)Adds a Vite app to the distributed application builder.
.withReference(ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: {connectionName?: string;optional?: boolean;name?: string;} | undefined): ViteAppResource (+1 overload)Adds a reference to another resource
api)const api: DotnetProjectResource.waitFor(ExecutableResource.waitFor(dependency: IResource | IResourceWithConnectionString, waitBehavior?: WaitBehavior): ViteAppResourceWaits for another resource to be ready
api);const api: DotnetProjectResourceawaitbuilder.const builder: IDistributedApplicationBuilderbuild().IDistributedApplicationBuilder.build(): DistributedApplicationBuilds the distributed application
run();DistributedApplication.run(cancellationToken?: cancellationToken): voidRuns the distributed application
After setup, a typical workspace layout looks like this:
- aspire.config.json (new)
- package.json (updated with Aspire delegate scripts)
Directoryaspire-apphost/ (new)
- apphost.mts
Directory.aspire/modules/
- …
- package.json
- tsconfig.apphost.json
Directoryservices/
Directoryweb/
- package.json
Directorysrc/
- …
Directorysrc/
DirectoryApi/
- MyApp.Api.csproj
Workspace subdirectory layout
Section titled “Workspace subdirectory layout”When your app already lives inside a subdirectory of a larger workspace (for example, apps/my-app/), run aspire init from that subdirectory. The CLI places the AppHost under aspire-apphost/ relative to where you run the command:
cd apps/my-appaspire init --language typescript --non-interactiveThe resulting layout looks like this:
Directoryapps/
Directorymy-app/
Directoryaspire-apphost/ (new)
- apphost.mts (new)
- package.json (new)
- tsconfig.apphost.json (new)
Directory.aspire/ (new)
Directorymodules/ (new)
- …
- aspire.config.json (new)
- package.json (updated with delegate scripts)
Directorysrc/
- …
Root package.json delegate scripts
Section titled “Root package.json delegate scripts”aspire init adds delegate scripts to the root package.json so you can run the AppHost from the workspace root without cd-ing into aspire-apphost/:
| Script | What it does |
|---|---|
aspire:start | Starts the Aspire dashboard and all orchestrated services |
aspire:build | Compiles the TypeScript AppHost |
aspire:dev | Watches the AppHost for changes |
These scripts delegate to the AppHost subdirectory using your package manager. For example, with pnpm and an AppHost at aspire-apphost/:
{ "scripts": { "aspire:start": "pnpm --dir aspire-apphost run aspire:start", "aspire:build": "pnpm --dir aspire-apphost run aspire:build", "aspire:dev": "pnpm --dir aspire-apphost run aspire:dev" }}Package-manager isolation
Section titled “Package-manager isolation”The AppHost package and your guest apps can use different package managers. The AppHost directory takes precedence for running AppHost scripts — if the AppHost’s package.json declares "packageManager": "pnpm@..." or contains a pnpm-lock.yaml, pnpm is used for AppHost operations regardless of the toolchain in the parent workspace.
File-based AppHost (default)
Section titled “File-based AppHost (default)”Use a file-based AppHost when you want a lightweight single-file orchestrator without adding a project to your solution. This is the default style created by aspire init when no .sln is detected.
-
Run
aspire initfrom your repo root. Without a.slnpresent, it creates a file-basedapphost.cs:Initialize Aspire with a file-based AppHost aspire init -
Add hosting integrations:
Add hosting integrations aspire add redisaspire add Aspire.Hosting.Dotnet -
Wire the resources in
apphost.cs:apphost.cs #:package Aspire.Hosting.AppHost@17.0.0#:package Aspire.Hosting.Redis@17.0.0#:package Aspire.Hosting.Dotnet@17.0.0var builder = DistributedApplication.CreateBuilder(args);var cache = builder.AddRedis("cache");var api = builder.AddDotnetProject("api", "./src/Api/MyApp.Api.csproj").WithReference(cache).WithHttpHealthCheck("/health");var worker = builder.AddDotnetProject("worker", "./src/Worker/MyApp.Worker.csproj").WithReference(cache);builder.Build().Run();
After setup, a typical repo layout looks like this:
- apphost.cs (new)
- aspire.config.json (new)
Directorysrc/
DirectoryApi/
- MyApp.Api.csproj
DirectoryWorker/
- MyApp.Worker.csproj
Project-based AppHost (with a .sln)
Section titled “Project-based AppHost (with a .sln)”Use this approach when your repo is already a .NET solution (.sln or .slnx) with multiple projects. The project-based AppHost joins your solution, so you get full IDE support including IntelliSense, debugging, and refactoring.
-
Run
aspire initfrom your solution root. It detects the.slnand creates a project-based AppHost automatically:Initialize Aspire in a .NET solution aspire init -
Add hosting integrations:
Add hosting integrations aspire add redisaspire add postgresaspire add Aspire.Hosting.Dotnet -
Wire the resources in the AppHost’s
AppHost.cs, referencing each service by its project path:MyApp.AppHost/AppHost.cs var builder = DistributedApplication.CreateBuilder(args);var cache = builder.AddRedis("cache").WithLifetime(ContainerLifetime.Persistent);var db = builder.AddPostgres("postgres").WithLifetime(ContainerLifetime.Persistent).AddDatabase("mydb");var api = builder.AddDotnetProject("api", "../src/Api/MyApp.Api.csproj").WithReference(db).WithReference(cache).WaitFor(db);builder.AddDotnetProject("web", "../src/Web/MyApp.Web.csproj").WithReference(api).WaitFor(api);builder.AddDotnetProject("worker", "../src/Worker/MyApp.Worker.csproj").WithReference(cache).WithReference(db);builder.Build().Run();
After setup, a typical solution layout looks like this:
- MyApp.sln
DirectoryMyApp.AppHost/
- MyApp.AppHost.csproj
- AppHost.cs
Directorysrc/
DirectoryApi/
- MyApp.Api.csproj
DirectoryWeb/
- MyApp.Web.csproj
DirectoryWorker/
- MyApp.Worker.csproj
For launch profiles, file-based apps, and IDE behavior, see .NET hosting.
-
Run
aspire initfrom your workspace root with the Go language option:Initialize Aspire with a Go AppHost aspire init --language go -
Add hosting integrations:
Add hosting integrations aspire add redisaspire add postgresaspire add Aspire.Hosting.Dotnet -
Wire the resources in
aspire-apphost/apphost.go:apphost.go package mainimport ("log""apphost/modules/aspire")func main() {builder, err := aspire.CreateBuilder()if err != nil {log.Fatal(aspire.FormatError(err))}cache := builder.AddRedis("cache")db := builder.AddPostgres("postgres").AddDatabase("mydb")api := builder.AddDotnetProject("api", "../src/Api/MyApp.Api.csproj").WithReference(db).WithReference(cache).WaitFor(db)builder.AddViteApp("web", "../services/web").WithReference(api).WaitFor(api)app, err := builder.Build()if err != nil {log.Fatal(aspire.FormatError(err))}if err := app.Run(); err != nil {log.Fatal(aspire.FormatError(err))}}
After setup, a typical workspace layout looks like this:
- aspire.config.json (new)
Directoryaspire-apphost/ (new)
- apphost.go
- go.mod
Directory.aspire/modules/
- …
Directoryservices/
Directoryweb/
- package.json
Directorysrc/
- …
Directorysrc/
DirectoryApi/
- MyApp.Api.csproj
Existing Go module
Section titled “Existing Go module”When your repo already has a root go.mod, aspire init --language go keeps it unchanged and places the AppHost in aspire-apphost/, with its own go.mod and generated SDK. The AppHost module is separate from your application module, so the AppHost’s dependencies don’t change your app’s dependencies. A Go service is added to the AppHost with AddGoApp, which takes the directory that contains the service:
builder.AddGoApp("api", "../cmd/api"). WithHttpEndpoint(aspire.HttpEndpointEnv("PORT")). WithExternalHttpEndpoints()For the AddGoApp options and publishing behavior, see Go hosting integration.
Scenario: Existing services with hosting integrations
Section titled “Scenario: Existing services with hosting integrations”Use this approach when Aspire already has a first-class resource type for the workload you want to run. That keeps the application model focused on what the service is and what it depends on, instead of reducing it to a generic shell command.
Common examples include Node.js apps, Vite frontends, Python workers, and Uvicorn-based APIs.
The following example registers a Python API with AddUvicornAppaddUvicornAppAddUvicornApp, a worker with AddPythonAppaddPythonAppAddPythonApp, and a frontend with AddViteAppaddViteAppAddViteApp.
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
builder = await function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const cache: RedisResource
cache = await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addRedis(name: string, options?: { port?: number; password?: string | ParameterResource;}): RedisResource (+1 overload)
Adds a Redis container to the application model.
addRedis('cache');
const const api: UvicornAppResource
api = await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addUvicornApp(name: string, appDirectory: string, app: string): UvicornAppResource
Adds a Uvicorn-based Python application to the distributed application builder with HTTP endpoint configuration.
addUvicornApp('api', '../services/api', 'main:app') .UvicornAppResource.withUv(options?: { install?: boolean; args?: string[];} | undefined): UvicornAppResource (+1 overload)
Adds a UV environment setup task to ensure the virtual environment exists before running the Python application.
withUv() .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): UvicornAppResource (+1 overload)
Adds a reference to another resource
withReference(const cache: RedisResource
cache) .ExecutableResource.withExternalHttpEndpoints(): UvicornAppResource
Marks existing http or https endpoints on a resource as external.
withExternalHttpEndpoints();
await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addPythonApp(name: string, appDirectory: string, scriptPath: string): PythonAppResource
Adds a Python application to the application model.
addPythonApp('worker', '../workers/inventory-sync', 'worker.py') .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): PythonAppResource (+1 overload)
Adds a reference to another resource
withReference(const cache: RedisResource
cache);
await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addViteApp(name: string, appDirectory: string, options?: { runScriptName?: string;}): ViteAppResource (+1 overload)
Adds a Vite app to the distributed application builder.
addViteApp('web', '../services/web') .ExecutableResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): ViteAppResource (+1 overload)
Adds a reference to another resource
withReference(const api: UvicornAppResource
api) .ExecutableResource.waitFor(dependency: IResource | IResourceWithConnectionString, waitBehavior?: WaitBehavior): ViteAppResource
Waits for another resource to be ready
waitFor(const api: UvicornAppResource
api);
await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();#:package Aspire.Hosting.AppHost@17.0.0#:package Aspire.Hosting.Redis@17.0.0#:package Aspire.Hosting.Python@17.0.0#:package Aspire.Hosting.JavaScript@17.0.0
var builder = DistributedApplication.CreateBuilder(args);
var cache = builder.AddRedis("cache");
var api = builder.AddUvicornApp("api", "../services/api", "main:app") .WithUv() .WithReference(cache) .WithExternalHttpEndpoints();
var worker = builder.AddPythonApp("worker", "../workers/inventory-sync", "worker.py") .WithReference(cache);
var web = builder.AddViteApp("web", "../services/web") .WithReference(api) .WaitFor(api);
builder.Build().Run();package main
import ( "log"
"apphost/modules/aspire")
func main() { builder, err := aspire.CreateBuilder() if err != nil { log.Fatal(aspire.FormatError(err)) }
cache := builder.AddRedis("cache")
api := builder.AddUvicornApp("api", "../services/api", "main:app"). WithUv(). WithReference(cache). WithExternalHttpEndpoints()
builder.AddPythonApp("worker", "../workers/inventory-sync", "worker.py"). WithReference(cache)
builder.AddViteApp("web", "../services/web"). WithReference(api). WaitFor(api)
app, err := builder.Build() if err != nil { log.Fatal(aspire.FormatError(err)) } if err := app.Run(); err != nil { log.Fatal(aspire.FormatError(err)) }}If a workload does not have a dedicated hosting API yet, model it as an executable resource with AddExecutableaddExecutableAddExecutable so it can still participate in the same application model.
For first-class workload guidance, see JavaScript integration, Python integration, and Multi-language architecture.
Scenario: Existing containers and shared infrastructure
Section titled “Scenario: Existing containers and shared infrastructure”Use this approach when the important boundary is the runtime environment itself: a published container image, a shared database, a cache, a queue, or an existing infrastructure topology. Model the shared resources first, then attach the workloads that consume them so connectivity, configuration, and startup order are explicit.
When Aspire has a first-class integration for that infrastructure, add it first:
aspire add postgresaspire add redisUse AddContaineraddContainerAddContainer for the published application images and WithHttpEndpointwithHttpEndpointWithHttpEndpoint to configure their HTTP endpoints:
import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
builder = await function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const db: PostgresDatabaseResource
db = (await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addPostgres(name: string, options?: { userName?: string | ParameterResource; password?: string | ParameterResource; port?: number;}): PostgresServerResource (+1 overload)
Adds a PostgreSQL resource to the application model. A container is used for local development.
addPostgres('postgres')).PostgresServerResource.addDatabase(name: string, options?: { databaseName?: string;} | undefined): PostgresDatabaseResource (+1 overload)
Adds a PostgreSQL database to the application model.
addDatabase('orders');
const const cache: RedisResource
cache = await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addRedis(name: string, options?: { port?: number; password?: string | ParameterResource;}): RedisResource (+1 overload)
Adds a Redis container to the application model.
addRedis('cache');
const const api: ContainerResource
api = await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addContainer(name: string, image: string | AddContainerOptions): ContainerResource
Adds a container resource to the application.
addContainer('api', { AddContainerOptions.image?: string | undefined
image: 'ghcr.io/contoso/orders-api', AddContainerOptions.tag?: string | undefined
tag: 'latest' }) .ContainerResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): ContainerResource (+1 overload)
Adds a reference to another resource
withReference(const db: PostgresDatabaseResource
db) .ContainerResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): ContainerResource (+1 overload)
Adds a reference to another resource
withReference(const cache: RedisResource
cache) .ContainerResource.withHttpEndpoint(options?: { port?: number; targetPort?: number; name?: string; env?: string; isProxied?: boolean;} | undefined): ContainerResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ port?: number | undefined
port: 8080, targetPort?: number | undefined
targetPort: 8080, name?: string | undefined
name: 'http' });
await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addContainer(name: string, image: string | AddContainerOptions): ContainerResource
Adds a container resource to the application.
addContainer('web', { AddContainerOptions.image?: string | undefined
image: 'ghcr.io/contoso/orders-web', AddContainerOptions.tag?: string | undefined
tag: 'latest' }) .ContainerResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): ContainerResource (+1 overload)
Adds a reference to another resource
withReference(const api: ContainerResource
api) .ContainerResource.withHttpEndpoint(options?: { port?: number; targetPort?: number; name?: string; env?: string; isProxied?: boolean;} | undefined): ContainerResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ port?: number | undefined
port: 3000, targetPort?: number | undefined
targetPort: 3000, name?: string | undefined
name: 'http' });
await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();#:package Aspire.Hosting.AppHost@17.0.0#:package Aspire.Hosting.PostgreSQL@17.0.0#:package Aspire.Hosting.Redis@17.0.0
var builder = DistributedApplication.CreateBuilder(args);
var db = builder.AddPostgres("postgres") .AddDatabase("orders");
var cache = builder.AddRedis("cache");
var api = builder.AddContainer("api", "ghcr.io/contoso/orders-api:latest") .WithReference(db) .WithReference(cache) .WithHttpEndpoint(port: 8080, targetPort: 8080, name: "http");
var web = builder.AddContainer("web", "ghcr.io/contoso/orders-web:latest") .WithReference(api) .WithHttpEndpoint(port: 3000, targetPort: 3000, name: "http");
builder.Build().Run();package main
import ( "log"
"apphost/modules/aspire")
func main() { builder, err := aspire.CreateBuilder() if err != nil { log.Fatal(aspire.FormatError(err)) }
db := builder.AddPostgres("postgres"). AddDatabase("orders")
cache := builder.AddRedis("cache")
api := builder.AddContainer("api", "ghcr.io/contoso/orders-api:latest"). WithReference(db). WithReference(cache). WithHttpEndpoint(aspire.HttpEndpointPort(8080), aspire.HttpEndpointTargetPort(8080), aspire.HttpEndpointName("http"))
builder.AddContainer("web", "ghcr.io/contoso/orders-web:latest"). WithReference(api). WithHttpEndpoint(aspire.HttpEndpointPort(3000), aspire.HttpEndpointTargetPort(3000), aspire.HttpEndpointName("http"))
app, err := builder.Build() if err != nil { log.Fatal(aspire.FormatError(err)) } if err := app.Run(); err != nil { log.Fatal(aspire.FormatError(err)) }}Scenario: Docker Compose
Section titled “Scenario: Docker Compose”Use this scenario when Docker Compose already captures the shape of your system. Treat the Compose file as a map of workloads, shared infrastructure, exposed ports, and dependency edges that you want to restate in the AppHost.
The goal is not a line-by-line translation of every field, but a clearer resource model of the same relationships.
services: postgres: image: postgres:latest environment: - POSTGRES_PASSWORD=postgres - POSTGRES_DB=mydb ports: - "5432:5432"
api: build: ./api environment: - DATABASE_URL=postgres://postgres:postgres@postgres:5432/mydb depends_on: - postgres
web: build: ./web environment: - API_URL=http://api:8080 depends_on: - api#:package Aspire.Hosting.AppHost@17.0.0#:package Aspire.Hosting.PostgreSQL@17.0.0
var builder = DistributedApplication.CreateBuilder(args);
var db = builder.AddPostgres("postgres") .AddDatabase("mydb");
var api = builder.AddDockerfile("api", "./api") .WithReference(db) .WithHttpEndpoint(port: 8080, targetPort: 8080, name: "http");
var web = builder.AddDockerfile("web", "./web") .WithReference(api) .WithHttpEndpoint(port: 3000, targetPort: 3000, name: "http");
builder.Build().Run();import { function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';
const const builder: IDistributedApplicationBuilder
builder = await function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();
const const db: PostgresDatabaseResource
db = (await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.addPostgres(name: string, options?: { userName?: string | ParameterResource; password?: string | ParameterResource; port?: number;}): PostgresServerResource (+1 overload)
Adds a PostgreSQL resource to the application model. A container is used for local development.
addPostgres('postgres')).PostgresServerResource.addDatabase(name: string, options?: { databaseName?: string;} | undefined): PostgresDatabaseResource (+1 overload)
Adds a PostgreSQL database to the application model.
addDatabase('mydb');
const const api: ContainerResource
api = await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addDockerfile(name: string, contextPath: string, options?: { dockerfilePath?: string; stage?: string;}): ContainerResource (+1 overload)
Adds a Dockerfile to the application model that can be treated like a container resource.
addDockerfile('api', '../api') .ContainerResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): ContainerResource (+1 overload)
Adds a reference to another resource
withReference(const db: PostgresDatabaseResource
db) .ContainerResource.withHttpEndpoint(options?: { port?: number; targetPort?: number; name?: string; env?: string; isProxied?: boolean;} | undefined): ContainerResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ port?: number | undefined
port: 8080, targetPort?: number | undefined
targetPort: 8080, name?: string | undefined
name: 'http' });
await const builder: IDistributedApplicationBuilder
builder .IDistributedApplicationBuilder.addDockerfile(name: string, contextPath: string, options?: { dockerfilePath?: string; stage?: string;}): ContainerResource (+1 overload)
Adds a Dockerfile to the application model that can be treated like a container resource.
addDockerfile('web', '../web') .ContainerResource.withReference(source: IResource | EndpointReference | string | uri, options?: { connectionName?: string; optional?: boolean; name?: string;} | undefined): ContainerResource (+1 overload)
Adds a reference to another resource
withReference(const api: ContainerResource
api) .ContainerResource.withHttpEndpoint(options?: { port?: number; targetPort?: number; name?: string; env?: string; isProxied?: boolean;} | undefined): ContainerResource (+1 overload)
Adds an HTTP endpoint
withHttpEndpoint({ port?: number | undefined
port: 3000, targetPort?: number | undefined
targetPort: 3000, name?: string | undefined
name: 'http' });
await const builder: IDistributedApplicationBuilder
builder.IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();package main
import ( "log"
"apphost/modules/aspire")
func main() { builder, err := aspire.CreateBuilder() if err != nil { log.Fatal(aspire.FormatError(err)) }
db := builder.AddPostgres("postgres"). AddDatabase("mydb")
api := builder.AddDockerfile("api", "./api"). WithReference(db). WithHttpEndpoint(aspire.HttpEndpointPort(8080), aspire.HttpEndpointTargetPort(8080), aspire.HttpEndpointName("http"))
builder.AddDockerfile("web", "./web"). WithReference(api). WithHttpEndpoint(aspire.HttpEndpointPort(3000), aspire.HttpEndpointTargetPort(3000), aspire.HttpEndpointName("http"))
app, err := builder.Build() if err != nil { log.Fatal(aspire.FormatError(err)) } if err := app.Run(); err != nil { log.Fatal(aspire.FormatError(err)) }}These scenarios are starting points, not mutually exclusive modes. Most real apps mix workload-specific resources, containers, shared infrastructure, project-path references, and occasional custom commands in a single application model. The key is that dependencies, endpoints, configuration, and startup behavior become explicit.
For more examples, see .NET / C# apps in the AppHost, C# file-based apps, Executable resources, and Migrate from Docker Compose.
Add telemetry configuration (optional)
Section titled “Add telemetry configuration (optional)”Telemetry is configured inside the workloads that emit it, not in the AppHost itself. Aspire gives those workloads an OTLP destination and a shared dashboard during local orchestration, but each service still uses the observability libraries that fit its runtime.
If your app includes Node.js or TypeScript services, configure OpenTelemetry inside the service and point it at the Aspire OTLP endpoint.
-
Install the OpenTelemetry packages:
Install OpenTelemetry packages npm install @opentelemetry/api @opentelemetry/sdk-node \@opentelemetry/auto-instrumentations-node \@opentelemetry/exporter-trace-otlp-grpc \@opentelemetry/exporter-metrics-otlp-grpc -
Create a telemetry bootstrap file:
telemetry.ts import { NodeSDK } from '@opentelemetry/sdk-node';import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';const sdk = new NodeSDK({instrumentations: [getNodeAutoInstrumentations()],});sdk.start(); -
Import it first in your app entry point:
src/server.ts import './telemetry';import express from 'express';const app = express();
If your app includes C# services, ServiceDefaults is the standard way to add observability, resilience, and health checks.
-
Create a ServiceDefaults project and reference it from your service:
Add ServiceDefaults dotnet new aspire-servicedefaults -n YourProject.ServiceDefaultsdotnet sln add YourProject.ServiceDefaultsdotnet add YourProject reference YourProject.ServiceDefaults -
Update your service’s
Program.cs:Program.cs — Add ServiceDefaults var builder = WebApplication.CreateBuilder(args);builder.AddServiceDefaults();var app = builder.Build();app.MapDefaultEndpoints();app.Run();
For more information, see Service Defaults.
If your app includes Go services, configure OpenTelemetry inside the service and point it at the Aspire OTLP endpoint. When you add a Go service with AddGoApp, call WithOtlpExporter so Aspire passes the OTLP environment variables to it.
-
Install the OpenTelemetry packages:
Install OpenTelemetry packages go get go.opentelemetry.io/otel \go.opentelemetry.io/otel/sdk \go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc \go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp -
Create a telemetry bootstrap function:
telemetry.go package mainimport ("context""go.opentelemetry.io/otel""go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"sdktrace "go.opentelemetry.io/otel/sdk/trace")func setupTelemetry(ctx context.Context) (func(context.Context) error, error) {// The exporter reads OTEL_EXPORTER_OTLP_ENDPOINT, which Aspire sets for the service.exporter, err := otlptracegrpc.New(ctx)if err != nil {return nil, err}provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))otel.SetTracerProvider(provider)return provider.Shutdown, nil} -
Call it at startup and wrap your HTTP handler with
otelhttp:main.go shutdown, err := setupTelemetry(context.Background())if err != nil {log.Fatal(err)}defer shutdown(context.Background())http.ListenAndServe(":"+os.Getenv("PORT"), otelhttp.NewHandler(mux, "app"))
For other runtimes, use the OpenTelemetry SDK or instrumentation library that matches the runtime you are already using, then export telemetry to the OTLP endpoint Aspire provides during local orchestration.
Run and verify
Section titled “Run and verify”Once the AppHost captures the resources and relationships you care about, start everything together with the Aspire CLI.
-
From the directory that contains your AppHost, run:
Run your application with Aspire aspire run -
Wait for the CLI to discover the AppHost, launch the resources, and print the dashboard URL.
Example output Finding apphosts...Dashboard: https://localhost:17068/login?t=examplePress CTRL+C to stop the apphost and exit. -
Open the dashboard in your browser and verify:
- All resources start successfully
- Service dependencies appear in the expected order
- Logs, traces, and metrics are visible
- Endpoints and environment variables look correct
-
Exercise the actual app flows you care about, such as frontend-to-API calls, worker jobs, or database access.
-
Stop the system by pressing
⌃+C⌃+CControl + CCtrlCControl + CCtrlC in your terminal.
Next steps
Section titled “Next steps”At this point, you have the core workflow: describe the resources your app needs, connect the workloads that depend on them, and let Aspire run the system together during local development. From there, you can deepen the setup incrementally instead of trying to remodel the entire app at once.
- Learn more about Executable resources for custom commands and non-project workloads
- Follow Deploy your first app when you are ready to move beyond local orchestration
- Use the Aspire extension for VS Code to run and inspect your app from the editor
- Check the Troubleshooting guide for common setup issues
- Ask questions and share feedback on Discord