Working with .NET Aspire 13

For AI Assistants: Use MCP Tools

CRITICAL: When helping users debug Aspire applications, use the Aspire MCP tools instead of curl, external HTTP calls, or suggesting manual dashboard inspection.

Task MCP Tool NOT This

Check resource status list_resources

❌ curl to dashboard API

Get service logs list_console_logs

❌ curl, docker logs

View traces list_traces

❌ curl to OTLP endpoint

Find errors in traces list_trace_structured_logs

❌ manual dashboard search

List available AppHosts list_apphosts

❌ file system search

If MCP is not configured, guide the user to run aspire mcp init in their AppHost directory.

Quick Reference

Task Reference File

AppHost patterns, resources, lifecycle app-host.md

Azure integrations (databases, messaging, AI) azure-integrations.md

Database integrations (Postgres, SQL, Mongo) database-integrations.md

Caching (Redis, Valkey, Garnet) caching-integrations.md

Messaging (Kafka, RabbitMQ, NATS) messaging-integrations.md

Polyglot (Node.js, Python, Go, Rust, Java) polyglot-integrations.md

Deployment, CLI, and aspire do pipelines deployment-cli.md

Testing with Aspire testing.md

Errors and troubleshooting diagnostics.md

MCP integration for AI assistants mcp-integration.md

VS Code extension vs-code-extension.md

Certificate trust configuration certificate-config.md

Migration from 9.x to 13.x aspire-13-migration.md

Common Mistakes

❌ Wrong: Using non-existent or deprecated APIs

Wrong Correct Why

AddPythonUvicornApp

AddUvicornApp

Method is just AddUvicornApp

AddNpmApp

AddViteApp or AddJavaScriptApp

AddNpmApp removed in 13.0

AddPythonApp for FastAPI AddUvicornApp

Use AddUvicornApp for ASGI (FastAPI, Starlette)

Aspire.Hosting.NodeJs

Aspire.Hosting.JavaScript

Package renamed in 13.0

❌ Wrong: Putting secrets in appsettings.json

// WRONG - secrets exposed in source control // appsettings.json: { "Parameters": { "api-key": "secret123" } }

// CORRECT - use user-secrets for development // dotnet user-secrets set "Parameters:api-key" "secret123"

Aspire 13 Breaking Changes

Critical: Migration from Aspire 9.x requires attention. See aspire-13-migration.md for full details.

JavaScript/Node.js Changes (13.0)

// BEFORE (9.x) - REMOVED IN 13.0 builder.AddNpmApp("frontend", "../app", scriptName: "dev", args: ["--no-open"])

// AFTER (13.0) - Use AddJavaScriptApp or AddViteApp builder.AddJavaScriptApp("frontend", "../app") .WithRunScript("dev") .WithArgs("--no-open");

// For Vite/React specifically: builder.AddViteApp("frontend", "../app") .WithHttpEndpoint(env: "PORT");

// Package renamed: Aspire.Hosting.NodeJs → Aspire.Hosting.JavaScript

Azure Redis Changes (13.1)

// BEFORE (13.0) - DEPRECATED builder.AddAzureRedisEnterprise("cache")

// AFTER (13.1) builder.AddAzureManagedRedis("cache")

Network Context Changes (13.0)

// BEFORE (9.x) - containerHostName parameter removed await resource.ProcessArgumentValuesAsync( executionContext, processValue, logger, containerHostName: "localhost", cancellationToken);

// AFTER (13.0) - Use NetworkIdentifier await resource.ProcessArgumentValuesAsync( executionContext, processValue, logger, cancellationToken);

// Get endpoints with network context var endpoint = api.GetEndpoint("http", KnownNetworkIdentifiers.DefaultAspireContainerNetwork);

Publishing API Changes (13.0)

// BEFORE (9.x) public class MyPublisher : IDistributedApplicationPublisher { }

// AFTER (13.0) - Use aspire do pipelines instead // IDistributedApplicationPublisher is deprecated

Aspire 13.0+ New Features

Certificate Trust Automation

// Automatic - no configuration needed var pythonApi = builder.AddUvicornApp("api", "./api", "main:app"); var nodeApi = builder.AddJavaScriptApp("frontend", "./frontend"); // Both automatically trust development certificates

