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/

References

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

list_docs

search_docs

get_doc

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:

list_integrations

get_integration_docs

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

Fallback: Context7

Use Context7 (

mcp_context7

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

Call

mcp_context7_resolve-library-id

libraryName: ".NET Aspire"

/microsoft/aspire.dev

/dotnet/aspire

/communitytoolkit/aspire

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

# 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

aspire new aspire-starter

aspire new aspire-ts-cs-starter

aspire new aspire-py-starter

aspire new aspire-apphost-singlefile

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)

aspire run

aspire publish

ConnectionStrings__<name>

services__<name>__http__0

.WaitFor()

ProjectResource

ContainerResource

ExecutableResource

ParameterResource

aspire run

Aspire.Hosting.Testing

6. CLI Quick Reference

Valid commands in Aspire CLI 13.1:

aspire new <template>

aspire init

aspire run

aspire add <integration>

aspire publish

aspire config

aspire cache

aspire deploy

aspire do <step>

aspire update

--self

aspire mcp init

aspire mcp start

Full command reference with flags: CLI Reference.

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

mcr.microsoft.com/dotnet/aspire-dashboard