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. The AppHost can be written in C# (all versions) or TypeScript (preview in 13.2/13.3, GA in 13.4).

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

References

Agent Safety Guardrails

When an AI agent drives Aspire, these rules prevent self-inflicted breakage. They apply to every Aspire task — read them before acting.

See the consolidated lifecycle tips in §7 Common Patterns and the per-version scrub list in Migration.

Detecting an Aspire workspace

Confirm it's an Aspire app before applying these rules:

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), docs are accessible via both MCP tools and CLI commands:

MCP tools (when MCP server is running):

CLI commands (work without MCP server):

These tools were added in PR #14028.

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:

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

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

13.3+ alternative install: with the .NET 10 SDK present, install the CLI as a NativeAOT .NET global tool: dotnet tool install -g Aspire.Cli.

13.5: also available via package managers — npm install -g @microsoft/aspire-cli, brew install --cask microsoft/aspire/aspire, winget install Microsoft.Aspire, or Nix (nix profile add github:microsoft/aspire#aspire-cli). New C# AppHost templates set AspireUseCliBundle=true so dotnet run resolves the CLI on the fly via dnx.

3. Project Templates

4. AppHost Quick Start

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

C# AppHost (all versions)

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) — AddViteApp auto-registers its http endpoint (PORT)
var web = builder.AddViteApp("web", "../frontend")
    .WithReference(api);

// Go worker (official Aspire.Hosting.Go package, 13.4+)
var worker = builder.AddGoApp("worker", "../go-worker")
    .WithReference(redis);

builder.Build().Run();

TypeScript AppHost (GA in 13.4; preview in 13.2/13.3)

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();
const cache = await builder.addRedis("cache");
const postgres = await builder.addPostgres("pg").addDatabase("catalog");
const api = await builder.addProject("api", "../api")
    .withReference(postgres).withReference(cache);
const web = await builder.addViteApp("web", "../frontend")
    .withReference(api);   // addViteApp auto-registers its http endpoint (PORT)
await builder.build().run();

TypeScript AppHost uses aspire.config.json for discovery (no .csproj); the orchestrator file is apphost.mts. Run aspire add to generate TypeScript SDKs into .aspire/modules/, and aspire restore to regenerate after upgrades. See Polyglot APIs for full details.

For complete API signatures, see Polyglot APIs.

5. Core Concepts (Summary)

6. CLI Quick Reference

Aspire CLI 13.2+ (recommended)

Most commands support --format Json for machine-readable output. Use --apphost <path> to target a specific AppHost.

Aspire CLI 13.1 (legacy)

On 13.1, the following 13.2+ commands are not available: start, stop, wait, describe, resources, resource, logs, otel, ps, doctor, docs, export, secret, certs, mcp tools, mcp call, restore. Use aspire run (foreground, Ctrl+C to stop) and the MCP tools or dashboard for resource inspection.

All other commands (aspire new, aspire init, aspire add, aspire publish, aspire config, aspire cache, aspire deploy, aspire do, aspire update) work the same on 13.1.

Full command reference with flags: CLI Reference.

7. Common Patterns

Running and debugging (13.2+)

1. Start the app: aspire start (or aspire start --isolated in worktrees)
2. Wait for resource: aspire wait <resource>
3. Check status: aspire describe
4. View structured logs: aspire otel logs <resource>
5. View console logs: aspire logs <resource>
6. View traces: aspire otel traces <resource>
7. To restart after changes: just run aspire start again (auto-stops previous)

Important rules

• Always start the app first (aspire start) before making changes to verify the starting state.
• To restart, just run aspire start again — it automatically stops the previous instance. NEVER use aspire stop then aspire run. NEVER use aspire run at all (13.2+).
• Use --isolated when working in a worktree.
• Avoid persistent containers early in development to prevent state management issues.
• Never install the Aspire workload — it is obsolete.
• Prefer aspire.dev and learn.microsoft.com/dotnet/aspire for official documentation.

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. Start: aspire start (13.2+) or aspire run (13.1)

Adding integrations

Discover hosting integrations with aspire integration list / aspire integration search <query> (13.4+), and use aspire docs search (13.2+) → aspire docs get to read the full guide. Use aspire add (or aspire integration add <integration>) to install the integration package. Restart with aspire start for the new resource to take effect.

Using resource MCP tools (13.2+)

Some resources expose MCP tools (e.g., WithPostgresMcp() adds SQL query tools). Discover and call them via CLI:

aspire mcp tools                                              # list available tools
aspire mcp tools --format Json                                # includes input schemas
aspire mcp call <resource> <tool> --input '{"key":"value"}'   # invoke a tool

Migrating from Docker Compose

1. aspire new aspire-empty (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