{"kind":"Skill","metadata":{"namespace":"community","name":"aspire","version":"0.1.0"},"spec":{"description":"Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.","files":{"SKILL.md":"---\nname: aspire\ndescription: 'Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.'\n---\n\n# Aspire — Polyglot Distributed-App Orchestration\n\nAspire 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.\n\n\u003e **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.\n\nDetailed reference material lives in the `references/` folder — load on demand.\n\n---\n\n## References\n\n| Reference | When to load |\n|---|---|\n| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |\n| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |\n| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |\n| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |\n| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |\n| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |\n| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |\n| [Testing](references/testing.md) | Integration tests against the AppHost |\n| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |\n\n---\n\n## 1. Researching Aspire Documentation\n\nThe Aspire team ships an **MCP server** that provides documentation tools directly inside your AI assistant. See [MCP Server](references/mcp-server.md) for setup details.\n\n### Aspire CLI 13.2+ (recommended — has built-in docs search)\n\nIf running Aspire CLI **13.2 or later** (`aspire --version`), the MCP server includes docs search tools:\n\n| Tool | Description |\n|---|---|\n| `list_docs` | Lists all available documentation from aspire.dev |\n| `search_docs` | Performs weighted lexical search across indexed documentation |\n| `get_doc` | Retrieves a specific document by its slug |\n\nThese tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028). To update: `aspire update --self --channel daily`.\n\nFor more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/\n\n### Aspire CLI 13.1 (integration tools only)\n\nOn 13.1, the MCP server provides integration lookup but **not** docs search:\n\n| Tool | Description |\n|---|---|\n| `list_integrations` | Lists available Aspire hosting integrations |\n| `get_integration_docs` | Gets documentation for a specific integration package |\n\nFor general docs queries on 13.1, use **Context7** as your primary source (see below).\n\n### Fallback: Context7\n\nUse **Context7** (`mcp_context7`) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:\n\n**Step 1 — Resolve the library ID** (one-time per session):\n\nCall `mcp_context7_resolve-library-id` with `libraryName: \".NET Aspire\"`.\n\n| Rank | Library ID | Use when |\n|---|---|---|\n| 1 | `/microsoft/aspire.dev` | Primary source. Guides, integrations, CLI reference, deployment. |\n| 2 | `/dotnet/aspire` | API internals, source-level implementation details. |\n| 3 | `/communitytoolkit/aspire` | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |\n\n**Step 2 — Query docs:**\n\n```\nlibraryId: \"/microsoft/aspire.dev\", query: \"Python integration AddPythonApp service discovery\"\nlibraryId: \"/communitytoolkit/aspire\", query: \"Golang Java Node.js community integrations\"\n```\n\n### Fallback: GitHub search (when Context7 is also unavailable)\n\nSearch the official docs repo on GitHub:\n- **Docs repo:** `microsoft/aspire.dev` — path: `src/frontend/src/content/docs/`\n- **Source repo:** `dotnet/aspire`\n- **Samples repo:** `dotnet/aspire-samples`\n- **Community integrations:** `CommunityToolkit/Aspire`\n\n---\n\n## 2. Prerequisites \u0026 Install\n\n| Requirement | Details |\n|---|---|\n| **.NET SDK** | 10.0+ (required even for non-.NET workloads — the AppHost is .NET) |\n| **Container runtime** | Docker Desktop, Podman, or Rancher Desktop |\n| **IDE (optional)** | VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider |\n\n```bash\n# Linux / macOS\ncurl -sSL https://aspire.dev/install.sh | bash\n\n# Windows PowerShell\nirm https://aspire.dev/install.ps1 | iex\n\n# Verify\naspire --version\n\n# Install templates\ndotnet new install Aspire.ProjectTemplates\n```\n\n---\n\n## 3. Project Templates\n\n| Template | Command | Description |\n|---|---|---|\n| **aspire-starter** | `aspire new aspire-starter` | ASP.NET Core/Blazor starter + AppHost + tests |\n| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | ASP.NET Core/React starter + AppHost |\n| **aspire-py-starter** | `aspire new aspire-py-starter` | FastAPI/React starter + AppHost |\n| **aspire-apphost-singlefile** | `aspire new aspire-apphost-singlefile` | Empty single-file AppHost |\n\n---\n\n## 4. AppHost Quick Start (Polyglot)\n\nThe AppHost orchestrates all services. Non-.NET workloads run as containers or executables.\n\n```csharp\nvar builder = DistributedApplication.CreateBuilder(args);\n\n// Infrastructure\nvar redis = builder.AddRedis(\"cache\");\nvar postgres = builder.AddPostgres(\"pg\").AddDatabase(\"catalog\");\n\n// .NET API\nvar api = builder.AddProject\u003cProjects.CatalogApi\u003e(\"api\")\n    .WithReference(postgres).WithReference(redis);\n\n// Python ML service\nvar ml = builder.AddPythonApp(\"ml-service\", \"../ml-service\", \"main.py\")\n    .WithHttpEndpoint(targetPort: 8000).WithReference(redis);\n\n// React frontend (Vite)\nvar web = builder.AddViteApp(\"web\", \"../frontend\")\n    .WithHttpEndpoint(targetPort: 5173).WithReference(api);\n\n// Go worker\nvar worker = builder.AddGolangApp(\"worker\", \"../go-worker\")\n    .WithReference(redis);\n\nbuilder.Build().Run();\n```\n\nFor complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).\n\n---\n\n## 5. Core Concepts (Summary)\n\n| Concept | Key point |\n|---|---|\n| **Run vs Publish** | `aspire run` = local dev (DCP engine). `aspire publish` = generate deployment manifests. |\n| **Service discovery** | Automatic via env vars: `ConnectionStrings__\u003cname\u003e`, `services__\u003cname\u003e__http__0` |\n| **Resource lifecycle** | DAG ordering — dependencies start first. `.WaitFor()` gates on health checks. |\n| **Resource types** | `ProjectResource`, `ContainerResource`, `ExecutableResource`, `ParameterResource` |\n| **Integrations** | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |\n| **Dashboard** | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run`. |\n| **MCP Server** | AI assistants can query running apps and search docs via CLI (STDIO). |\n| **Testing** | `Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit. |\n| **Deployment** | Docker, Kubernetes, Azure Container Apps, Azure App Service. |\n\n---\n\n## 6. CLI Quick Reference\n\nValid commands in Aspire CLI 13.1:\n\n| Command | Description | Status |\n|---|---|---|\n| `aspire new \u003ctemplate\u003e` | Create from template | Stable |\n| `aspire init` | Initialize in existing project | Stable |\n| `aspire run` | Start all resources locally | Stable |\n| `aspire add \u003cintegration\u003e` | Add an integration | Stable |\n| `aspire publish` | Generate deployment manifests | Preview |\n| `aspire config` | Manage configuration settings | Stable |\n| `aspire cache` | Manage disk cache | Stable |\n| `aspire deploy` | Deploy to defined targets | Preview |\n| `aspire do \u003cstep\u003e` | Execute a pipeline step | Preview |\n| `aspire update` | Update integrations (or `--self` for CLI) | Preview |\n| `aspire mcp init` | Configure MCP for AI assistants | Stable |\n| `aspire mcp start` | Start the MCP server | Stable |\n\nFull command reference with flags: [CLI Reference](references/cli-reference.md).\n\n---\n\n## 7. Common Patterns\n\n### Adding a new service\n\n1. Create your service directory (any language)\n2. Add to AppHost: `Add*App()` or `AddProject\u003cT\u003e()`\n3. Wire dependencies: `.WithReference()`\n4. Gate on health: `.WaitFor()` if needed\n5. Run: `aspire run`\n\n### Migrating from Docker Compose\n\n1. `aspire new aspire-apphost-singlefile` (empty AppHost)\n2. Replace each `docker-compose` service with an Aspire resource\n3. `depends_on` → `.WithReference()` + `.WaitFor()`\n4. `ports` → `.WithHttpEndpoint()`\n5. `environment` → `.WithEnvironment()` or `.WithReference()`\n\n---\n\n## 8. Key URLs\n\n| Resource | URL |\n|---|---|\n| **Documentation** | https://aspire.dev |\n| **Runtime repo** | https://github.com/dotnet/aspire |\n| **Docs repo** | https://github.com/microsoft/aspire.dev |\n| **Samples** | https://github.com/dotnet/aspire-samples |\n| **Community Toolkit** | https://github.com/CommunityToolkit/Aspire |\n| **Dashboard image** | `mcr.microsoft.com/dotnet/aspire-dashboard` |\n| **Discord** | https://aka.ms/aspire/discord |\n| **Reddit** | https://www.reddit.com/r/aspiredotdev/ |\n","references/architecture.md":"# Architecture — Deep Dive\n\nThis reference covers Aspire's internal architecture: the DCP engine, resource model, service discovery, networking, telemetry, and the eventing system.\n\n---\n\n## Developer Control Plane (DCP)\n\nThe DCP is the **runtime engine** that Aspire uses in `aspire run` mode. Key facts:\n\n- Written in **Go** (not .NET)\n- Exposes a **Kubernetes-compatible API server** (local only, not a real K8s cluster)\n- Manages resource lifecycle: create, start, health-check, stop, restart\n- Runs containers via the local container runtime (Docker, Podman, Rancher)\n- Runs executables as native OS processes\n- Handles networking via a proxy layer with automatic port assignment\n- Provides the foundation for the Aspire Dashboard's real-time data\n\n### DCP vs Kubernetes\n\n| Aspect | DCP (local dev) | Kubernetes (production) |\n|---|---|---|\n| API | Kubernetes-compatible | Full Kubernetes API |\n| Scope | Single machine | Cluster |\n| Networking | Local proxy, auto ports | Service mesh, ingress |\n| Storage | Local volumes | PVCs, cloud storage |\n| Purpose | Developer inner loop | Production deployment |\n\nThe Kubernetes-compatible API means Aspire understands the same resource abstractions, but DCP is **not** a Kubernetes distribution — it's a lightweight local runtime.\n\n---\n\n## Resource Model\n\nEverything in Aspire is a **resource**. The resource model is hierarchical:\n\n### Type hierarchy\n\n```\nIResource (interface)\n└── Resource (abstract base)\n    ├── ProjectResource          — .NET project reference\n    ├── ContainerResource        — Docker/OCI container\n    ├── ExecutableResource       — Native process (polyglot apps)\n    ├── ParameterResource        — Config value or secret\n    └── Infrastructure resources\n        ├── RedisResource\n        ├── PostgresServerResource\n        ├── MongoDBServerResource\n        ├── SqlServerResource\n        ├── RabbitMQServerResource\n        ├── KafkaServerResource\n        └── ... (one per integration)\n```\n\n### Resource properties\n\nEvery resource has:\n- **Name** — unique identifier within the AppHost\n- **State** — lifecycle state (Starting, Running, FailedToStart, Stopping, Stopped, etc.)\n- **Annotations** — metadata attached to the resource\n- **Endpoints** — network endpoints exposed by the resource\n- **Environment variables** — injected into the process/container\n\n### Annotations\n\nAnnotations are metadata bags attached to resources. Common built-in annotations:\n\n| Annotation | Purpose |\n|---|---|\n| `EndpointAnnotation` | Defines an HTTP/HTTPS/TCP endpoint |\n| `EnvironmentCallbackAnnotation` | Deferred env var resolution |\n| `HealthCheckAnnotation` | Health check configuration |\n| `ContainerImageAnnotation` | Docker image details |\n| `VolumeAnnotation` | Volume mount configuration |\n| `CommandLineArgsCallbackAnnotation` | Dynamic CLI arguments |\n| `ManifestPublishingCallbackAnnotation` | Custom publish behavior |\n\n### Resource lifecycle states\n\n```\nNotStarted → Starting → Running → Stopping → Stopped\n                 ↓                     ↓\n          FailedToStart           RuntimeUnhealthy\n                                       ↓\n                                  Restarting → Running\n```\n\n### DAG (Directed Acyclic Graph)\n\nResources form a dependency graph. Aspire starts resources in topological order:\n\n```\nPostgreSQL ──→ API ──→ Frontend\nRedis ────────↗\nRabbitMQ ──→ Worker\n```\n\n1. PostgreSQL, Redis, and RabbitMQ start first (no dependencies)\n2. API starts after PostgreSQL and Redis are healthy\n3. Frontend starts after API is healthy\n4. Worker starts after RabbitMQ is healthy\n\n`.WaitFor()` adds a health-check gate to the dependency edge. Without it, the dependency starts but the downstream doesn't wait for health.\n\n---\n\n## Service Discovery\n\nAspire injects environment variables into each resource so services can find each other. No service registry or DNS is needed — it's pure environment variable injection.\n\n### Connection strings\n\nFor databases, caches, and message brokers:\n\n```\nConnectionStrings__\u003cresource-name\u003e=\u003cconnection-string\u003e\n```\n\nExamples:\n```\nConnectionStrings__cache=localhost:6379\nConnectionStrings__catalog=Host=localhost;Port=5432;Database=catalog;Username=postgres;Password=...\nConnectionStrings__messaging=amqp://guest:guest@localhost:5672\n```\n\n### Service endpoints\n\nFor HTTP/HTTPS services:\n\n```\nservices__\u003cresource-name\u003e__\u003cscheme\u003e__0=\u003curl\u003e\n```\n\nExamples:\n```\nservices__api__http__0=http://localhost:5234\nservices__api__https__0=https://localhost:7234\nservices__ml__http__0=http://localhost:8000\n```\n\n### How .WithReference() works\n\n```csharp\nvar redis = builder.AddRedis(\"cache\");\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithReference(redis);\n```\n\nThis does:\n1. Adds `ConnectionStrings__cache=localhost:\u003cauto-port\u003e` to the API's environment\n2. Creates a dependency edge in the DAG (API depends on Redis)\n3. In the API service, `builder.Configuration.GetConnectionString(\"cache\")` returns the connection string\n\n### Cross-language service discovery\n\nAll languages use the same env var pattern:\n\n| Language | How to read |\n|---|---|\n| C# | `builder.Configuration.GetConnectionString(\"cache\")` |\n| Python | `os.environ[\"ConnectionStrings__cache\"]` |\n| JavaScript | `process.env.ConnectionStrings__cache` |\n| Go | `os.Getenv(\"ConnectionStrings__cache\")` |\n| Java | `System.getenv(\"ConnectionStrings__cache\")` |\n| Rust | `std::env::var(\"ConnectionStrings__cache\")` |\n\n---\n\n## Networking\n\n### Proxy architecture\n\nIn `aspire run` mode, DCP runs a reverse proxy for each exposed endpoint:\n\n```\nBrowser → Proxy (auto-assigned port) → Actual Service (target port)\n```\n\n- **port** (the external port) — auto-assigned by DCP unless overridden\n- **targetPort** — the port your service actually listens on\n- All inter-service traffic goes through the proxy for observability\n\n```csharp\n// Let DCP auto-assign the external port, service listens on 8000\nbuilder.AddPythonApp(\"ml\", \"../ml\", \"main.py\")\n    .WithHttpEndpoint(targetPort: 8000);\n\n// Fix the external port to 3000\nbuilder.AddViteApp(\"web\", \"../frontend\")\n    .WithHttpEndpoint(port: 3000, targetPort: 5173);\n```\n\n### Endpoint types\n\n```csharp\n// HTTP endpoint\n.WithHttpEndpoint(port?, targetPort?, name?)\n\n// HTTPS endpoint\n.WithHttpsEndpoint(port?, targetPort?, name?)\n\n// Generic endpoint (TCP, custom schemes)\n.WithEndpoint(port?, targetPort?, scheme?, name?, isExternal?)\n\n// Mark endpoints as externally accessible (for deployment)\n.WithExternalHttpEndpoints()\n```\n\n---\n\n## Telemetry (OpenTelemetry)\n\nAspire configures OpenTelemetry automatically for .NET services. For non-.NET services, you configure OpenTelemetry manually, pointing at the DCP collector.\n\n### What's auto-configured (.NET services)\n\n- **Distributed tracing** — HTTP client/server spans, database spans, messaging spans\n- **Metrics** — Runtime metrics, HTTP metrics, custom metrics\n- **Structured logging** — Logs correlated with trace context\n- **Exporter** — OTLP exporter pointing at the Aspire Dashboard\n\n### Configuring non-.NET services\n\nThe DCP exposes an OTLP endpoint. Set these env vars in your non-.NET service:\n\n```\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317\nOTEL_SERVICE_NAME=\u003cyour-service-name\u003e\n```\n\nAspire auto-injects `OTEL_EXPORTER_OTLP_ENDPOINT` via `.WithReference()` for the dashboard collector.\n\n### ServiceDefaults pattern\n\nThe `ServiceDefaults` project is a shared configuration library that standardizes:\n- OpenTelemetry setup (tracing, metrics, logging)\n- Health check endpoints (`/health`, `/alive`)\n- Resilience policies (retries, circuit breakers via Polly)\n\n```csharp\n// In each .NET service's Program.cs\nbuilder.AddServiceDefaults();   // adds OTel, health checks, resilience\n// ... other service config ...\napp.MapDefaultEndpoints();      // maps /health and /alive\n```\n\n---\n\n## Health Checks\n\n### Built-in health checks\n\nEvery integration adds health checks automatically on the client side:\n- Redis: `PING` command\n- PostgreSQL: `SELECT 1`\n- MongoDB: `ping` command\n- RabbitMQ: Connection check\n- etc.\n\n### WaitFor vs WithReference\n\n```csharp\n// WithReference: wires connection string + creates dependency edge\n// (downstream may start before dependency is healthy)\n.WithReference(db)\n\n// WaitFor: gates on health check — downstream won't start until healthy\n.WaitFor(db)\n\n// Typical pattern: both\n.WithReference(db).WaitFor(db)\n```\n\n### Custom health checks\n\n```csharp\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithHealthCheck(\"ready\", \"/health/ready\")\n    .WithHealthCheck(\"live\", \"/health/live\");\n```\n\n---\n\n## Eventing System\n\nThe AppHost supports lifecycle events for reacting to resource state changes:\n\n```csharp\nbuilder.Eventing.Subscribe\u003cResourceReadyEvent\u003e(\"api\", (evt, ct) =\u003e\n{\n    // Fires when \"api\" resource becomes healthy\n    Console.WriteLine($\"API is ready at {evt.Resource.Name}\");\n    return Task.CompletedTask;\n});\n\nbuilder.Eventing.Subscribe\u003cBeforeResourceStartedEvent\u003e(\"db\", async (evt, ct) =\u003e\n{\n    // Run database migrations before the DB resource is marked as started\n    await RunMigrations();\n});\n```\n\n### Available events\n\n| Event | When |\n|---|---|\n| `BeforeResourceStartedEvent` | Before a resource starts |\n| `ResourceReadyEvent` | Resource is healthy and ready |\n| `ResourceStateChangedEvent` | Any state transition |\n| `BeforeStartEvent` | Before the entire application starts |\n| `AfterEndpointsAllocatedEvent` | After all ports are assigned |\n\n---\n\n## Configuration\n\n### Parameters\n\n```csharp\n// Plain parameter\nvar apiKey = builder.AddParameter(\"api-key\");\n\n// Secret parameter (prompted at run, not logged)\nvar dbPassword = builder.AddParameter(\"db-password\", secret: true);\n\n// Use in resources\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithEnvironment(\"API_KEY\", apiKey);\n\nvar db = builder.AddPostgres(\"db\", password: dbPassword);\n```\n\n### Configuration sources\n\nParameters are resolved from (in priority order):\n1. Command-line arguments\n2. Environment variables\n3. User secrets (`dotnet user-secrets`)\n4. `appsettings.json` / `appsettings.{Environment}.json`\n5. Interactive prompt (for secrets during `aspire run`)\n","references/cli-reference.md":"# CLI Reference — Complete Command Reference\n\nThe Aspire CLI (`aspire`) is the primary interface for creating, running, and publishing distributed applications. It is cross-platform and installed standalone (not coupled to the .NET CLI, though `dotnet` commands also work).\n\n**Tested against:** Aspire CLI 13.1.0\n\n---\n\n## Installation\n\n```bash\n# Linux / macOS\ncurl -sSL https://aspire.dev/install.sh | bash\n\n# Windows PowerShell\nirm https://aspire.dev/install.ps1 | iex\n\n# Verify\naspire --version\n\n# Update the CLI itself\naspire update --self\n```\n\n---\n\n## Global Options\n\nAll commands support these options:\n\n| Option                | Description                                    |\n| --------------------- | ---------------------------------------------- |\n| `-d, --debug`         | Enable debug logging to the console            |\n| `--non-interactive`   | Disable all interactive prompts and spinners   |\n| `--wait-for-debugger` | Wait for a debugger to attach before executing |\n| `-?, -h, --help`      | Show help and usage information                |\n| `--version`           | Show version information                       |\n\n---\n\n## Command Reference\n\n### `aspire new`\n\nCreate a new project from a template.\n\n```bash\naspire new [\u003ctemplate\u003e] [options]\n\n# Options:\n#   -n, --name \u003cname\u003e        Project name\n#   -o, --output \u003cdir\u003e       Output directory\n#   -s, --source \u003csource\u003e    NuGet source for templates\n#   -v, --version \u003cversion\u003e  Version of templates to use\n#   --channel \u003cchannel\u003e      Channel (stable, daily)\n\n# Examples:\naspire new aspire-starter\naspire new aspire-starter -n MyApp -o ./my-app\naspire new aspire-ts-cs-starter\naspire new aspire-py-starter\naspire new aspire-apphost-singlefile\n```\n\nAvailable templates:\n\n- `aspire-starter` — ASP.NET Core/Blazor starter + AppHost + tests\n- `aspire-ts-cs-starter` — ASP.NET Core/React + AppHost\n- `aspire-py-starter` — FastAPI/React + AppHost\n- `aspire-apphost-singlefile` — Empty single-file AppHost\n\n### `aspire init`\n\nInitialize Aspire in an existing project or solution.\n\n```bash\naspire init [options]\n\n# Options:\n#   -s, --source \u003csource\u003e    NuGet source for templates\n#   -v, --version \u003cversion\u003e  Version of templates to use\n#   --channel \u003cchannel\u003e      Channel (stable, daily)\n\n# Example:\ncd my-existing-solution\naspire init\n```\n\nAdds AppHost and ServiceDefaults projects to an existing solution. Interactive prompts guide you through selecting which projects to orchestrate.\n\n### `aspire run`\n\nStart all resources locally using the DCP (Developer Control Plane).\n\n```bash\naspire run [options] [-- \u003cadditional arguments\u003e]\n\n# Options:\n#   --project \u003cpath\u003e       Path to AppHost project file\n\n# Examples:\naspire run\naspire run --project ./src/MyApp.AppHost\n```\n\nBehavior:\n\n1. Builds the AppHost project\n2. Starts the DCP engine\n3. Creates resources in dependency order (DAG)\n4. Waits for health checks on gated resources\n5. Opens the dashboard in the default browser\n6. Streams logs to the terminal\n\nPress `Ctrl+C` to gracefully stop all resources.\n\n### `aspire add`\n\nAdd a hosting integration to the AppHost.\n\n```bash\naspire add [\u003cintegration\u003e] [options]\n\n# Options:\n#   --project \u003cpath\u003e         Target project file\n#   -v, --version \u003cversion\u003e  Version of integration to add\n#   -s, --source \u003csource\u003e    NuGet source for integration\n\n# Examples:\naspire add redis\naspire add postgresql\naspire add mongodb\n```\n\n### `aspire publish` (Preview)\n\nGenerate deployment manifests from the AppHost resource model.\n\n```bash\naspire publish [options] [-- \u003cadditional arguments\u003e]\n\n# Options:\n#   --project \u003cpath\u003e                   Path to AppHost project file\n#   -o, --output-path \u003cpath\u003e           Output directory (default: ./aspire-output)\n#   --log-level \u003clevel\u003e                Log level (trace, debug, information, warning, error, critical)\n#   -e, --environment \u003cenv\u003e            Environment (default: Production)\n#   --include-exception-details        Include stack traces in pipeline logs\n\n# Examples:\naspire publish\naspire publish --output-path ./deploy\naspire publish -e Staging\n```\n\n### `aspire config`\n\nManage Aspire configuration settings.\n\n```bash\naspire config \u003csubcommand\u003e\n\n# Subcommands:\n#   get \u003ckey\u003e              Get a configuration value\n#   set \u003ckey\u003e \u003cvalue\u003e      Set a configuration value\n#   list                   List all configuration values\n#   delete \u003ckey\u003e           Delete a configuration value\n\n# Examples:\naspire config list\naspire config set telemetry.enabled false\naspire config get telemetry.enabled\naspire config delete telemetry.enabled\n```\n\n### `aspire cache`\n\nManage disk cache for CLI operations.\n\n```bash\naspire cache \u003csubcommand\u003e\n\n# Subcommands:\n#   clear                  Clear all cache entries\n\n# Example:\naspire cache clear\n```\n\n### `aspire deploy` (Preview)\n\nDeploy the contents of an Aspire apphost to its defined deployment targets.\n\n```bash\naspire deploy [options] [-- \u003cadditional arguments\u003e]\n\n# Options:\n#   --project \u003cpath\u003e                   Path to AppHost project file\n#   -o, --output-path \u003cpath\u003e           Output path for deployment artifacts\n#   --log-level \u003clevel\u003e                Log level (trace, debug, information, warning, error, critical)\n#   -e, --environment \u003cenv\u003e            Environment (default: Production)\n#   --include-exception-details        Include stack traces in pipeline logs\n#   --clear-cache                      Clear deployment cache for current environment\n\n# Example:\naspire deploy --project ./src/MyApp.AppHost\n```\n\n### `aspire do` (Preview)\n\nExecute a specific pipeline step and its dependencies.\n\n```bash\naspire do \u003cstep\u003e [options] [-- \u003cadditional arguments\u003e]\n\n# Options:\n#   --project \u003cpath\u003e                   Path to AppHost project file\n#   -o, --output-path \u003cpath\u003e           Output path for artifacts\n#   --log-level \u003clevel\u003e                Log level (trace, debug, information, warning, error, critical)\n#   -e, --environment \u003cenv\u003e            Environment (default: Production)\n#   --include-exception-details        Include stack traces in pipeline logs\n\n# Example:\naspire do build-images --project ./src/MyApp.AppHost\n```\n\n### `aspire update` (Preview)\n\nUpdate integrations in the Aspire project, or update the CLI itself.\n\n```bash\naspire update [options]\n\n# Options:\n#   --project \u003cpath\u003e       Path to AppHost project file\n#   --self                 Update the Aspire CLI itself to the latest version\n#   --channel \u003cchannel\u003e    Channel to update to (stable, daily)\n\n# Examples:\naspire update                          # Update project integrations\naspire update --self                   # Update the CLI itself\naspire update --self --channel daily   # Update CLI to daily build\n```\n\n### `aspire mcp`\n\nManage the MCP (Model Context Protocol) server.\n\n```bash\naspire mcp \u003csubcommand\u003e\n\n# Subcommands:\n#   init    Initialize MCP server configuration for detected agent environments\n#   start   Start the MCP server\n```\n\n#### `aspire mcp init`\n\n```bash\naspire mcp init\n\n# Interactive — detects your AI environment and creates config files.\n# Supported environments:\n# - VS Code (GitHub Copilot)\n# - Copilot CLI\n# - Claude Code\n# - OpenCode\n```\n\nGenerates the appropriate configuration file for your detected AI tool.\nSee [MCP Server](mcp-server.md) for details.\n\n#### `aspire mcp start`\n\n```bash\naspire mcp start\n\n# Starts the MCP server using STDIO transport.\n# This is typically invoked by your AI tool, not run manually.\n```\n\n---\n\n## Commands That Do NOT Exist\n\nThe following commands are **not valid** in Aspire CLI 13.1. Use alternatives:\n\n| Invalid Command | Alternative                                                          |\n| --------------- | -------------------------------------------------------------------- |\n| `aspire build`  | Use `dotnet build ./AppHost`                                         |\n| `aspire test`   | Use `dotnet test ./Tests`                                            |\n| `aspire dev`    | Use `aspire run` (includes file watching)                            |\n| `aspire list`   | Use `aspire new --help` for templates, `aspire add` for integrations |\n\n---\n\n## .NET CLI equivalents\n\nThe `dotnet` CLI can perform some Aspire tasks:\n\n| Aspire CLI                  | .NET CLI Equivalent              |\n| --------------------------- | -------------------------------- |\n| `aspire new aspire-starter` | `dotnet new aspire-starter`      |\n| `aspire run`                | `dotnet run --project ./AppHost` |\n| N/A                         | `dotnet build ./AppHost`         |\n| N/A                         | `dotnet test ./Tests`            |\n\nThe Aspire CLI adds value with `publish`, `deploy`, `add`, `mcp`, `config`, `cache`, `do`, and `update` — commands that have no direct `dotnet` equivalent.\n","references/dashboard.md":"# Dashboard — Complete Reference\n\nThe Aspire Dashboard provides real-time observability for all resources in your distributed application. It launches automatically with `aspire run` and can also run standalone.\n\n---\n\n## Features\n\n### Resources view\n\nDisplays all resources (projects, containers, executables) with:\n\n- **Name** and **type** (Project, Container, Executable)\n- **State** (Starting, Running, Stopped, FailedToStart, etc.)\n- **Start time** and **uptime**\n- **Endpoints** — clickable URLs for each exposed endpoint\n- **Source** — project path, container image, or executable path\n- **Actions** — Stop, Start, Restart buttons\n\n### Console logs\n\nAggregated raw stdout/stderr from all resources:\n\n- Filter by resource name\n- Search within logs\n- Auto-scroll with pause\n- Color-coded by resource\n\n### Structured logs\n\nApplication-level structured logs (via ILogger, OpenTelemetry):\n\n- **Filterable** by resource, log level, category, message content\n- **Expandable** — click to see full log entry with all properties\n- **Correlated** with traces — click to jump to the related trace\n- Supports .NET ILogger structured logging properties\n- Supports OpenTelemetry log signals from any language\n\n### Distributed traces\n\nEnd-to-end request traces across all services:\n\n- **Waterfall view** — shows the full call chain with timing\n- **Span details** — HTTP method, URL, status code, duration\n- **Database spans** — SQL queries, connection details\n- **Messaging spans** — queue operations, topic publishes\n- **Error highlighting** — failed spans shown in red\n- **Cross-service correlation** — trace context propagated automatically for .NET; manual for other languages\n\n### Metrics\n\nReal-time and historical metrics:\n\n- **Runtime metrics** — CPU, memory, GC, thread pool\n- **HTTP metrics** — request rate, error rate, latency percentiles\n- **Custom metrics** — any metrics your services emit via OpenTelemetry\n- **Chartable** — time-series graphs for each metric\n\n### GenAI Visualizer\n\nFor applications using AI/LLM integrations:\n\n- **Token usage** — prompt tokens, completion tokens, total tokens per request\n- **Prompt/completion pairs** — see the exact prompt sent and response received\n- **Model metadata** — which model, temperature, max tokens\n- **Latency** — time per AI call\n- Requires services to emit [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) via OpenTelemetry\n\n---\n\n## Dashboard URL\n\nBy default, the dashboard runs on an auto-assigned port. Find it:\n\n- In the terminal output when `aspire run` starts\n- Via MCP: `list_resources` tool\n- Override with `--dashboard-port`:\n\n```bash\naspire run --dashboard-port 18888\n```\n\n---\n\n## Standalone Dashboard\n\nRun the dashboard without an AppHost — useful for existing applications that already emit OpenTelemetry:\n\n```bash\ndocker run --rm -d \\\n  -p 18888:18888 \\\n  -p 4317:18889 \\\n  mcr.microsoft.com/dotnet/aspire-dashboard:latest\n```\n\n| Port             | Purpose                                                      |\n| ---------------- | ------------------------------------------------------------ |\n| `18888`          | Dashboard web UI                                             |\n| `4317` → `18889` | OTLP gRPC receiver (standard OTel port → dashboard internal) |\n\n### Configure your services\n\nPoint your OpenTelemetry exporters at the dashboard:\n\n```bash\n# Environment variables for any language's OpenTelemetry SDK\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317\nOTEL_SERVICE_NAME=my-service\n```\n\n### Docker Compose example\n\n```yaml\nservices:\n  dashboard:\n    image: mcr.microsoft.com/dotnet/aspire-dashboard:latest\n    ports:\n      - \"18888:18888\"\n      - \"4317:18889\"\n\n  api:\n    build: ./api\n    environment:\n      - OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889\n      - OTEL_SERVICE_NAME=api\n\n  worker:\n    build: ./worker\n    environment:\n      - OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889\n      - OTEL_SERVICE_NAME=worker\n```\n\n---\n\n## Dashboard configuration\n\n### Authentication\n\nThe standalone dashboard supports authentication via browser tokens:\n\n```bash\ndocker run --rm -d \\\n  -p 18888:18888 \\\n  -p 4317:18889 \\\n  -e DASHBOARD__FRONTEND__AUTHMODE=BrowserToken \\\n  -e DASHBOARD__FRONTEND__BROWSERTOKEN__TOKEN=my-secret-token \\\n  mcr.microsoft.com/dotnet/aspire-dashboard:latest\n```\n\n### OTLP configuration\n\n```bash\n# Accept OTLP over gRPC (default)\n-e DASHBOARD__OTLP__GRPC__ENDPOINT=http://0.0.0.0:18889\n\n# Accept OTLP over HTTP\n-e DASHBOARD__OTLP__HTTP__ENDPOINT=http://0.0.0.0:18890\n\n# Require API key for OTLP\n-e DASHBOARD__OTLP__AUTHMODE=ApiKey\n-e DASHBOARD__OTLP__PRIMARYAPIKEY=my-api-key\n```\n\n### Resource limits\n\n```bash\n# Limit log entries retained\n-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT=10000\n\n# Limit trace entries retained\n-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT=10000\n\n# Limit metric data points\n-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICCOUNT=50000\n```\n\n---\n\n## Copilot integration\n\nThe dashboard integrates with GitHub Copilot in VS Code:\n\n- Ask questions about resource status\n- Query logs and traces in natural language\n- The MCP server (see [MCP Server](mcp-server.md)) provides the bridge\n\n---\n\n## Non-.NET service telemetry\n\nFor non-.NET services to appear in the dashboard, they must emit OpenTelemetry signals. Aspire auto-injects the OTLP endpoint env var when using `.WithReference()`:\n\n### Python (OpenTelemetry SDK)\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nimport os\n\n# Aspire injects OTEL_EXPORTER_OTLP_ENDPOINT automatically\nendpoint = os.environ.get(\"OTEL_EXPORTER_OTLP_ENDPOINT\", \"http://localhost:4317\")\n\nprovider = TracerProvider()\nprovider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))\ntrace.set_tracer_provider(provider)\n```\n\n### JavaScript (OpenTelemetry SDK)\n\n```javascript\nconst { NodeTracerProvider } = require(\"@opentelemetry/sdk-trace-node\");\nconst { OTLPTraceExporter } = require(\"@opentelemetry/exporter-trace-otlp-grpc\");\n\nconst provider = new NodeTracerProvider();\nprovider.addSpanProcessor(\n  new BatchSpanProcessor(\n    new OTLPTraceExporter({\n      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || \"http://localhost:4317\",\n    })\n  )\n);\nprovider.register();\n```\n","references/deployment.md":"# Deployment — Complete Reference\n\nAspire separates **orchestration** (what to run) from **deployment** (where to run it). The `aspire publish` command translates your AppHost resource model into deployment manifests for your target platform.\n\n---\n\n## Publish vs Deploy\n\n| Concept | What it does |\n|---|---|\n| **`aspire publish`** | Generates deployment artifacts (Dockerfiles, Helm charts, Bicep, etc.) |\n| **Deploy** | You run the generated artifacts through your CI/CD pipeline |\n\nAspire does NOT deploy directly. It generates the manifests — you deploy them.\n\n---\n\n## Supported Targets\n\n### Docker\n\n**Package:** `Aspire.Hosting.Docker`\n\n```bash\naspire publish -p docker -o ./docker-output\n```\n\nGenerates:\n- `docker-compose.yml` — service definitions matching your AppHost\n- `Dockerfile` for each .NET project\n- Environment variable configuration\n- Volume mounts\n- Network configuration\n\n```csharp\n// AppHost configuration for Docker publishing\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .PublishAsDockerFile();  // override default publish behavior\n```\n\n### Kubernetes\n\n**Package:** `Aspire.Hosting.Kubernetes`\n\n```bash\naspire publish -p kubernetes -o ./k8s-output\n```\n\nGenerates:\n- Kubernetes YAML manifests (Deployments, Services, ConfigMaps, Secrets)\n- Helm chart (optional)\n- Ingress configuration\n- Resource limits based on AppHost configuration\n\n```csharp\n// AppHost: customize K8s publishing\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithReplicas(3)                    // maps to K8s replicas\n    .WithExternalHttpEndpoints();       // maps to Ingress/LoadBalancer\n```\n\n### Azure Container Apps\n\n**Package:** `Aspire.Hosting.Azure.AppContainers`\n\n```bash\naspire publish -p azure -o ./azure-output\n```\n\nGenerates:\n- Bicep templates for Azure Container Apps Environment\n- Container App definitions for each service\n- Azure Container Registry configuration\n- Managed identity configuration\n- Dapr components (if using Dapr integration)\n- VNET configuration\n\n```csharp\n// AppHost: Azure-specific configuration\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithExternalHttpEndpoints()        // maps to external ingress\n    .WithReplicas(3);                   // maps to min replicas\n\n// Azure resources are auto-provisioned\nvar storage = builder.AddAzureStorage(\"storage\");   // creates Storage Account\nvar cosmos = builder.AddAzureCosmosDB(\"cosmos\");    // creates Cosmos DB account\nvar sb = builder.AddAzureServiceBus(\"messaging\");   // creates Service Bus namespace\n```\n\n### Azure App Service\n\n**Package:** `Aspire.Hosting.Azure.AppService`\n\n```bash\naspire publish -p appservice -o ./appservice-output\n```\n\nGenerates:\n- Bicep templates for App Service Plans and Web Apps\n- Connection string configuration\n- Application settings\n\n---\n\n## Resource model to deployment mapping\n\n| AppHost concept | Docker Compose | Kubernetes | Azure Container Apps |\n|---|---|---|---|\n| `AddProject\u003cT\u003e()` | `service` with Dockerfile | `Deployment` + `Service` | `Container App` |\n| `AddContainer()` | `service` with `image:` | `Deployment` + `Service` | `Container App` |\n| `AddRedis()` | `service: redis` | `StatefulSet` | Managed Redis |\n| `AddPostgres()` | `service: postgres` | `StatefulSet` | Azure PostgreSQL |\n| `.WithReference()` | `environment:` vars | `ConfigMap` / `Secret` | App settings |\n| `.WithReplicas(n)` | `deploy: replicas: n` | `replicas: n` | `minReplicas: n` |\n| `.WithVolume()` | `volumes:` | `PersistentVolumeClaim` | Azure Files |\n| `.WithHttpEndpoint()` | `ports:` | `Service` port | Ingress |\n| `.WithExternalHttpEndpoints()` | `ports:` (host) | `Ingress` / `LoadBalancer` | External ingress |\n| `AddParameter(secret: true)` | `.env` file | `Secret` | Key Vault reference |\n\n---\n\n## CI/CD integration\n\n### GitHub Actions example\n\n```yaml\nname: Deploy\non:\n  push:\n    branches: [main]\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Setup .NET\n        uses: actions/setup-dotnet@v4\n        with:\n          dotnet-version: '10.0.x'\n\n      - name: Install Aspire CLI\n        run: curl -sSL https://aspire.dev/install.sh | bash\n\n      - name: Generate manifests\n        run: aspire publish -p azure -o ./deploy\n\n      - name: Deploy to Azure\n        uses: azure/arm-deploy@v2\n        with:\n          template: ./deploy/main.bicep\n          parameters: ./deploy/main.parameters.json\n```\n\n### Azure DevOps example\n\n```yaml\ntrigger:\n  branches:\n    include: [main]\n\npool:\n  vmImage: 'ubuntu-latest'\n\nsteps:\n  - task: UseDotNet@2\n    inputs:\n      version: '10.0.x'\n\n  - script: curl -sSL https://aspire.dev/install.sh | bash\n    displayName: 'Install Aspire CLI'\n\n  - script: aspire publish -p azure -o $(Build.ArtifactStagingDirectory)/deploy\n    displayName: 'Generate deployment manifests'\n\n  - task: AzureResourceManagerTemplateDeployment@3\n    inputs:\n      deploymentScope: 'Resource Group'\n      templateLocation: '$(Build.ArtifactStagingDirectory)/deploy/main.bicep'\n```\n\n---\n\n## Environment-specific configuration\n\n### Using parameters for secrets\n\n```csharp\n// AppHost\nvar dbPassword = builder.AddParameter(\"db-password\", secret: true);\nvar postgres = builder.AddPostgres(\"db\", password: dbPassword);\n```\n\nIn deployment:\n- **Docker:** Loaded from `.env` file\n- **Kubernetes:** Loaded from `Secret` resource\n- **Azure:** Loaded from Key Vault via managed identity\n\n### Conditional resources\n\n```csharp\n// Use Azure services in production, emulators locally\nif (builder.ExecutionContext.IsPublishMode)\n{\n    var cosmos = builder.AddAzureCosmosDB(\"cosmos\");    // real Azure resource\n}\nelse\n{\n    var cosmos = builder.AddAzureCosmosDB(\"cosmos\")\n        .RunAsEmulator();                                // local emulator\n}\n```\n\n---\n\n## Dev Containers \u0026 GitHub Codespaces\n\nAspire templates include `.devcontainer/` configuration:\n\n```json\n{\n  \"name\": \"Aspire App\",\n  \"image\": \"mcr.microsoft.com/devcontainers/dotnet:10.0\",\n  \"features\": {\n    \"ghcr.io/devcontainers/features/docker-in-docker:2\": {},\n    \"ghcr.io/devcontainers/features/node:1\": {}\n  },\n  \"postCreateCommand\": \"curl -sSL https://aspire.dev/install.sh | bash\",\n  \"forwardPorts\": [18888],\n  \"portsAttributes\": {\n    \"18888\": { \"label\": \"Aspire Dashboard\" }\n  }\n}\n```\n\nPort forwarding works automatically in Codespaces — the dashboard and all service endpoints are accessible via forwarded URLs.\n","references/integrations-catalog.md":"# Integrations Catalog\n\nAspire has **144+ integrations** across 13 categories. Rather than maintaining a static list, use the MCP tools to get live, up-to-date integration data.\n\n---\n\n## Discovering integrations (MCP tools)\n\nThe Aspire MCP server provides two tools for integration discovery — these work on **all CLI versions** (13.1+) and do **not** require a running AppHost.\n\n| Tool                   | What it does                                                                                             | When to use                                                                                 |\n| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `list_integrations`    | Returns all available Aspire hosting integrations with their NuGet package IDs                           | \"What integrations are available for databases?\" / \"Show me all Redis-related integrations\" |\n| `get_integration_docs` | Retrieves detailed documentation for a specific integration package (setup, configuration, code samples) | \"How do I configure PostgreSQL?\" / \"Show me the docs for `Aspire.Hosting.Redis`\"            |\n\n### Workflow\n\n1. **Browse** — Call `list_integrations` to see what's available. Filter results by category or keyword.\n2. **Deep dive** — Call `get_integration_docs` with the package ID (e.g., `Aspire.Hosting.Redis`) and version (e.g., `9.0.0`) to get full setup instructions.\n3. **Add** — Run `aspire add \u003cintegration\u003e` to install the hosting package into your AppHost.\n\n\u003e **Tip:** These tools return the same data as the [official integrations gallery](https://aspire.dev/integrations/gallery/). Prefer them over static docs — integrations are added frequently.\n\n---\n\n## Integration pattern\n\nEvery integration follows a two-package pattern:\n\n- **Hosting package** (`Aspire.Hosting.*`) — adds the resource to the AppHost\n- **Client package** (`Aspire.*`) — configures the client SDK in your service with health checks, telemetry, and retries\n- **Community Toolkit** (`CommunityToolkit.Aspire.*`) — community-maintained integrations from [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)\n\n```csharp\n// === AppHost (hosting side) ===\nvar redis = builder.AddRedis(\"cache\");  // Aspire.Hosting.Redis\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithReference(redis);\n\n// === Service (client side) — in API's Program.cs ===\nbuilder.AddRedisClient(\"cache\");        // Aspire.StackExchange.Redis\n// Automatically configures: connection string, health checks, OpenTelemetry, retries\n```\n\n---\n\n## Categories at a glance\n\nUse `list_integrations` for the full live list. This summary covers the major categories:\n\n| Category            | Key integrations                                                                      | Example hosting package                  |\n| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |\n| **AI**              | Azure OpenAI, OpenAI, GitHub Models, Ollama                                           | `Aspire.Hosting.Azure.CognitiveServices` |\n| **Caching**         | Redis, Garnet, Valkey, Azure Cache for Redis                                          | `Aspire.Hosting.Redis`                   |\n| **Cloud / Azure**   | Storage, Cosmos DB, Service Bus, Key Vault, Event Hubs, Functions, SQL, SignalR (25+) | `Aspire.Hosting.Azure.Storage`           |\n| **Cloud / AWS**     | AWS SDK integration                                                                   | `Aspire.Hosting.AWS`                     |\n| **Databases**       | PostgreSQL, SQL Server, MongoDB, MySQL, Oracle, Elasticsearch, Milvus, Qdrant, SQLite | `Aspire.Hosting.PostgreSQL`              |\n| **DevTools**        | Data API Builder, Dev Tunnels, Mailpit, k6, Flagd, Ngrok, Stripe                      | `Aspire.Hosting.DevTunnels`              |\n| **Messaging**       | RabbitMQ, Kafka, NATS, ActiveMQ, LavinMQ                                              | `Aspire.Hosting.RabbitMQ`                |\n| **Observability**   | OpenTelemetry (built-in), Seq, OTel Collector                                         | `Aspire.Hosting.Seq`                     |\n| **Compute**         | Docker Compose, Kubernetes                                                            | `Aspire.Hosting.Docker`                  |\n| **Reverse Proxies** | YARP                                                                                  | `Aspire.Hosting.Yarp`                    |\n| **Security**        | Keycloak                                                                              | `Aspire.Hosting.Keycloak`                |\n| **Frameworks**      | JavaScript, Python, Go, Java, Rust, Bun, Deno, Orleans, MAUI, Dapr, PowerShell        | `Aspire.Hosting.Python`                  |\n\nFor polyglot framework method signatures, see [Polyglot APIs](polyglot-apis.md).\n\n---\n","references/mcp-server.md":"# MCP Server — Complete Reference\n\nAspire exposes an **MCP (Model Context Protocol) server** that lets AI coding assistants query and control your running distributed application, and search Aspire documentation. This enables AI tools to inspect resource status, read logs, view traces, restart services, and look up docs — all from within the AI assistant's context.\n\nReference: https://aspire.dev/get-started/configure-mcp/\n\n---\n\n## Setup: `aspire mcp init`\n\nThe easiest way to configure the MCP server is using the Aspire CLI:\n\n```bash\n# Open a terminal in your project directory\naspire mcp init\n```\n\nThe command walks you through an interactive setup:\n\n1. **Workspace root** — prompts for the path to your workspace root (defaults to current directory)\n2. **Environment detection** — detects supported AI environments (VS Code, Copilot CLI, Claude Code, OpenCode) and asks which to configure\n3. **Playwright MCP** — optionally offers to configure the Playwright MCP server alongside Aspire\n4. **Config creation** — writes the appropriate configuration files (e.g., `.vscode/mcp.json`)\n5. **AGENTS.md** — if one doesn't already exist, creates an `AGENTS.md` with Aspire-specific instructions for AI agents\n\n\u003e **Note:** `aspire mcp init` uses interactive prompts (Spectre.Console). It must be run in a real terminal — the VS Code integrated terminal may not handle the prompts correctly. Use an external terminal if needed.\n\n---\n\n## Understanding the Configuration\n\nWhen you run `aspire mcp init`, the CLI creates configuration files appropriate for your detected environment.\n\n### VS Code (GitHub Copilot)\n\nCreates or updates `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"aspire\": {\n      \"type\": \"stdio\",\n      \"command\": \"aspire\",\n      \"args\": [\"mcp\", \"start\"]\n    }\n  }\n}\n```\n\n## MCP Tools\n\nThe tools available depend on your Aspire CLI version. Check with `aspire --version`.\n\n### Tools available in 13.1+ (stable)\n\n#### Resource management tools\n\nThese tools require a running AppHost (`aspire run`).\n\n| Tool                         | Description                                                                          |\n| ---------------------------- | ------------------------------------------------------------------------------------ |\n| `list_resources`             | Lists all resources, including state, health status, source, endpoints, and commands                |\n| `list_console_logs`          | Lists console logs for a resource                                                                   |\n| `list_structured_logs`       | Lists structured logs, optionally filtered by resource name                                         |\n| `list_traces`                | Lists distributed traces. Traces can be filtered using an optional resource name parameter          |\n| `list_trace_structured_logs` | Lists structured logs for a specific trace                                                          |\n| `execute_resource_command`   | Executes a resource command (accepts resource name and command name)                                |\n\n#### AppHost management tools\n\n| Tool             | Description                                                                                 |\n| ---------------- | ------------------------------------------------------------------------------------------- |\n| `list_apphosts`  | Lists all detected AppHost connections, showing which are in/out of working directory scope |\n| `select_apphost` | Selects which AppHost to use when multiple are running                                      |\n\n#### Integration tools\n\nThese work without a running AppHost.\n\n| Tool                   | Description                                                                                                       |\n| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `list_integrations`    | Lists available Aspire hosting integrations (NuGet packages for databases, message brokers, cloud services, etc.) |\n| `get_integration_docs` | Gets documentation for a specific Aspire hosting integration package                                              |\n\n### Tools added in 13.2+ (documentation search)\n\n\u003e **Version gate:** These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028) and ship in Aspire CLI **13.2**. If you are on 13.1, these tools will NOT appear. To get them early, update to the daily channel: `aspire update --self --channel daily`.\n\n| Tool          | Description                                                              |\n| ------------- | ------------------------------------------------------------------------ |\n| `list_docs`   | Lists all available documentation from aspire.dev                        |\n| `search_docs` | Performs weighted lexical search across indexed aspire.dev documentation |\n| `get_doc`     | Retrieves a specific document by its slug                                |\n\nThese tools index aspire.dev content using the `llms.txt` specification and provide weighted lexical search (titles 10x, summaries 8x, headings 6x, code 5x, body 1x). They work without a running AppHost.\n\n### Fallback for documentation (13.1 users)\n\nIf you are on Aspire CLI 13.1 and don't have `list_docs`/`search_docs`/`get_doc`, use **Context7** as a fallback for documentation queries. See the [SKILL.md documentation research section](../SKILL.md#1-researching-aspire-documentation) for details.\n\n---\n\n## Excluding Resources from MCP\n\nResources and associated telemetry can be excluded from MCP results by annotating the resource:\n\n```csharp\nvar builder = DistributedApplication.CreateBuilder(args);\n\nvar apiService = builder.AddProject\u003cProjects.Api\u003e(\"apiservice\")\n    .ExcludeFromMcp();  // Hidden from MCP tools\n\nbuilder.AddProject\u003cProjects.Web\u003e(\"webfrontend\")\n    .WithExternalHttpEndpoints()\n    .WithReference(apiService);\n\nbuilder.Build().Run();\n```\n\n---\n\n## Supported AI Assistants\n\nThe `aspire mcp init` command supports:\n\n- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) (GitHub Copilot)\n- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server)\n- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)\n- [OpenCode](https://opencode.ai/docs/mcp-servers/)\n\nThe MCP server uses the **STDIO transport protocol** and may work with other agentic coding environments that support this protocol.\n\n---\n\n## Usage Patterns\n\n### Debugging with AI assistance\n\nOnce MCP is configured, your AI assistant can:\n\n1. **Inspect running state:**\n\n   - \"List all my Aspire resources and their status\"\n   - \"Is the database healthy?\"\n   - \"What port is the API running on?\"\n\n2. **Read logs:**\n\n   - \"Show me the recent logs from the ML service\"\n   - \"Are there any errors in the worker logs?\"\n\n3. **View traces:**\n\n   - \"Show me the trace for the last failed request\"\n   - \"What's the latency for API → Database calls?\"\n\n4. **Control resources:**\n\n   - \"Restart the API service\"\n   - \"Stop the worker while I debug the queue\"\n\n5. **Search docs (13.2+):**\n   - \"Search the Aspire docs for Redis caching\"\n   - \"How do I configure service discovery?\"\n   - _(Requires CLI 13.2+. On 13.1, use Context7 or `list_integrations`/`get_integration_docs` for integration-specific docs.)_\n\n---\n\n## Security Considerations\n\n- The MCP server only exposes resources from the local AppHost\n- No authentication is required (local development only)\n- The STDIO transport only works for the AI tool that spawned the process\n- **Do not expose the MCP endpoint to the network in production**\n\n---\n\n## Limitations\n\n- AI models have limits on data processing. Large data fields (e.g., stack traces) may be truncated.\n- Requests involving large collections of telemetry may be shortened by omitting older items.\n\n---\n\n## Troubleshooting\n\nIf you run into issues, check the [open MCP issues on GitHub](https://github.com/dotnet/aspire/issues?q=is%3Aissue+is%3Aopen+label%3Aarea-mcp).\n\n## See Also\n\n- [aspire mcp command](https://aspire.dev/reference/cli/commands/aspire-mcp/)\n- [aspire mcp init command](https://aspire.dev/reference/cli/commands/aspire-mcp-init/)\n- [aspire mcp start command](https://aspire.dev/reference/cli/commands/aspire-mcp-start/)\n- [GitHub Copilot in the Dashboard](https://aspire.dev/dashboard/copilot/)\n- [How I taught AI to read Aspire docs](https://davidpine.dev/posts/aspire-docs-mcp-tools/)\n","references/polyglot-apis.md":"# Polyglot APIs — Complete Reference\n\nAspire supports 10+ languages/runtimes. The AppHost is always .NET, but orchestrated workloads can be any language. Each language has a hosting method that returns a resource you wire into the dependency graph.\n\n---\n\n## Hosting model differences\n\n| Model | Resource type | How it runs | Examples |\n|---|---|---|---|\n| **Project** | `ProjectResource` | .NET project reference, built by SDK | `AddProject\u003cT\u003e()` |\n| **Container** | `ContainerResource` | Docker/OCI image | `AddContainer()`, `AddRedis()`, `AddPostgres()` |\n| **Executable** | `ExecutableResource` | Native OS process | `AddExecutable()`, all `Add*App()` polyglot methods |\n\nAll polyglot `Add*App()` methods create `ExecutableResource` instances under the hood. They don't require the target language's SDK on the AppHost side — only that the workload's runtime is installed on the dev machine.\n\n---\n\n## Official (Microsoft-maintained)\n\n### .NET / C\\#\n\n```csharp\nbuilder.AddProject\u003cProjects.MyApi\u003e(\"api\")\n```\n\n**Chaining methods:**\n- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP endpoint\n- `.WithHttpsEndpoint(port?, targetPort?, name?)` — expose HTTPS endpoint\n- `.WithEndpoint(port?, targetPort?, scheme?, name?)` — generic endpoint\n- `.WithReference(resource)` — wire dependency (connection string or service discovery)\n- `.WithReplicas(count)` — run multiple instances\n- `.WithEnvironment(key, value)` — set environment variable\n- `.WithEnvironment(callback)` — set env vars via callback (deferred resolution)\n- `.WaitFor(resource)` — don't start until dependency is healthy\n- `.WithExternalHttpEndpoints()` — mark endpoints as externally accessible\n- `.WithOtlpExporter()` — configure OpenTelemetry exporter\n- `.PublishAsDockerFile()` — override publish behavior to Dockerfile\n\n### Python\n\n```csharp\n// Standard Python script\nbuilder.AddPythonApp(\"service\", \"../python-service\", \"main.py\")\n\n// Uvicorn ASGI server (FastAPI, Starlette, etc.)\nbuilder.AddUvicornApp(\"fastapi\", \"../fastapi-app\", \"app:app\")\n```\n\n**`AddPythonApp(name, projectDirectory, scriptPath, args?)`**\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP\n- `.WithVirtualEnvironment(path?)` — use venv (default: `.venv`)\n- `.WithPipPackages(packages)` — install pip packages on start\n- `.WithReference(resource)` — wire dependency\n- `.WithEnvironment(key, value)` — set env var\n- `.WaitFor(resource)` — wait for dependency health\n\n**`AddUvicornApp(name, projectDirectory, appModule, args?)`**\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP\n- `.WithVirtualEnvironment(path?)` — use venv\n- `.WithReference(resource)` — wire dependency\n- `.WithEnvironment(key, value)` — set env var\n- `.WaitFor(resource)` — wait for dependency health\n\n**Python service discovery:** Environment variables are injected automatically. Use `os.environ` to read:\n```python\nimport os\nredis_conn = os.environ[\"ConnectionStrings__cache\"]\napi_url = os.environ[\"services__api__http__0\"]\n```\n\n### JavaScript / TypeScript\n\n```csharp\n// Generic JavaScript app (npm start)\nbuilder.AddJavaScriptApp(\"frontend\", \"../web-app\")\n\n// Vite dev server\nbuilder.AddViteApp(\"spa\", \"../vite-app\")\n\n// Node.js script\nbuilder.AddNodeApp(\"worker\", \"server.js\", \"../node-worker\")\n```\n\n**`AddJavaScriptApp(name, workingDirectory)`**\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP\n- `.WithNpmPackageInstallation()` — run `npm install` before start\n- `.WithReference(resource)` — wire dependency\n- `.WithEnvironment(key, value)` — set env var\n- `.WaitFor(resource)` — wait for dependency health\n\n**`AddViteApp(name, workingDirectory)`**\n\nChaining methods (same as `AddJavaScriptApp` plus):\n- `.WithNpmPackageInstallation()` — run `npm install` before start\n- `.WithHttpEndpoint(port?, targetPort?, name?)` — Vite defaults to 5173\n\n**`AddNodeApp(name, scriptPath, workingDirectory)`**\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP\n- `.WithNpmPackageInstallation()` — run `npm install` before start\n- `.WithReference(resource)` — wire dependency\n- `.WithEnvironment(key, value)` — set env var\n\n**JS/TS service discovery:** Environment variables are injected. Use `process.env`:\n```javascript\nconst redisUrl = process.env.ConnectionStrings__cache;\nconst apiUrl = process.env.services__api__http__0;\n```\n\n---\n\n## Community (CommunityToolkit/Aspire)\n\nAll community integrations follow the same pattern: install the NuGet package in your AppHost, then use the `Add*App()` method.\n\n### Go\n\n**Package:** `CommunityToolkit.Aspire.Hosting.Golang`\n\n```csharp\nbuilder.AddGolangApp(\"go-api\", \"../go-service\")\n    .WithHttpEndpoint(targetPort: 8080)\n    .WithReference(redis)\n    .WithEnvironment(\"LOG_LEVEL\", \"debug\")\n    .WaitFor(redis);\n```\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)`\n- `.WithReference(resource)`\n- `.WithEnvironment(key, value)`\n- `.WaitFor(resource)`\n\n**Go service discovery:** Standard env vars via `os.Getenv()`:\n```go\nredisAddr := os.Getenv(\"ConnectionStrings__cache\")\n```\n\n### Java (Spring Boot)\n\n**Package:** `CommunityToolkit.Aspire.Hosting.Java`\n\n```csharp\nbuilder.AddSpringApp(\"spring-api\", \"../spring-service\")\n    .WithHttpEndpoint(targetPort: 8080)\n    .WithReference(postgres)\n    .WaitFor(postgres);\n```\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)`\n- `.WithReference(resource)`\n- `.WithEnvironment(key, value)`\n- `.WaitFor(resource)`\n- `.WithMavenBuild()` — run Maven build before start\n- `.WithGradleBuild()` — run Gradle build before start\n\n**Java service discovery:** Env vars via `System.getenv()`:\n```java\nString dbConn = System.getenv(\"ConnectionStrings__db\");\n```\n\n### Rust\n\n**Package:** `CommunityToolkit.Aspire.Hosting.Rust`\n\n```csharp\nbuilder.AddRustApp(\"rust-worker\", \"../rust-service\")\n    .WithHttpEndpoint(targetPort: 3000)\n    .WithReference(redis)\n    .WaitFor(redis);\n```\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)`\n- `.WithReference(resource)`\n- `.WithEnvironment(key, value)`\n- `.WaitFor(resource)`\n- `.WithCargoBuild()` — run `cargo build` before start\n\n### Bun\n\n**Package:** `CommunityToolkit.Aspire.Hosting.Bun`\n\n```csharp\nbuilder.AddBunApp(\"bun-api\", \"../bun-service\")\n    .WithHttpEndpoint(targetPort: 3000)\n    .WithReference(redis);\n```\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)`\n- `.WithReference(resource)`\n- `.WithEnvironment(key, value)`\n- `.WaitFor(resource)`\n- `.WithBunPackageInstallation()` — run `bun install` before start\n\n### Deno\n\n**Package:** `CommunityToolkit.Aspire.Hosting.Deno`\n\n```csharp\nbuilder.AddDenoApp(\"deno-api\", \"../deno-service\")\n    .WithHttpEndpoint(targetPort: 8000)\n    .WithReference(redis);\n```\n\nChaining methods:\n- `.WithHttpEndpoint(port?, targetPort?, name?)`\n- `.WithReference(resource)`\n- `.WithEnvironment(key, value)`\n- `.WaitFor(resource)`\n\n### PowerShell\n\n```csharp\nbuilder.AddPowerShell(\"ps-script\", \"../scripts/process.ps1\")\n    .WithReference(storageAccount);\n```\n\n### Dapr\n\n**Package:** `Aspire.Hosting.Dapr` (official)\n\n```csharp\nvar dapr = builder.AddDapr();\nvar api = builder.AddProject\u003cProjects.Api\u003e(\"api\")\n    .WithDaprSidecar(\"api-sidecar\");\n```\n\n---\n\n## Complete mixed-language example\n\n```csharp\nvar builder = DistributedApplication.CreateBuilder(args);\n\n// Infrastructure\nvar redis = builder.AddRedis(\"cache\");\nvar postgres = builder.AddPostgres(\"pg\").AddDatabase(\"catalog\");\nvar mongo = builder.AddMongoDB(\"mongo\").AddDatabase(\"analytics\");\nvar rabbit = builder.AddRabbitMQ(\"messaging\");\n\n// .NET API (primary)\nvar api = builder.AddProject\u003cProjects.CatalogApi\u003e(\"api\")\n    .WithReference(postgres)\n    .WithReference(redis)\n    .WithReference(rabbit)\n    .WaitFor(postgres)\n    .WaitFor(redis);\n\n// Python ML service (FastAPI)\nvar ml = builder.AddUvicornApp(\"ml\", \"../ml-service\", \"app:app\")\n    .WithHttpEndpoint(targetPort: 8000)\n    .WithVirtualEnvironment()\n    .WithReference(redis)\n    .WithReference(mongo)\n    .WaitFor(redis);\n\n// TypeScript frontend (Vite + React)\nvar web = builder.AddViteApp(\"web\", \"../frontend\")\n    .WithNpmPackageInstallation()\n    .WithHttpEndpoint(targetPort: 5173)\n    .WithReference(api);\n\n// Go event processor\nvar processor = builder.AddGolangApp(\"processor\", \"../go-processor\")\n    .WithReference(rabbit)\n    .WithReference(mongo)\n    .WaitFor(rabbit);\n\n// Java analytics service (Spring Boot)\nvar analytics = builder.AddSpringApp(\"analytics\", \"../spring-analytics\")\n    .WithHttpEndpoint(targetPort: 8080)\n    .WithReference(mongo)\n    .WithReference(rabbit)\n    .WaitFor(mongo);\n\n// Rust high-perf worker\nvar worker = builder.AddRustApp(\"worker\", \"../rust-worker\")\n    .WithReference(redis)\n    .WithReference(rabbit)\n    .WaitFor(redis);\n\nbuilder.Build().Run();\n```\n\nThis single AppHost starts 6 services across 5 languages plus 4 infrastructure resources, all wired together with automatic service discovery.\n","references/testing.md":"# Testing — Complete Reference\n\nAspire provides `Aspire.Hosting.Testing` for running integration tests against your full AppHost. Tests spin up the entire distributed application (or a subset) and run assertions against real services.\n\n---\n\n## Package\n\n```xml\n\u003cPackageReference Include=\"Aspire.Hosting.Testing\" Version=\"*\" /\u003e\n```\n\n---\n\n## Core pattern: DistributedApplicationTestingBuilder\n\n```csharp\n// 1. Create a testing builder from your AppHost\nvar builder = await DistributedApplicationTestingBuilder\n    .CreateAsync\u003cProjects.MyAppHost\u003e();\n\n// 2. (Optional) Override resources for testing\n// ... see customization section below\n\n// 3. Build and start the application\nawait using var app = await builder.BuildAsync();\nawait app.StartAsync();\n\n// 4. Create HTTP clients for your services\nvar client = app.CreateHttpClient(\"api\");\n\n// 5. Run assertions\nvar response = await client.GetAsync(\"/health\");\nAssert.Equal(HttpStatusCode.OK, response.StatusCode);\n```\n\n---\n\n## xUnit examples\n\n### Basic health check test\n\n```csharp\npublic class HealthTests(ITestOutputHelper output)\n{\n    [Fact]\n    public async Task AllServicesAreHealthy()\n    {\n        var builder = await DistributedApplicationTestingBuilder\n            .CreateAsync\u003cProjects.AppHost\u003e();\n\n        await using var app = await builder.BuildAsync();\n        await app.StartAsync();\n\n        // Test each service's health endpoint\n        var apiClient = app.CreateHttpClient(\"api\");\n        var apiHealth = await apiClient.GetAsync(\"/health\");\n        Assert.Equal(HttpStatusCode.OK, apiHealth.StatusCode);\n\n        var workerClient = app.CreateHttpClient(\"worker\");\n        var workerHealth = await workerClient.GetAsync(\"/health\");\n        Assert.Equal(HttpStatusCode.OK, workerHealth.StatusCode);\n    }\n}\n```\n\n### API integration test\n\n```csharp\npublic class ApiTests(ITestOutputHelper output)\n{\n    [Fact]\n    public async Task CreateOrder_ReturnsCreated()\n    {\n        var builder = await DistributedApplicationTestingBuilder\n            .CreateAsync\u003cProjects.AppHost\u003e();\n\n        await using var app = await builder.BuildAsync();\n        await app.StartAsync();\n\n        var client = app.CreateHttpClient(\"api\");\n\n        var order = new { ProductId = 1, Quantity = 2 };\n        var response = await client.PostAsJsonAsync(\"/orders\", order);\n\n        Assert.Equal(HttpStatusCode.Created, response.StatusCode);\n\n        var created = await response.Content.ReadFromJsonAsync\u003cOrder\u003e();\n        Assert.NotNull(created);\n        Assert.Equal(1, created.ProductId);\n    }\n}\n```\n\n### Testing with wait for readiness\n\n```csharp\n[Fact]\npublic async Task DatabaseIsSeeded()\n{\n    var builder = await DistributedApplicationTestingBuilder\n        .CreateAsync\u003cProjects.AppHost\u003e();\n\n    await using var app = await builder.BuildAsync();\n    await app.StartAsync();\n\n    // Wait for the API to be fully ready (all dependencies healthy)\n    await app.WaitForResourceReadyAsync(\"api\");\n\n    var client = app.CreateHttpClient(\"api\");\n    var response = await client.GetAsync(\"/products\");\n\n    Assert.Equal(HttpStatusCode.OK, response.StatusCode);\n    var products = await response.Content.ReadFromJsonAsync\u003cList\u003cProduct\u003e\u003e();\n    Assert.NotEmpty(products);\n}\n```\n\n---\n\n## MSTest examples\n\n```csharp\n[TestClass]\npublic class IntegrationTests\n{\n    [TestMethod]\n    public async Task ApiReturnsProducts()\n    {\n        var builder = await DistributedApplicationTestingBuilder\n            .CreateAsync\u003cProjects.AppHost\u003e();\n\n        await using var app = await builder.BuildAsync();\n        await app.StartAsync();\n\n        var client = app.CreateHttpClient(\"api\");\n        var response = await client.GetAsync(\"/products\");\n\n        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);\n    }\n}\n```\n\n---\n\n## NUnit examples\n\n```csharp\n[TestFixture]\npublic class IntegrationTests\n{\n    [Test]\n    public async Task ApiReturnsProducts()\n    {\n        var builder = await DistributedApplicationTestingBuilder\n            .CreateAsync\u003cProjects.AppHost\u003e();\n\n        await using var app = await builder.BuildAsync();\n        await app.StartAsync();\n\n        var client = app.CreateHttpClient(\"api\");\n        var response = await client.GetAsync(\"/products\");\n\n        Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));\n    }\n}\n```\n\n---\n\n## Customizing the test AppHost\n\n### Override resources\n\n```csharp\nvar builder = await DistributedApplicationTestingBuilder\n    .CreateAsync\u003cProjects.AppHost\u003e();\n\n// Replace a real database with a test container\nbuilder.Services.ConfigureHttpClientDefaults(http =\u003e\n{\n    http.AddStandardResilienceHandler();\n});\n\n// Add test-specific configuration\nbuilder.Configuration[\"TestMode\"] = \"true\";\n\nawait using var app = await builder.BuildAsync();\nawait app.StartAsync();\n```\n\n### Exclude resources\n\n```csharp\nvar builder = await DistributedApplicationTestingBuilder\n    .CreateAsync\u003cProjects.AppHost\u003e(args =\u003e\n    {\n        // Don't start the worker for API-only tests\n        args.Args = [\"--exclude-resource\", \"worker\"];\n    });\n```\n\n### Test with specific environment\n\n```csharp\nvar builder = await DistributedApplicationTestingBuilder\n    .CreateAsync\u003cProjects.AppHost\u003e(args =\u003e\n    {\n        args.Args = [\"--environment\", \"Testing\"];\n    });\n```\n\n---\n\n## Connection string access\n\n```csharp\n// Get the connection string for a resource in tests\nvar connectionString = await app.GetConnectionStringAsync(\"db\");\n\n// Use it to query the database directly in tests\nusing var conn = new NpgsqlConnection(connectionString);\nawait conn.OpenAsync();\nvar count = await conn.ExecuteScalarAsync\u003cint\u003e(\"SELECT COUNT(*) FROM products\");\nAssert.True(count \u003e 0);\n```\n\n---\n\n## Best practices\n\n1. **Use `WaitForResourceReadyAsync`** before making requests — ensures all dependencies are healthy\n2. **Each test should be independent** — don't rely on state from previous tests\n3. **Use `await using`** for the app — ensures cleanup even on test failure\n4. **Test real infrastructure** — Aspire spins up real containers (Redis, PostgreSQL, etc.), giving you high-fidelity integration tests\n5. **Keep test AppHost lean** — exclude resources you don't need for specific test scenarios\n6. **Use test-specific configuration** — override settings for test isolation\n7. **Timeout protection** — set reasonable test timeouts since containers take time to start:\n\n```csharp\n[Fact(Timeout = 120_000)]  // 2 minutes\npublic async Task SlowIntegrationTest() { ... }\n```\n\n---\n\n## Project structure\n\n```\nMyApp/\n├── src/\n│   ├── MyApp.AppHost/           # AppHost project\n│   ├── MyApp.Api/               # API service\n│   ├── MyApp.Worker/            # Worker service\n│   └── MyApp.ServiceDefaults/   # Shared defaults\n└── tests/\n    └── MyApp.Tests/             # Integration tests\n        ├── MyApp.Tests.csproj   # References AppHost + Testing package\n        └── ApiTests.cs          # Test classes\n```\n\n```xml\n\u003c!-- MyApp.Tests.csproj --\u003e\n\u003cProject Sdk=\"Microsoft.NET.Sdk\"\u003e\n  \u003cPropertyGroup\u003e\n    \u003cTargetFramework\u003enet10.0\u003c/TargetFramework\u003e\n    \u003cIsAspireTestProject\u003etrue\u003c/IsAspireTestProject\u003e\n  \u003c/PropertyGroup\u003e\n\n  \u003cItemGroup\u003e\n    \u003cPackageReference Include=\"Aspire.Hosting.Testing\" Version=\"*\" /\u003e\n    \u003cPackageReference Include=\"Microsoft.NET.Test.Sdk\" Version=\"*\" /\u003e\n    \u003cPackageReference Include=\"xunit\" Version=\"*\" /\u003e\n    \u003cPackageReference Include=\"xunit.runner.visualstudio\" Version=\"*\" /\u003e\n  \u003c/ItemGroup\u003e\n\n  \u003cItemGroup\u003e\n    \u003cProjectReference Include=\"..\\..\\src\\MyApp.AppHost\\MyApp.AppHost.csproj\" /\u003e\n  \u003c/ItemGroup\u003e\n\u003c/Project\u003e\n```\n","references/troubleshooting.md":"# Troubleshooting — Diagnostics \u0026 Common Issues\n\n---\n\n## Diagnostic Codes\n\nAspire emits diagnostic codes for common issues. These appear in build warnings/errors and IDE diagnostics.\n\n### Standard diagnostics\n\n| Code          | Severity | Description                                                |\n| ------------- | -------- | ---------------------------------------------------------- |\n| **ASPIRE001** | Warning  | Resource name contains invalid characters                  |\n| **ASPIRE002** | Warning  | Duplicate resource name detected                           |\n| **ASPIRE003** | Error    | Missing required package reference                         |\n| **ASPIRE004** | Warning  | Deprecated API usage                                       |\n| **ASPIRE005** | Error    | Invalid endpoint configuration                             |\n| **ASPIRE006** | Warning  | Health check not configured for resource with `.WaitFor()` |\n| **ASPIRE007** | Warning  | Container image tag not specified (using `latest`)         |\n| **ASPIRE008** | Error    | Circular dependency detected in resource graph             |\n\n### Experimental diagnostics (ASPIREHOSTINGX\\*)\n\nThese codes indicate usage of experimental/preview APIs. They may require `#pragma warning disable` or `\u003cNoWarn\u003e` if you intentionally use experimental features:\n\n| Code                      | Area                             |\n| ------------------------- | -------------------------------- |\n| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs        |\n| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs    |\n| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs     |\n| ASPIRE_HOSTINGX_0016–0022 | Experimental resource model APIs |\n\nTo suppress experimental warnings:\n\n```xml\n\u003c!-- In .csproj --\u003e\n\u003cPropertyGroup\u003e\n  \u003cNoWarn\u003e$(NoWarn);ASPIRE_HOSTINGX_0001\u003c/NoWarn\u003e\n\u003c/PropertyGroup\u003e\n```\n\nOr per-line:\n\n```csharp\n#pragma warning disable ASPIRE_HOSTINGX_0001\nvar resource = builder.AddExperimentalResource(\"test\");\n#pragma warning restore ASPIRE_HOSTINGX_0001\n```\n\n---\n\n## Common Issues \u0026 Solutions\n\n### Container runtime\n\n| Problem                           | Solution                                                                                               |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| \"Cannot connect to Docker daemon\" | Start Docker Desktop / Podman / Rancher Desktop                                                        |\n| Container fails to start          | Check `docker ps -a` for exit codes; check dashboard console logs                                      |\n| Port already in use               | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |\n| Container image pull fails        | Check network connectivity; verify image name and tag                                                  |\n| \"Permission denied\" on Linux      | Add user to `docker` group: `sudo usermod -aG docker $USER`                                            |\n\n### Service discovery\n\n| Problem                       | Solution                                                                     |\n| ----------------------------- | ---------------------------------------------------------------------------- |\n| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard            |\n| Connection string is null     | The reference resource name doesn't match; check `ConnectionStrings__\u003cname\u003e` |\n| Wrong port in service URL     | Check `targetPort` vs actual service listen port                             |\n| Env var not set               | Rebuild AppHost; verify resource name matches exactly                        |\n\n### Python workloads\n\n| Problem                           | Solution                                                        |\n| --------------------------------- | --------------------------------------------------------------- |\n| \"Python not found\"                | Ensure Python is on PATH; specify full path in `AddPythonApp()` |\n| venv not found                    | Use `.WithVirtualEnvironment()` or create venv manually         |\n| pip packages fail to install      | Use `.WithPipPackages()` or install in venv before `aspire run` |\n| ModuleNotFoundError               | venv isn't activated; `.WithVirtualEnvironment()` handles this  |\n| \"Port already in use\" for Uvicorn | Check `targetPort` — another instance may be running            |\n\n### JavaScript / TypeScript workloads\n\n| Problem                       | Solution                                                         |\n| ----------------------------- | ---------------------------------------------------------------- |\n| \"node_modules not found\"      | Use `.WithNpmPackageInstallation()` to auto-install              |\n| npm install fails             | Check `package.json` is valid; check npm registry connectivity   |\n| Vite dev server won't start   | Verify `vite` is in devDependencies; check Vite config           |\n| Port mismatch                 | Ensure `targetPort` matches the port in your JS framework config |\n| TypeScript compilation errors | These happen in the service, not Aspire — check service logs     |\n\n### Go workloads\n\n| Problem                    | Solution                                                   |\n| -------------------------- | ---------------------------------------------------------- |\n| \"go not found\"             | Ensure Go is installed and on PATH                         |\n| Build fails                | Check `go.mod` exists in working directory                 |\n| \"no Go files in directory\" | Verify `workingDir` points to the directory with `main.go` |\n\n### Java workloads\n\n| Problem                  | Solution                                                |\n| ------------------------ | ------------------------------------------------------- |\n| \"java not found\"         | Ensure JDK is installed and `JAVA_HOME` is set          |\n| Maven/Gradle build fails | Verify build files exist; check build tool installation |\n| Spring Boot won't start  | Check `application.properties`; verify main class       |\n\n### Rust workloads\n\n| Problem              | Solution                                                             |\n| -------------------- | -------------------------------------------------------------------- |\n| \"cargo not found\"    | Install Rust via rustup                                              |\n| Build takes too long | Rust compile times are normal; use `.WithCargoBuild()` for pre-build |\n\n### Health checks \u0026 startup\n\n| Problem                      | Solution                                                                       |\n| ---------------------------- | ------------------------------------------------------------------------------ |\n| Resource stuck in \"Starting\" | Health check endpoint not responding; check service logs                       |\n| `.WaitFor()` timeout         | Increase timeout or fix health endpoint; default is 30 seconds                 |\n| Health check always fails    | Verify endpoint path (default: `/health`); check service binds to correct port |\n| Cascading startup failures   | A dependency failed; check the root resource first                             |\n\n### Dashboard\n\n| Problem                               | Solution                                                                  |\n| ------------------------------------- | ------------------------------------------------------------------------- |\n| Dashboard doesn't open                | Check terminal for URL; use `--dashboard-port` for fixed port             |\n| No logs appearing                     | Service may not be writing to stdout/stderr; check console output         |\n| No traces for non-.NET services       | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |\n| Traces don't show cross-service calls | Propagate trace context headers (`traceparent`, `tracestate`)             |\n\n### Build \u0026 configuration\n\n| Problem                                   | Solution                                                            |\n| ----------------------------------------- | ------------------------------------------------------------------- |\n| \"Project not found\" for `AddProject\u003cT\u003e()` | Ensure `.csproj` is in the solution and referenced by AppHost       |\n| Package version conflicts                 | Pin all Aspire packages to the same version                         |\n| AppHost won't build                       | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore`  |\n| `aspire run` build error                  | Fix the build error first; `aspire run` requires a successful build |\n\n### Deployment\n\n| Problem                                  | Solution                                                             |\n| ---------------------------------------- | -------------------------------------------------------------------- |\n| `aspire publish` fails                   | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |\n| Generated Bicep has errors               | Check for unsupported resource configurations                        |\n| Container image push fails               | Verify registry credentials and permissions                          |\n| Missing connection strings in deployment | Check generated ConfigMaps/Secrets match resource names              |\n\n---\n\n## Debugging strategies\n\n### 1. Check the dashboard first\n\nThe dashboard shows resource state, logs, traces, and metrics. Start here for any issue.\n\n### 2. Check environment variables\n\nIn the dashboard, click a resource to see all injected environment variables. Verify connection strings and service URLs are correct.\n\n### 3. Read console logs\n\nDashboard → Console Logs → filter by the failing resource. Raw stdout/stderr often contains the root cause.\n\n### 4. Check the DAG\n\nIf services fail to start, check the dependency order. A failed dependency blocks all downstream resources.\n\n### 5. Use MCP for AI-assisted debugging\n\nIf MCP is configured (see [MCP Server](mcp-server.md)), ask your AI assistant:\n\n- \"What resources are failing?\"\n- \"Show me the logs for [service]\"\n- \"What traces show errors?\"\n\n### 6. Isolate the problem\n\nRun just the failing resource by commenting out others in the AppHost. This narrows whether the issue is the resource itself or a dependency.\n\n---\n\n## Getting help\n\n| Channel                 | URL                                            |\n| ----------------------- | ---------------------------------------------- |\n| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues        |\n| GitHub Issues (docs)    | https://github.com/microsoft/aspire.dev/issues |\n| Discord                 | https://aka.ms/aspire/discord                  |\n| Stack Overflow          | Tag: `dotnet-aspire`                           |\n| Reddit                  | https://www.reddit.com/r/aspiredotdev/         |\n"},"import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/tree/541b7819d8c3545c6df122491af4fa1eae415779/skills/aspire"}},"content_hash":[128,10,92,36,169,165,214,110,158,146,96,112,155,228,1,141,60,224,39,214,46,251,197,82,213,94,157,75,232,140,168,235],"trust_level":"unsigned","yanked":false}