aspire

Aspire — Polyglot Distributed-App Orchestration

Aspire is a code-first, polyglot toolchain for building observable, production-ready distributed applications. It orchestrates containers, executables, and cloud resources from a single AppHost project — regardless of whether the workloads are C#, Python, JavaScript/TypeScript, Go, Java, Rust, Bun, Deno, or PowerShell.

> Mental model: The AppHost is a conductor — it doesn't play the instruments, it tells every service when to start, how to find each other, and watches for problems.

Detailed reference material lives in the references/ folder — load on demand.

---

References

| Reference | When to load |

|---|---|

| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |

| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |

| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |

| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |

| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |

| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |

| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |

| [Testing](references/testing.md) | Integration tests against the AppHost |

| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |

---

1. Researching Aspire Documentation

The Aspire team ships an MCP server that provides documentation tools directly inside your AI assistant. See [MCP Server](references/mcp-server.md) for setup details.

Aspire CLI 13.2+ (recommended — has built-in docs search)

If running Aspire CLI 13.2 or later (aspire --version), the MCP server includes docs search tools:

| Tool | Description |

|---|---|

| list_docs | Lists all available documentation from aspire.dev |

| search_docs | Performs weighted lexical search across indexed documentation |

| get_doc | Retrieves a specific document by its slug |

These tools were added in PR #14028. To update: aspire update --self --channel daily.

For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/

Aspire CLI 13.1 (integration tools only)

On 13.1, the MCP server provides integration lookup but not docs search:

| Tool | Description |

|---|---|

| list_integrations | Lists available Aspire hosting integrations |

| get_integration_docs | Gets documentation for a specific integration package |

For general docs queries on 13.1, use Context7 as your primary source (see below).

Fallback: Context7

Use Context7 (mcp_context7) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:

Step 1 — Resolve the library ID (one-time per session):

Call mcp_context7_resolve-library-id with libraryName: ".NET Aspire".

| Rank | Library ID | Use when |

|---|---|---|

| 1 | /microsoft/aspire.dev | Primary source. Guides, integrations, CLI reference, deployment. |

| 2 | /dotnet/aspire | API internals, source-level implementation details. |

| 3 | /communitytoolkit/aspire | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |

Step 2 — Query docs:

libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"

Fallback: GitHub search (when Context7 is also unavailable)

Search the official docs repo on GitHub:

• Docs repo: microsoft/aspire.dev — path: src/frontend/src/content/docs/
• Source repo: dotnet/aspire
• Samples repo: dotnet/aspire-samples
• Community integrations: CommunityToolkit/Aspire

---

2. Prerequisites & Install

| Requirement | Details |

|---|---|

| .NET SDK | 10.0+ (required even for non-.NET workloads — the AppHost is .NET) |

| Container runtime | Docker Desktop, Podman, or Rancher Desktop |

| IDE (optional) | VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider |

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

# Windows PowerShell
irm https://aspire.dev/install.ps1 | iex

# Verify
aspire --version

# Install templates
dotnet new install Aspire.ProjectTemplates

---

3. Project Templates

| Template | Command | Description |

|---|---|---|

| aspire-starter | aspire new aspire-starter | ASP.NET Core/Blazor starter + AppHost + tests |

| aspire-ts-cs-starter | aspire new aspire-ts-cs-starter | ASP.NET Core/React starter + AppHost |

| aspire-py-starter | aspire new aspire-py-starter | FastAPI/React starter + AppHost |

| aspire-apphost-singlefile | aspire new aspire-apphost-singlefile | Empty single-file AppHost |

---

4. AppHost Quick Start (Polyglot)

The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure
var redis = builder.AddRedis("cache");
var postgres = builder.AddPostgres("pg").AddDatabase("catalog");

// .NET API
var api = builder.AddProject<Projects.CatalogApi>("api")
    .WithReference(postgres).WithReference(redis);

// Python ML service
var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
    .WithHttpEndpoint(targetPort: 8000).WithReference(redis);

// React frontend (Vite)
var web = builder.AddViteApp("web", "../frontend")
    .WithHttpEndpoint(targetPort: 5173).WithReference(api);

// Go worker
var worker = builder.AddGolangApp("worker", "../go-worker")
    .WithReference(redis);

builder.Build().Run();

For complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).

---

5. Core Concepts (Summary)

| Concept | Key point |

|---|---|

| Run vs Publish | aspire run = local dev (DCP engine). aspire publish = generate deployment manifests. |

| Service discovery | Automatic via env vars: ConnectionStrings__<name>, services__<name>__http__0 |

| Resource lifecycle | DAG ordering — dependencies start first. .WaitFor() gates on health checks. |

| Resource types | ProjectResource, ContainerResource, ExecutableResource, ParameterResource |

| Integrations | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |

| Dashboard | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with aspire run. |

| MCP Server | AI assistants can query running apps and search docs via CLI (STDIO). |

| Testing | Aspire.Hosting.Testing — spin up full AppHost in xUnit/MSTest/NUnit. |

| Deployment | Docker, Kubernetes, Azure Container Apps, Azure App Service. |

---

6. CLI Quick Reference

Valid commands in Aspire CLI 13.1:

| Command | Description | Status |

|---|---|---|

| aspire new <template> | Create from template | Stable |

| aspire init | Initialize in existing project | Stable |

| aspire run | Start all resources locally | Stable |

| aspire add <integration> | Add an integration | Stable |

| aspire publish | Generate deployment manifests | Preview |

| aspire config | Manage configuration settings | Stable |

| aspire cache | Manage disk cache | Stable |

| aspire deploy | Deploy to defined targets | Preview |

| aspire do <step> | Execute a pipeline step | Preview |

| aspire update | Update integrations (or --self for CLI) | Preview |

| aspire mcp init | Configure MCP for AI assistants | Stable |

| aspire mcp start | Start the MCP server | Stable |

Full command reference with flags: [CLI Reference](references/cli-reference.md).

---

7. Common Patterns

Adding a new service

1. Create your service directory (any language)
2. Add to AppHost: Add*App() or AddProject<T>()
3. Wire dependencies: .WithReference()
4. Gate on health: .WaitFor() if needed
5. Run: aspire run

Migrating from Docker Compose

1. aspire new aspire-apphost-singlefile (empty AppHost)
2. Replace each docker-compose service with an Aspire resource
3. depends_on → .WithReference() + .WaitFor()
4. ports → .WithHttpEndpoint()
5. environment → .WithEnvironment() or .WithReference()

---

8. Key URLs

| Resource | URL |

|---|---|

| Documentation | https://aspire.dev |

| Runtime repo | https://github.com/dotnet/aspire |

| Docs repo | https://github.com/microsoft/aspire.dev |

| Samples | https://github.com/dotnet/aspire-samples |

| Community Toolkit | https://github.com/CommunityToolkit/Aspire |

| Dashboard image | mcr.microsoft.com/dotnet/aspire-dashboard |

| Discord | https://aka.ms/aspire/discord |

| Reddit | https://www.reddit.com/r/aspiredotdev/ |