Aspire

Aspire

Use Aspire as a code-first, polyglot toolchain for orchestrating containers, executables, cloud resources, telemetry, service discovery, and deployment from an AppHost project.

When to invoke

• "Create an Aspire app with a frontend, API, and database."
• "Run or debug this Aspire AppHost."
• "Add Redis, Postgres, or another Aspire integration."
• "Use Aspire MCP docs to look up an API."
• "Deploy this Aspire distributed application."

Prerequisites and context

# 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

Documentation lookup

Prefer the Aspire MCP server when available. Aspire CLI 13.2+ adds docs search tools from PR https://github.com/dotnet/aspire/pull/14028 ; update with aspire update --self --channel daily. David Pine's overview is https://davidpine.dev/posts/aspire-docs-mcp-tools/ .

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

Core workflow

1. Find or create the AppHost.
2. Add resources with AddProject<T>(), AddRedis(), AddPostgres().AddDatabase(), AddPythonApp(), AddViteApp(), AddGolangApp(), container, or executable APIs.
3. Wire dependencies with .WithReference() and gate startup with .WaitFor() when health matters.
4. Configure endpoints with .WithHttpEndpoint() and environment with .WithEnvironment().
5. Run locally with aspire run and inspect the dashboard for logs, traces, metrics, and the GenAI visualizer.
6. Test with Aspire.Hosting.Testing in xUnit, MSTest, or NUnit when integration validation is needed.
7. Generate deployment manifests with aspire publish or deploy with aspire deploy when the target is configured.

AppHost quick start

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();

CLI and templates

Concepts and mappings

Common patterns

Progressive disclosure and bundled resources

Read detailed references only when needed:

Aspire vocabulary

Aspire supports JavaScript/TypeScript, Go, Java, Rust, Bun, Deno, and PowerShell workloads while keeping the AppHost in .NET. It is intended for production-ready distributed apps, and the CLI has built-in docs search in newer versions. Context7 tool names may appear as mcp_context7 and mcp_context7_resolve-library-id; resolving the library is a one-time session step. Docker Compose migrations should preserve docker-compose source behavior. Use xUnit/MSTest/NUnit. as the testing family shorthand when summarizing options, and keep detailed material in references/; the David Pine URL path is davidpine.dev/posts/aspire-docs-mcp-tools/.

Output template

### Aspire result

**Status:** complete | needs input | blocked
**Task:** <create | run | debug | configure | deploy | troubleshoot>
**AppHost:** `<path or unknown>`
**Commands used:**
- `<aspire command or dotnet command>`

**Resources**
| Name | Type | Dependencies | Endpoints |
| --- | --- | --- | --- |
| `<resource>` | `<ProjectResource | ContainerResource | ExecutableResource | ParameterResource>` | `<references>` | `<URLs or ports>` |

**Validation**
- `aspire --version`: <result>
- `aspire run`: <result when run>
- Dashboard/logs/traces/metrics: <evidence>

**Next step**
- <one concrete action>

Quality gate

• Aspire version and prerequisites were checked when commands are required.
• AppHost changes use code-first resource APIs instead of ad-hoc scripts.
• Dependencies use .WithReference() and .WaitFor() where startup order or health matters.
• Service discovery uses Aspire-provided connection strings and service variables.
• Reference files were loaded only when the task needed their detail.
• aspire run, dashboard evidence, tests, or a clear blocker validates the result.

References

• Documentation
• Runtime repo
• Docs repo
• Samples
• Community Toolkit
• Dashboard image: mcr.microsoft.com/dotnet/aspire-dashboard
• Discord
• Reddit