MCP Integration for AI Assistants

Initialize MCP for Claude Code, GitHub Copilot, etc.

aspire mcp init

aspire do Pipeline System

aspire do build # Build container images aspire do push # Push to registry aspire do deploy # Full deployment aspire do diagnostics # Show available steps

aspire init (Aspirify Existing Projects)

aspire init # Interactive setup aspire init --single-file # Create .cs AppHost without .csproj

Single-File AppHost

// apphost.cs - no project file needed #:package Aspire.Hosting@* #:package Aspire.Hosting.Redis@*

var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis("cache"); builder.Build().Run();

Common Patterns

FastAPI + React (Vite) Full Stack

// Required packages: // dotnet add package Aspire.Hosting.Python // dotnet add package Aspire.Hosting.JavaScript (NOT NodeJs!) // dotnet add package Aspire.Hosting.PostgreSQL

var builder = DistributedApplication.CreateBuilder(args);

// Database var db = builder.AddPostgres("db") .AddDatabase("appdata") .WithDataVolume();

// FastAPI backend - use AddUvicornApp (NOT AddPythonApp!) var api = builder.AddUvicornApp("api", "../api", "main:app") .WithHttpEndpoint(port: 8000, env: "PORT") .WithReference(db) .WaitFor(db);

// React frontend - use AddViteApp (NOT AddNpmApp!) builder.AddViteApp("frontend", "../frontend") .WithHttpEndpoint(env: "PORT") .WithExternalHttpEndpoints() .WithReference(api);

builder.Build().Run();

Frontend reads API URL from env: process.env.services__api__http__0

Basic AppHost Structure

var builder = DistributedApplication.CreateBuilder(args);

// Database var db = builder.AddPostgres("db") .AddDatabase("appdata") .WithDataVolume();

// API with database reference var api = builder.AddProject<Projects.Api>("api") .WithReference(db) .WaitFor(db);

// Frontend with API reference builder.AddViteApp("frontend", "../frontend") .WithHttpEndpoint(env: "PORT") .WithReference(api);

builder.Build().Run();

Service Discovery Pattern

// Producer exposes endpoint var api = builder.AddProject<Projects.Api>("api") .WithHttpEndpoint(port: 5000, name: "api");

// Consumer references it (gets services__api__api__0 env var) builder.AddProject<Projects.Web>("web") .WithReference(api);

Health Checks and Wait

var db = builder.AddPostgres("db"); var cache = builder.AddRedis("cache");

builder.AddProject<Projects.Api>("api") .WithReference(db) .WithReference(cache) .WaitFor(db) // Wait for running .WaitForHealthy(cache); // Wait for healthy (requires health check)

When to Read Specific Files

Read app-host.md when:

• Setting up new AppHost project

• Understanding resource lifecycle events

• Configuring endpoints and networking

• Using parameters and secrets

Read azure-integrations.md when:

• Using Azure services (Cosmos, Service Bus, Storage)

• Running Azure emulators locally

• Using RunAsEmulator() or RunAsContainer()

• Customizing Bicep output

Read polyglot-integrations.md when:

• Adding Node.js, Python, Go, Rust, or Java apps

• Frontend frameworks (Vite, Angular, React)

• Container-based polyglot services

• Migrating from AddNpmApp to AddJavaScriptApp

Read deployment-cli.md when:

• Using aspire deploy , aspire publish , or aspire do

• Using aspire init to Aspirify existing projects

• Setting up CI/CD pipelines

• Understanding manifest format

Read mcp-integration.md when:

• Setting up AI assistant integration

• Configuring Claude Code, GitHub Copilot, or Cursor

• Excluding resources from MCP access

Read vs-code-extension.md when:

• Using Aspire in VS Code

• Debugging polyglot applications

• Creating new Aspire projects in VS Code

Read certificate-config.md when:

• Configuring HTTPS for polyglot apps

• Custom certificate authorities

• Certificate trust issues between services

Read aspire-13-migration.md when:

• Upgrading from Aspire 9.x

• Seeing deprecated API warnings

• Container networking issues after upgrade

Read diagnostics.md when:

• Seeing ASPIRE* compiler errors

• Debugging service discovery issues

• Troubleshooting container startup