aspire

by github

Code-first orchestration for polyglot distributed apps with automatic service discovery and observability. Orchestrates containers, executables, and cloud resources (C#, Python, JavaScript, Go, Java, Rust, and more) from a single .NET AppHost project Includes 144+ integrations across databases, caches, messaging, AI, and observability platforms with automatic environment variable injection for service discovery Built-in dashboard provides real-time logs, traces, metrics, and GenAI... npx skills add https://github.com/github/awesome-copilot --skill aspire Download ZIPGitHub36.2k

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 Command flags, options, or detailed usage MCP Server Setting up MCP for AI assistants, available tools Integrations Catalog Discovering integrations via MCP tools, wiring patterns Polyglot APIs Method signatures, chaining options, language-specific patterns Architecture DCP internals, resource model, service discovery, networking, telemetry Dashboard Dashboard features, standalone mode, GenAI Visualizer Deployment Docker, Kubernetes, Azure Container Apps, App Service Testing Integration tests against the AppHost Troubleshooting 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 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

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

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.

7. Common Patterns

Adding a new service

• Create your service directory (any language)

• Add to AppHost: Add*App() or AddProject<T>()

• Wire dependencies: .WithReference()

• Gate on health: .WaitFor() if needed

• Run: aspire run

Migrating from Docker Compose

• aspire new aspire-apphost-singlefile (empty AppHost)

• Replace each docker-compose service with an Aspire resource

• depends_on → .WithReference() + .WaitFor()

• ports → .WithHttpEndpoint()

• 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/