Aspire Orchestration
MANDATORY COMPLIANCE — This skill prevents agent self-harm in Aspire projects.
Violating these rules causes file locks, orphaned processes, and user frustration (#15801).
Prerequisites
| Requirement |
Install |
| .NET 10.0 SDK |
https://dotnet.microsoft.com/download |
| Aspire CLI (curl/PowerShell) |
curl -sSL https://aspire.dev/install.sh | bash |
| Aspire CLI (NativeAOT global tool, .NET 10) |
dotnet tool install -g Aspire.Cli |
Either install method works. The dotnet tool install path produces a NativeAOT binary
(instant startup, no JIT warmup) and is the recommended option when .NET 10 is already present.
Detection
Activate when ANY signal is present:
| Signal |
How to Detect |
Confidence |
| C# AppHost |
.csproj containing Aspire.AppHost.Sdk |
✅ Definitive |
| File-based C# AppHost |
apphost.cs or .cs file with #:sdk Aspire.AppHost.Sdk |
✅ Definitive |
| TypeScript AppHost |
apphost.ts file in project |
✅ Definitive |
| Aspire config |
aspire.config.json in project root |
High |
| Aspire settings |
.aspire/ directory present |
High |
| Generated TS modules |
.aspire/modules/ directory present |
High |
| Service defaults |
Aspire.ServiceDefaults in project references |
Medium |
See detection.md for detailed fingerprinting.
Safety Guardrails
| Situation |
✅ ALWAYS Do |
❌ NEVER Do |
| Start an Aspire app |
aspire start |
dotnet run on AppHost |
| Wait for resource ready |
aspire wait <resource> |
curl / HTTP polling loops |
| Code changed in a resource |
Prefer resource commands, runtime watch/HMR, dashboard actions, or IDE-managed debugging |
dotnet build against locked files |
| Task complete |
aspire stop |
Leave processes running |
| Check resource status |
aspire describe / aspire ps |
Manual process inspection |
| Working in git worktree |
aspire start --isolated |
aspire start without isolation |
| Running from AI agent |
Add --non-interactive to all commands |
Assuming interactive terminal |
| Editing unfamiliar API |
aspire docs search <topic> then aspire docs api search <query> for API reference |
Guessing API shape |
| C# AppHost API inspection |
Use dotnet-inspect skill (if available) for local symbols |
Guessing overloads or builder chains |
| Adding custom dashboard/resource commands |
aspire docs search "custom resource commands" first |
Inventing WithCommand patterns without docs |
| Installing Aspire support |
Use aspire add or aspire init |
dotnet workload install aspire (obsolete) |
See safety-guardrails.md for detailed rules and recovery patterns.
Default Workflow
- Confirm workspace is Aspire — identify the AppHost
aspire start (or aspire start --isolated in worktrees)
aspire wait <resource> before interacting with any resource
aspire describe to inspect state, then work
- If AppHost code changed, rerun
aspire start; if only one resource changed, prefer the resource's commands/watch/HMR/debug workflow
aspire stop when cleanup is explicitly requested or needed to release locks/ports
Quick Reference
| Task |
Command |
| Start app (agents) |
aspire start (background, preferred) |
| Start app (human) |
aspire run (foreground, dashboard) |
| Stop app |
aspire stop |
| Wait for resource |
aspire wait <resource> |
| Check status |
aspire ps or aspire describe |
| Show hidden resources (proxies, helpers, migrations) |
aspire ps --include-hidden / aspire describe --include-hidden |
| Resource operation |
aspire resource <resource-name> <command> such as stop, start, or rebuild when exposed |
| Create new project |
aspire new aspire-starter |
| Add Aspire to existing |
aspire init (then hand off to aspireify skill for wiring) |
| Add integration |
aspire add <package> |
| Discover integrations |
aspire integration list --format Json / aspire integration search <query> --format Json |
| Upgrade the CLI itself |
aspire update --self |
| Update project package refs |
aspire update (modifies project files — get user approval) |
| Restore generated files |
aspire restore |
| Environment maintenance |
aspire cache clear, aspire certs trust, aspire certs clean |
| Diagnose environment |
aspire doctor |
| Machine-readable output |
--format Json (supported: ps, describe, start) |
| Look up API reference |
aspire docs api search <query> --language csharp|typescript |
| Browse API entries |
aspire docs api list <scope> |
| Get API detail |
aspire docs api get <id> |
Error Handling
| Symptom |
Cause |
Action |
File lock errors during build (MSB3491, CS2012) |
Aspire is running and holds locks on bin/, obj/, and assemblies. |
Run aspire stop first, then rebuild or aspire start. Do NOT conclude the project has a permanent build failure. |
| "Port already in use" |
Previous instance running |
aspire stop, then aspire start |
| Resource not found |
App not started or name wrong |
aspire ps to check |
| Build errors in resource |
Code error, not Aspire issue |
Fix code, then use resource commands/watch/HMR/debug workflow or rerun aspire start if AppHost code changed |
| Environment issues |
Missing SDK or tools |
aspire doctor to diagnose |
JSON parse failure from aspire start |
Mixed human/JSON output (#15843) |
Strip non-JSON lines before parsing |
aspire wait rejects name |
Use displayName not name (#15842) |
Use displayName from aspire ps --format Json |
aspire ps hangs |
AppHost on breakpoint (#15576) |
Use timeout, check AppHost process |
aspire agent init fails |
Non-interactive terminal (#16264) |
Run from standard terminal |
| Docker daemon unavailable |
Container-backed resources fail to start |
Start Docker Desktop, then aspire start |
| Multiple AppHosts detected |
Wrong AppHost targeted |
Use --apphost <path> to specify explicitly |
🔒 File-Lock Recovery (MSB3491 / CS2012) — Always aspire stop First
When a build fails with error MSB3491: Could not write to output file ... or
error CS2012: Cannot open ... for writing, the project itself is healthy —
Aspire is running and holding file locks on the resource's output assemblies.
The recovery is always the same:
# ✅ Correct recovery sequence
aspire stop # release the locks
# ... then either rebuild / restart one resource if the resource exposes commands ...
aspire resource <name> rebuild # example: C# project resource with rebuild command
# ... or restart the whole AppHost ...
aspire start # if AppHost code changed or Aspire was already stopped
| ❌ NEVER do |
✅ ALWAYS do |
| Tell the user the project has a permanent build failure |
Recognize the lock as Aspire holding outputs and run aspire stop |
dotnet build again with locks held |
aspire stop first, then dotnet build (or prefer resource commands/watch/HMR/debug workflow) |
Delete bin/ / obj/ to "fix" the lock |
aspire stop — deletion may succeed but the next build relocks |
pkill dotnet or kill <PID> to free locks |
aspire stop — clean shutdown via the CLI, no orphans |
| Tell the user to "reboot" or "restart your machine" |
aspire stop — single command, instant fix |
The same rule applies to any "file in use", "cannot access the file", or
"another process is using" error during a build of an Aspire-managed resource.
Handoff Rules
| Scenario |
Route To |
AppHost wiring after aspire init (scan repo, add resources, ServiceDefaults/OTel) |
→ aspireify skill (../aspireify/SKILL.md) or project-local .agents/skills/aspireify/SKILL.md |
Browser logs (Aspire.Hosting.Browsers / WithBrowserLogs()) and dashboard authoring |
→ aspireify skill (code edits) and aspire-monitoring (discovery) |
Custom resource commands (WithCommand, ExecuteCommandResult, HttpCommandResultMode) |
→ aspireify skill |
Lifecycle hooks (SubscribeBeforeStart, SubscribeAfterResourcesCreated, BeforeStart pipeline phase) |
→ aspireify skill |
Endpoint authoring (WithEndpoint updates, ExcludeReferenceEndpoint flag) |
→ aspireify skill |
Deploy, publish, pipeline steps, aspire destroy |
→ aspire-deployment skill |
Logs, traces, metrics, dashboard, aspire dashboard run |
→ aspire-monitoring skill |
| Deployed app diagnostics |
→ azure-diagnostics skill (azure-skills) |
Runtime Settings And Environment
| Variable |
Default |
Purpose |
ASPIRE_ENABLE_CONTAINER_TUNNEL |
true |
Container tunnel provides uniform host connectivity across Docker Desktop, Docker Engine, and Podman. Set to false to opt out. |
ASPIRE_ENVIRONMENT |
unset |
Selects the environment-specific config profile — controls which appsettings.{environment}.json is loaded and which environment is reported in dashboard telemetry. |
ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE |
true |
The Aspire trusted developer certificate is used by DCP on Windows. Set to false to opt out. |
features.defaultWatchEnabled |
false unless configured |
Enables Aspire default watch for supported C# and TypeScript AppHosts. Do not treat this as per-resource rebuild, restart, or hot reload for resource source changes. |
TypeScript AppHost Note
Detection covers TS AppHosts (apphost.ts), but all TS AppHost authoring is delegated to aspireify.
Current rules to apply when handing off:
| Rule |
Why |
Prefer unified withEnvironment(name, value) over deprecated per-kind helpers (withEnvironmentEndpoint, withEnvironmentParameter, withEnvironmentConnectionString, withEnvironmentExpression, withEnvironmentFromOutput, withEnvironmentFromKeyVaultSecret) |
Per-kind helpers are deprecated — single API now handles all value types |
Never edit .aspire/modules/ directly |
Generated; use aspire add <package> to regenerate and aspire restore to recover missing files |
Use aspire docs api search <query> --language typescript for API lookup |
TS surface differs from C# |
Skill Routing — In-Plugin Sibling Skills
After aspire init drops a skeleton AppHost + aspire.config.json, route AppHost wiring
(scan repo → propose resource graph → edit AppHost → wire Aspire.ServiceDefaults / OTel →
validate via aspire start) to the in-plugin aspireify skill: ../aspireify/SKILL.md.
For first-run flows that only need the skeleton drop, see the in-plugin aspire-init skill:
../aspire-init/SKILL.md. This orchestration skill stays focused
on lifecycle (start/stop/wait/restart) and never edits AppHost code itself.
Project-Local Skill Precedence
If .agents/skills/aspire/SKILL.md exists (from aspire agent init), defer to it for:
C# AppHost editing, TS AppHost editing, Playwright handoff, investigation workflows.
Safety guardrails from this plugin ALWAYS apply.
If .agents/skills/aspireify/SKILL.md exists project-locally (installed by aspire init in
current Aspire), warn the user that a project-local aspireify skill is present and defer to it
for AppHost wiring instead of the in-plugin sibling. Same precedence rule as the project-local
aspire skill above: project-local wins, plugin guardrails still apply.
References
- safety-guardrails.md — Detailed rules and recovery patterns
- detection.md — Project fingerprinting
- app-commands.md — App lifecycle and bootstrap commands
- resource-management.md — Resource wait, restart, and operations
- agent-workflows.md — Common agent investigation, integration, TypeScript, and handoff workflows
1---2name: aspire-orchestration3description: >-4 **WORKFLOW SKILL** — Manage Aspire AppHost lifecycle and recover from file locks,5 port conflicts, and orphaned processes. WHEN: "start my Aspire app", "aspire start",6 "aspire stop", "aspire wait", "restart the API service", "file lock error",7 "MSB3491", "CS2012", "port already in use", "upgrade Aspire CLI", "aspire update --self",8 "proxies missing in aspire ps", "--include-hidden", "aspire integration list",9 "aspire integration search", "default watch", "hot reload". INVOKES: aspire CLI10 (start, stop, wait, ps, resource, integration, add, init, doctor, update, restore).11 FOR SINGLE OPERATIONS: Run the aspire CLI command directly.12license: MIT13metadata:14 source: https://skillmd.com/skills/dotnet/aspire-orchestration15 author: Microsoft16 version: "0.0.1"17---1819# Aspire Orchestration2021> **MANDATORY COMPLIANCE** — This skill prevents agent self-harm in Aspire projects.22> Violating these rules causes file locks, orphaned processes, and user frustration ([#15801](https://github.com/microsoft/aspire/issues/15801)).2324## Prerequisites2526| Requirement | Install |27|-------------|---------|28| .NET 10.0 SDK | https://dotnet.microsoft.com/download |29| Aspire CLI (curl/PowerShell) | `curl -sSL https://aspire.dev/install.sh \| bash` |30| Aspire CLI (NativeAOT global tool, .NET 10) | `dotnet tool install -g Aspire.Cli` |3132Either install method works. The `dotnet tool install` path produces a NativeAOT binary33(instant startup, no JIT warmup) and is the recommended option when .NET 10 is already present.3435## Detection3637Activate when ANY signal is present:3839| Signal | How to Detect | Confidence |40|--------|---------------|------------|41| C# AppHost | `.csproj` containing `Aspire.AppHost.Sdk` | ✅ Definitive |42| File-based C# AppHost | `apphost.cs` or `.cs` file with `#:sdk Aspire.AppHost.Sdk` | ✅ Definitive |43| TypeScript AppHost | `apphost.ts` file in project | ✅ Definitive |44| Aspire config | `aspire.config.json` in project root | High |45| Aspire settings | `.aspire/` directory present | High |46| Generated TS modules | `.aspire/modules/` directory present | High |47| Service defaults | `Aspire.ServiceDefaults` in project references | Medium |4849See [detection.md](references/detection.md) for detailed fingerprinting.5051## Safety Guardrails5253| Situation | ✅ ALWAYS Do | ❌ NEVER Do |54|-----------|-------------|------------|55| Start an Aspire app | `aspire start` | `dotnet run` on AppHost |56| Wait for resource ready | `aspire wait <resource>` | `curl` / HTTP polling loops |57| Code changed in a resource | Prefer resource commands, runtime watch/HMR, dashboard actions, or IDE-managed debugging | `dotnet build` against locked files |58| Task complete | `aspire stop` | Leave processes running |59| Check resource status | `aspire describe` / `aspire ps` | Manual process inspection |60| Working in git worktree | `aspire start --isolated` | `aspire start` without isolation |61| Running from AI agent | Add `--non-interactive` to all commands | Assuming interactive terminal |62| Editing unfamiliar API | `aspire docs search <topic>` then `aspire docs api search <query>` for API reference | Guessing API shape |63| C# AppHost API inspection | Use `dotnet-inspect` skill (if available) for local symbols | Guessing overloads or builder chains |64| Adding custom dashboard/resource commands | `aspire docs search "custom resource commands"` first | Inventing `WithCommand` patterns without docs |65| Installing Aspire support | Use `aspire add` or `aspire init` | ~~`dotnet workload install aspire`~~ (obsolete) |6667See [safety-guardrails.md](references/safety-guardrails.md) for detailed rules and recovery patterns.6869## Default Workflow70711. Confirm workspace is Aspire — identify the AppHost722. `aspire start` (or `aspire start --isolated` in worktrees)733. `aspire wait <resource>` before interacting with any resource744. `aspire describe` to inspect state, then work755. If AppHost code changed, rerun `aspire start`; if only one resource changed, prefer the resource's commands/watch/HMR/debug workflow766. `aspire stop` when cleanup is explicitly requested or needed to release locks/ports7778## Quick Reference7980| Task | Command |81|------|---------|82| Start app (agents) | `aspire start` (background, preferred) |83| Start app (human) | `aspire run` (foreground, dashboard) |84| Stop app | `aspire stop` |85| Wait for resource | `aspire wait <resource>` |86| Check status | `aspire ps` or `aspire describe` |87| Show hidden resources (proxies, helpers, migrations) | `aspire ps --include-hidden` / `aspire describe --include-hidden` |88| Resource operation | `aspire resource <resource-name> <command>` such as `stop`, `start`, or `rebuild` when exposed |89| Create new project | `aspire new aspire-starter` |90| Add Aspire to existing | `aspire init` (then hand off to `aspireify` skill for wiring) |91| Add integration | `aspire add <package>` |92| Discover integrations | `aspire integration list --format Json` / `aspire integration search <query> --format Json` |93| Upgrade the CLI itself | `aspire update --self` |94| Update project package refs | `aspire update` (modifies project files — get user approval) |95| Restore generated files | `aspire restore` |96| Environment maintenance | `aspire cache clear`, `aspire certs trust`, `aspire certs clean` |97| Diagnose environment | `aspire doctor` |98| Machine-readable output | `--format Json` (supported: `ps`, `describe`, `start`) |99| Look up API reference | `aspire docs api search <query> --language csharp\|typescript` |100| Browse API entries | `aspire docs api list <scope>` |101| Get API detail | `aspire docs api get <id>` |102103## Error Handling104105| Symptom | Cause | Action |106|---------|-------|--------|107| **File lock errors during build (`MSB3491`, `CS2012`)** | **Aspire is running and holds locks on `bin/`, `obj/`, and assemblies.** | **Run `aspire stop` first**, then rebuild or `aspire start`. Do NOT conclude the project has a permanent build failure. |108| "Port already in use" | Previous instance running | `aspire stop`, then `aspire start` |109| Resource not found | App not started or name wrong | `aspire ps` to check |110| Build errors in resource | Code error, not Aspire issue | Fix code, then use resource commands/watch/HMR/debug workflow or rerun `aspire start` if AppHost code changed |111| Environment issues | Missing SDK or tools | `aspire doctor` to diagnose |112| JSON parse failure from `aspire start` | Mixed human/JSON output ([#15843](https://github.com/microsoft/aspire/issues/15843)) | Strip non-JSON lines before parsing |113| `aspire wait` rejects name | Use `displayName` not `name` ([#15842](https://github.com/microsoft/aspire/issues/15842)) | Use `displayName` from `aspire ps --format Json` |114| `aspire ps` hangs | AppHost on breakpoint ([#15576](https://github.com/microsoft/aspire/issues/15576)) | Use timeout, check AppHost process |115| `aspire agent init` fails | Non-interactive terminal ([#16264](https://github.com/microsoft/aspire/issues/16264)) | Run from standard terminal |116| Docker daemon unavailable | Container-backed resources fail to start | Start Docker Desktop, then `aspire start` |117| Multiple AppHosts detected | Wrong AppHost targeted | Use `--apphost <path>` to specify explicitly |118119### 🔒 File-Lock Recovery (MSB3491 / CS2012) — Always `aspire stop` First120121When a build fails with `error MSB3491: Could not write to output file ...` or122`error CS2012: Cannot open ... for writing`, the project itself is healthy —123**Aspire is running and holding file locks** on the resource's output assemblies.124The recovery is always the same:125126```bash127# ✅ Correct recovery sequence128aspire stop # release the locks129# ... then either rebuild / restart one resource if the resource exposes commands ...130aspire resource <name> rebuild # example: C# project resource with rebuild command131# ... or restart the whole AppHost ...132aspire start # if AppHost code changed or Aspire was already stopped133```134135| ❌ NEVER do | ✅ ALWAYS do |136|------------|-------------|137| Tell the user the project has a permanent build failure | Recognize the lock as Aspire holding outputs and run `aspire stop` |138| `dotnet build` again with locks held | `aspire stop` first, then `dotnet build` (or prefer resource commands/watch/HMR/debug workflow) |139| Delete `bin/` / `obj/` to "fix" the lock | `aspire stop` — deletion may succeed but the next build relocks |140| `pkill dotnet` or `kill <PID>` to free locks | `aspire stop` — clean shutdown via the CLI, no orphans |141| Tell the user to "reboot" or "restart your machine" | `aspire stop` — single command, instant fix |142143The same rule applies to any "file in use", "cannot access the file", or144"another process is using" error during a build of an Aspire-managed resource.145146## Handoff Rules147148| Scenario | Route To |149|----------|----------|150| AppHost wiring after `aspire init` (scan repo, add resources, ServiceDefaults/OTel) | → `aspireify` skill ([`../aspireify/SKILL.md`](../aspireify/SKILL.md)) or project-local `.agents/skills/aspireify/SKILL.md` |151| Browser logs (`Aspire.Hosting.Browsers` / `WithBrowserLogs()`) and dashboard authoring | → `aspireify` skill (code edits) and `aspire-monitoring` (discovery) |152| Custom resource commands (`WithCommand`, `ExecuteCommandResult`, `HttpCommandResultMode`) | → `aspireify` skill |153| Lifecycle hooks (`SubscribeBeforeStart`, `SubscribeAfterResourcesCreated`, BeforeStart pipeline phase) | → `aspireify` skill |154| Endpoint authoring (`WithEndpoint` updates, `ExcludeReferenceEndpoint` flag) | → `aspireify` skill |155| Deploy, publish, pipeline steps, `aspire destroy` | → `aspire-deployment` skill |156| Logs, traces, metrics, dashboard, `aspire dashboard run` | → `aspire-monitoring` skill |157| Deployed app diagnostics | → `azure-diagnostics` skill (azure-skills) |158159## Runtime Settings And Environment160161| Variable | Default | Purpose |162|----------|---------|---------|163| `ASPIRE_ENABLE_CONTAINER_TUNNEL` | `true` | Container tunnel provides uniform host connectivity across Docker Desktop, Docker Engine, and Podman. Set to `false` to opt out. |164| `ASPIRE_ENVIRONMENT` | unset | Selects the environment-specific config profile — controls which `appsettings.{environment}.json` is loaded and which environment is reported in dashboard telemetry. |165| `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` | `true` | The Aspire trusted developer certificate is used by DCP on Windows. Set to `false` to opt out. |166| `features.defaultWatchEnabled` | false unless configured | Enables Aspire default watch for supported C# and TypeScript AppHosts. Do not treat this as per-resource rebuild, restart, or hot reload for resource source changes. |167168## TypeScript AppHost Note169170Detection covers TS AppHosts (`apphost.ts`), but **all TS AppHost authoring is delegated to `aspireify`**.171Current rules to apply when handing off:172173| Rule | Why |174|------|-----|175| Prefer unified `withEnvironment(name, value)` over deprecated per-kind helpers (`withEnvironmentEndpoint`, `withEnvironmentParameter`, `withEnvironmentConnectionString`, `withEnvironmentExpression`, `withEnvironmentFromOutput`, `withEnvironmentFromKeyVaultSecret`) | Per-kind helpers are deprecated — single API now handles all value types |176| Never edit `.aspire/modules/` directly | Generated; use `aspire add <package>` to regenerate and `aspire restore` to recover missing files |177| Use `aspire docs api search <query> --language typescript` for API lookup | TS surface differs from C# |178179## Skill Routing — In-Plugin Sibling Skills180181After `aspire init` drops a skeleton AppHost + `aspire.config.json`, route AppHost wiring182(scan repo → propose resource graph → edit AppHost → wire `Aspire.ServiceDefaults` / OTel →183validate via `aspire start`) to the in-plugin **aspireify** skill: [`../aspireify/SKILL.md`](../aspireify/SKILL.md).184For first-run flows that only need the skeleton drop, see the in-plugin **aspire-init** skill:185[`../aspire-init/SKILL.md`](../aspire-init/SKILL.md). This orchestration skill stays focused186on lifecycle (start/stop/wait/restart) and never edits AppHost code itself.187188## Project-Local Skill Precedence189190If `.agents/skills/aspire/SKILL.md` exists (from `aspire agent init`), defer to it for:191C# AppHost editing, TS AppHost editing, Playwright handoff, investigation workflows.192Safety guardrails from this plugin ALWAYS apply.193194If `.agents/skills/aspireify/SKILL.md` exists project-locally (installed by `aspire init` in195current Aspire), **warn the user** that a project-local aspireify skill is present and **defer to it**196for AppHost wiring instead of the in-plugin sibling. Same precedence rule as the project-local197`aspire` skill above: project-local wins, plugin guardrails still apply.198199## References200201- [safety-guardrails.md](references/safety-guardrails.md) — Detailed rules and recovery patterns202- [detection.md](references/detection.md) — Project fingerprinting203- [app-commands.md](references/app-commands.md) — App lifecycle and bootstrap commands204- [resource-management.md](references/resource-management.md) — Resource wait, restart, and operations205- [agent-workflows.md](references/agent-workflows.md) — Common agent investigation, integration, TypeScript, and handoff workflows