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

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.

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/