Skip to content

Commit 33096fc

Browse files
aaronpowellaaronpowell
authored
Merge pull request #669 from ChrisMcKee1/add-aspire-skill
feat: Add Aspire polyglot distributed-app orchestration skill
2 parents 7de4b48 + 2244cc6 commit 33096fc

File tree

11 files changed

+2377
-0
lines changed

11 files changed

+2377
-0
lines changed

‎docs/README.skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
2424
| ---- | ----------- | -------------- |
2525
| [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:<br />- Implementing self-critique and reflection loops<br />- Building evaluator-optimizer pipelines for quality-critical generation<br />- Creating test-driven code refinement workflows<br />- Designing rubric-based or LLM-as-judge evaluation systems<br />- Adding iterative improvement to agent outputs (code, reports, analysis)<br />- Measuring and improving agent response quality | None |
2626
| [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`<br />`examples/appinsights.bicep`<br />`references/ASPNETCORE.md`<br />`references/AUTO.md`<br />`references/NODEJS.md`<br />`references/PYTHON.md`<br />`scripts/appinsights.ps1` |
27+
| [aspire](../skills/aspire/SKILL.md) | 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. | `references/architecture.md`<br />`references/cli-reference.md`<br />`references/dashboard.md`<br />`references/deployment.md`<br />`references/integrations-catalog.md`<br />`references/mcp-server.md`<br />`references/polyglot-apis.md`<br />`references/testing.md`<br />`references/troubleshooting.md` |
2728
| [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`<br />`references/REPORT-TEMPLATE.md`<br />`references/VALIDATION-COMMANDS.md` |
2829
| [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | None |
2930
| [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`<br />`assets/template-architecture.md` |

‎skills/aspire/SKILL.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
name: aspire
3+
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.'
4+
---
5+
6+
# Aspire — Polyglot Distributed-App Orchestration
7+
8+
Aspire 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.
9+
10+
> **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.
11+
12+
Detailed reference material lives in the `references/` folder — load on demand.
13+
14+
---
15+
16+
## References
17+
18+
| Reference | When to load |
19+
|---|---|
20+
| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |
21+
| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |
22+
| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |
23+
| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |
24+
| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |
25+
| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |
26+
| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |
27+
| [Testing](references/testing.md) | Integration tests against the AppHost |
28+
| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |
29+
30+
---
31+
32+
## 1. Researching Aspire Documentation
33+
34+
The 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.
35+
36+
### Aspire CLI 13.2+ (recommended — has built-in docs search)
37+
38+
If running Aspire CLI **13.2 or later** (`aspire --version`), the MCP server includes docs search tools:
39+
40+
| Tool | Description |
41+
|---|---|
42+
| `list_docs` | Lists all available documentation from aspire.dev |
43+
| `search_docs` | Performs weighted lexical search across indexed documentation |
44+
| `get_doc` | Retrieves a specific document by its slug |
45+
46+
These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028). To update: `aspire update --self --channel daily`.
47+
48+
For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/
49+
50+
### Aspire CLI 13.1 (integration tools only)
51+
52+
On 13.1, the MCP server provides integration lookup but **not** docs search:
53+
54+
| Tool | Description |
55+
|---|---|
56+
| `list_integrations` | Lists available Aspire hosting integrations |
57+
| `get_integration_docs` | Gets documentation for a specific integration package |
58+
59+
For general docs queries on 13.1, use **Context7** as your primary source (see below).
60+
61+
### Fallback: Context7
62+
63+
Use **Context7** (`mcp_context7`) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:
64+
65+
**Step 1 — Resolve the library ID** (one-time per session):
66+
67+
Call `mcp_context7_resolve-library-id` with `libraryName: ".NET Aspire"`.
68+
69+
| Rank | Library ID | Use when |
70+
|---|---|---|
71+
| 1 | `/microsoft/aspire.dev` | Primary source. Guides, integrations, CLI reference, deployment. |
72+
| 2 | `/dotnet/aspire` | API internals, source-level implementation details. |
73+
| 3 | `/communitytoolkit/aspire` | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |
74+
75+
**Step 2 — Query docs:**
76+
77+
```
78+
libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
79+
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"
80+
```
81+
82+
### Fallback: GitHub search (when Context7 is also unavailable)
83+
84+
Search the official docs repo on GitHub:
85+
- **Docs repo:** `microsoft/aspire.dev` — path: `src/frontend/src/content/docs/`
86+
- **Source repo:** `dotnet/aspire`
87+
- **Samples repo:** `dotnet/aspire-samples`
88+
- **Community integrations:** `CommunityToolkit/Aspire`
89+
90+
---
91+
92+
## 2. Prerequisites & Install
93+
94+
| Requirement | Details |
95+
|---|---|
96+
| **.NET SDK** | 10.0+ (required even for non-.NET workloads — the AppHost is .NET) |
97+
| **Container runtime** | Docker Desktop, Podman, or Rancher Desktop |
98+
| **IDE (optional)** | VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider |
99+
100+
```bash
101+
# Linux / macOS
102+
curl -sSL https://aspire.dev/install.sh | bash
103+
104+
# Windows PowerShell
105+
irm https://aspire.dev/install.ps1 | iex
106+
107+
# Verify
108+
aspire --version
109+
110+
# Install templates
111+
dotnet new install Aspire.ProjectTemplates
112+
```
113+
114+
---
115+
116+
## 3. Project Templates
117+
118+
| Template | Command | Description |
119+
|---|---|---|
120+
| **aspire-starter** | `aspire new aspire-starter` | ASP.NET Core/Blazor starter + AppHost + tests |
121+
| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | ASP.NET Core/React starter + AppHost |
122+
| **aspire-py-starter** | `aspire new aspire-py-starter` | FastAPI/React starter + AppHost |
123+
| **aspire-apphost-singlefile** | `aspire new aspire-apphost-singlefile` | Empty single-file AppHost |
124+
125+
---
126+
127+
## 4. AppHost Quick Start (Polyglot)
128+
129+
The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.
130+
131+
```csharp
132+
var builder = DistributedApplication.CreateBuilder(args);
133+
134+
// Infrastructure
135+
var redis = builder.AddRedis("cache");
136+
var postgres = builder.AddPostgres("pg").AddDatabase("catalog");
137+
138+
// .NET API
139+
var api = builder.AddProject<Projects.CatalogApi>("api")
140+
.WithReference(postgres).WithReference(redis);
141+
142+
// Python ML service
143+
var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
144+
.WithHttpEndpoint(targetPort: 8000).WithReference(redis);
145+
146+
// React frontend (Vite)
147+
var web = builder.AddViteApp("web", "../frontend")
148+
.WithHttpEndpoint(targetPort: 5173).WithReference(api);
149+
150+
// Go worker
151+
var worker = builder.AddGolangApp("worker", "../go-worker")
152+
.WithReference(redis);
153+
154+
builder.Build().Run();
155+
```
156+
157+
For complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).
158+
159+
---
160+
161+
## 5. Core Concepts (Summary)
162+
163+
| Concept | Key point |
164+
|---|---|
165+
| **Run vs Publish** | `aspire run` = local dev (DCP engine). `aspire publish` = generate deployment manifests. |
166+
| **Service discovery** | Automatic via env vars: `ConnectionStrings__<name>`, `services__<name>__http__0` |
167+
| **Resource lifecycle** | DAG ordering — dependencies start first. `.WaitFor()` gates on health checks. |
168+
| **Resource types** | `ProjectResource`, `ContainerResource`, `ExecutableResource`, `ParameterResource` |
169+
| **Integrations** | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |
170+
| **Dashboard** | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run`. |
171+
| **MCP Server** | AI assistants can query running apps and search docs via CLI (STDIO). |
172+
| **Testing** | `Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit. |
173+
| **Deployment** | Docker, Kubernetes, Azure Container Apps, Azure App Service. |
174+
175+
---
176+
177+
## 6. CLI Quick Reference
178+
179+
Valid commands in Aspire CLI 13.1:
180+
181+
| Command | Description | Status |
182+
|---|---|---|
183+
| `aspire new <template>` | Create from template | Stable |
184+
| `aspire init` | Initialize in existing project | Stable |
185+
| `aspire run` | Start all resources locally | Stable |
186+
| `aspire add <integration>` | Add an integration | Stable |
187+
| `aspire publish` | Generate deployment manifests | Preview |
188+
| `aspire config` | Manage configuration settings | Stable |
189+
| `aspire cache` | Manage disk cache | Stable |
190+
| `aspire deploy` | Deploy to defined targets | Preview |
191+
| `aspire do <step>` | Execute a pipeline step | Preview |
192+
| `aspire update` | Update integrations (or `--self` for CLI) | Preview |
193+
| `aspire mcp init` | Configure MCP for AI assistants | Stable |
194+
| `aspire mcp start` | Start the MCP server | Stable |
195+
196+
Full command reference with flags: [CLI Reference](references/cli-reference.md).
197+
198+
---
199+
200+
## 7. Common Patterns
201+
202+
### Adding a new service
203+
204+
1. Create your service directory (any language)
205+
2. Add to AppHost: `Add*App()` or `AddProject<T>()`
206+
3. Wire dependencies: `.WithReference()`
207+
4. Gate on health: `.WaitFor()` if needed
208+
5. Run: `aspire run`
209+
210+
### Migrating from Docker Compose
211+
212+
1. `aspire new aspire-apphost-singlefile` (empty AppHost)
213+
2. Replace each `docker-compose` service with an Aspire resource
214+
3. `depends_on` → `.WithReference()` + `.WaitFor()`
215+
4. `ports` → `.WithHttpEndpoint()`
216+
5. `environment` → `.WithEnvironment()` or `.WithReference()`
217+
218+
---
219+
220+
## 8. Key URLs
221+
222+
| Resource | URL |
223+
|---|---|
224+
| **Documentation** | https://aspire.dev |
225+
| **Runtime repo** | https://github.com/dotnet/aspire |
226+
| **Docs repo** | https://github.com/microsoft/aspire.dev |
227+
| **Samples** | https://github.com/dotnet/aspire-samples |
228+
| **Community Toolkit** | https://github.com/CommunityToolkit/Aspire |
229+
| **Dashboard image** | `mcr.microsoft.com/dotnet/aspire-dashboard` |
230+
| **Discord** | https://aka.ms/aspire/discord |
231+
| **Reddit** | https://www.reddit.com/r/aspiredotdev/ |

0 commit comments

Comments
 (0)