Aspire Dev

Aspire Skill

Orchestrate, monitor, and debug .NET Aspire distributed applications using the Aspire CLI and Aspire MCP tools.

Resources are defined in the AppHost project (Program.cs or AppHost.cs). The CLI manages the app lifecycle; the MCP tools provide real-time inspection from within the editor.

Aspire evolves rapidly. When unsure about an API or behavior, use mcp_aspire_search_docs or aspire docs search to check before guessing.

Quick reference — CLI commands

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

Full CLI reference → load references/cli-reference.md

Quick reference — MCP tools

Tools that do not require a running AppHost: mcp_aspire_doctor, mcp_aspire_list_integrations, mcp_aspire_search_docs, mcp_aspire_get_doc, mcp_aspire_list_docs.

Full MCP reference → load references/mcp-tools.md

Key workflows

Pre-flight check

Before starting the app for the first time, verify the environment:

mcp_aspire_doctor

This runs comprehensive checks (SDK version, container runtime, CLI version, etc.) and returns pass/warning/fail with actionable fix suggestions. Does not require a running AppHost.

If mcp_aspire_doctor is unavailable, use the CLI equivalent:

aspire doctor

Running in agent environments

Use aspire start to run the AppHost in the background. When working in a git worktree, use --isolated to avoid port conflicts:

aspire start --isolated

Use aspire wait <resource> to block until a resource is healthy before interacting with it:

aspire start --isolated
aspire wait myapi

Relaunching is safe — aspire start automatically stops any previous instance. Re-run aspire start whenever changes are made to the AppHost project.

Monitoring resources

Once running, use MCP or CLI interchangeably:

Debugging issues

Before making code changes, inspect the app state:

1. Check resource status — mcp_aspire_list_resources or aspire describe
2. View structured logs — mcp_aspire_list_structured_logs(resourceName=...) or aspire otel logs <resource>
3. View distributed traces — mcp_aspire_list_traces(resourceName=...) or aspire otel traces <resource>
4. Drill into trace logs — mcp_aspire_list_trace_structured_logs(traceId=...) or aspire otel logs --trace-id <id>
5. Fall back to console logs — mcp_aspire_list_console_logs(resourceName=...) or aspire logs <resource>

This top-down approach (status → structured logs → traces → trace logs → console logs) finds root causes efficiently.

Console logs can be extremely verbose. Never dump full console logs to the user. Read them, find the relevant parts, and summarize.

Adding integrations

1. Search for the integration: mcp_aspire_search_docs(query="redis integration") or aspire docs search redis
2. Read the docs: mcp_aspire_get_doc(slug="redis-integration") or aspire docs get redis-integration
3. Add the package: aspire add redis
4. Restart the app: aspire start (automatically stops previous instance)

For a catalog of available integrations: mcp_aspire_list_integrations or see references/integrations.md.

Multiple AppHosts

If the workspace contains multiple AppHost projects:

mcp_aspire_list_apphosts                                    # See all detected AppHosts
mcp_aspire_select_apphost(appHostPath="src/MyApp.AppHost")  # Select one

Or via CLI: aspire ps to list, --apphost <path> flag on any command to target a specific one.

Important rules

• Always verify the starting state before making changes — run mcp_aspire_doctor for environment checks, then aspire start and mcp_aspire_list_resources to confirm baseline health.
• To restart, just run aspire start again — it automatically stops the previous instance. NEVER chain aspire stop then aspire start.
• aspire start vs aspire run: aspire start runs in background (preferred for agents); aspire run runs in foreground (long-running, must be a background terminal process).
• 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. Use the Aspire CLI (dotnet tool install -g aspire).
• Prefer aspire.dev and learn.microsoft.com/dotnet/aspire for official documentation.
• Never print full console logs to the user — summarize the relevant parts.

Reference files

Load these on demand for deeper detail: