Skip to content
Aspire
Docs Try Aspire
Docs Try

Install Aspire CLI

macOS

curl -sSL https://aspire.dev/install.sh | bash

Linux

curl -sSL https://aspire.dev/install.sh | bash

Windows

irm https://aspire.dev/install.ps1 | iex
More installation options

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”
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.

  1. Run aspire init in your repo root:

    Initialize Aspire
    aspire init

    Choose your AppHost language (C# or TypeScript) when prompted, or pass --language csharp / --language typescript. The command creates a minimal AppHost file, an aspire.config.json, and installs the aspireify skill into your agent’s skill directory.

  2. Ask your AI coding agent to run the aspireify skill. 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 WithReference, WaitFor, endpoints, and volumes
    • Add ServiceDefaults and configure OpenTelemetry for each service
    • Validate the setup by running aspire start

  3. Once the agent reports success, run aspire start yourself 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.

Aspire offers two C# AppHost styles:

File-based AppHost — a single apphost.cs file that uses #:sdk and #:package directives. No .csproj, no solution integration required. Best for polyglot repos or quick setups.

Project-based AppHost — a traditional AppHost.csproj that lives inside a .sln alongside your other C# projects. Uses ProjectReference items and the generated Projects namespace for strongly-typed AddProject<T>() calls. Best when your repo is already a .NET solution and you want IDE-integrated orchestration.

Both styles use the same Aspire.AppHost.Sdk and the same hosting APIs.

Set up your AppHost

Section titled “Set up your AppHost”

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.

  1. Run aspire init from your repo root. Without a .sln present, it creates a file-based apphost.cs:

    Initialize Aspire with a file-based AppHost
    aspire init

  2. Add hosting integrations:

    Add hosting integrations
    aspire add redis

  3. Wire the resources in apphost.cs:

    apphost.cs
    #:sdk Aspire.AppHost.Sdk@13.2.0
    #:package Aspire.Hosting.Redis@13.2.0
    

    #pragma warning disable ASPIRECSHARPAPPS001
    

    var builder = DistributedApplication.CreateBuilder(args);
    

    var cache = builder.AddRedis("cache");
    

    var api = builder.AddCSharpApp("api", "./src/Api/MyApp.Api.csproj")
        .WithReference(cache)
        .WithHttpHealthCheck("/health");
    

    var worker = builder.AddCSharpApp("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 uses ProjectReference items and the generated Projects namespace for strongly-typed AddProject<T>() calls, giving you full IDE support including IntelliSense, refactoring, and build-order awareness.

  1. Run aspire init from your solution root. It detects the .sln and creates a project-based AppHost automatically:

    Initialize Aspire in a .NET solution
    aspire init

  2. Add project references from the AppHost to each service you want to orchestrate:

    Add project references
    dotnet add MyApp.AppHost reference src/Api/MyApp.Api.csproj
    dotnet add MyApp.AppHost reference src/Web/MyApp.Web.csproj
    dotnet add MyApp.AppHost reference src/Worker/MyApp.Worker.csproj

  3. Add hosting integrations:

    Add hosting integrations
    aspire add redis
    aspire add postgres

  4. Wire the resources in the AppHost’s Program.cs:

    MyApp.AppHost/Program.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.AddProject<Projects.MyApp_Api>("api")
        .WithReference(db)
        .WithReference(cache)
        .WaitFor(db);
    

    builder.AddProject<Projects.MyApp_Web>("web")
        .WithReference(api)
        .WaitFor(api);
    

    builder.AddProject<Projects.MyApp_Worker>("worker")
        .WithReference(cache)
        .WithReference(db);
    

    builder.Build().Run();

After setup, a typical solution layout looks like this:

  • MyApp.sln
  • DirectoryMyApp.AppHost/
    • MyApp.AppHost.csproj
    • Program.cs
  • DirectoryMyApp.ServiceDefaults/
    • MyApp.ServiceDefaults.csproj
    • Extensions.cs
  • Directorysrc/
    • DirectoryApi/
      • MyApp.Api.csproj
    • DirectoryWeb/
      • MyApp.Web.csproj
    • DirectoryWorker/
      • MyApp.Worker.csproj

For the full AddProject workflow including custom type names, multi-project solutions, and launch profiles, see Project resources.

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.

apphost.cs — Existing services with hosting integrations
#:sdk Aspire.AppHost.Sdk@13.3.0
#:package Aspire.Hosting.Redis@13.3.0
#:package Aspire.Hosting.Python@13.3.0
#:package Aspire.Hosting.JavaScript@13.3.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();

If a workload does not have a dedicated hosting API yet, model it as an executable resource with AddExecutable or addExecutable 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:

Add hosting integrations
aspire add postgres
aspire add redis
apphost.cs — Existing containers and shared infrastructure
#:sdk Aspire.AppHost.Sdk@13.3.0
#:package Aspire.Hosting.PostgreSQL@13.3.0
#:package Aspire.Hosting.Redis@13.3.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();

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.

docker-compose.yml
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

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 Project resources, 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 C# services, ServiceDefaults is the standard way to add observability, resilience, and health checks.

  1. Create a ServiceDefaults project and reference it from your service:

    Add ServiceDefaults
    dotnet new aspire-servicedefaults -n YourProject.ServiceDefaults
    dotnet sln add YourProject.ServiceDefaults
    dotnet add YourProject reference YourProject.ServiceDefaults

  2. 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.

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.

  1. From the directory that contains your AppHost, run:

    Run your application with Aspire
    aspire run

  2. 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=example
    

    Press CTRL+C to stop the apphost and exit.

  3. 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

  4. Exercise the actual app flows you care about, such as frontend-to-API calls, worker jobs, or database access.

  5. Stop the system by pressing ⌃+C Control + C Control + C 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.

Connect with us

Community

SHA — 96184d4 © Microsoft