Agent-Skills.md

Agent Skills: Working with .NET Aspire 13

Use when building distributed apps with Aspire; orchestrating .NET, JavaScript, Python, or polyglot services; when environment variables or service discovery aren't working; when migrating from .NET Aspire 9 to 13+ or Community Toolkit; when seeing AddNpmApp deprecated errors; when OTEL not appearing in dashboard; when ports change on restart breaking OAuth; when configuring MCP server for AI assistants; when debugging Aspire apps and need to check resource status or logs

UncategorizedID: mhagrelius/dotfiles/working-with-aspire

Repository

mhagrelius/dotfiles
mhagrelius

Install this agent skill to your local

pnpm dlx add-skill https://github.com/mhagrelius/dotfiles/tree/HEAD/.claude/skills/working-with-aspire

Skill Files

Browse the full folder contents for working-with-aspire.

Download Skill

Loading file tree…

.claude/skills/working-with-aspire/SKILL.md

Skill Metadata

Name
working-with-aspire
Description
Use when building distributed apps with Aspire; orchestrating .NET, JavaScript, Python, or polyglot services; when environment variables or service discovery aren't working; when migrating from .NET Aspire 9 to 13+ or Community Toolkit; when seeing AddNpmApp deprecated errors; when OTEL not appearing in dashboard; when ports change on restart breaking OAuth; when configuring MCP server for AI assistants; when debugging Aspire apps and need to check resource status or logs

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