Aspireify
One-time wiring skill. aspire init drops a skeleton; aspireify turns
that skeleton into a working AppHost by scanning the repo, proposing a resource
graph, editing the AppHost, wiring Aspire.ServiceDefaults, and validating end
to end. Self-deactivates after a clean aspire start. Aligned with Aspire 13.4
guidance from the current Aspire development branch.
🚫 Hard Refusal: Never Edit .aspire/modules/
⛔ REFUSE any request to edit, modify, change, open-for-edit, or "tweak" files
inside .aspire/modules/ of a TypeScript AppHost. This directory is generated by Aspire
from apphost.ts and the integration packages — every file in it gets clobbered
on the next build, aspire add, or aspire start.
If a user asks to edit something in .aspire/modules/ (e.g., .aspire/modules/postgres.module.ts),
the correct response is:
- Refuse the edit with a clear "I won't edit
.aspire/modules/" statement.
- Explain that
.aspire/modules/ is generated and any changes are clobbered.
- Redirect the requested change to
apphost.ts — the only file the user
should hand-edit in a TS AppHost.
- If the user wants a new integration, suggest
aspire add <package>; if they want
to change configuration, show the equivalent edit in apphost.ts.
| ❌ Wrong |
✅ Right |
Open .aspire/modules/postgres.module.ts and tweak the connection options |
Edit apphost.ts and change addPostgres('pg', { ... }) options there |
Modify a generated .aspire/modules/*.ts file directly |
Re-run aspire add <package> after updating apphost.ts |
Comment out a line in .aspire/modules/ to disable a resource |
Remove or guard the resource declaration in apphost.ts |
This rule applies even if the user insists, even for "one-line" changes, even for
"just to test something." The TS AppHost regenerates .aspire/modules/ deterministically;
edits are unrecoverable noise.
Guiding Principles From Aspire 13.4
Minimize changes to the user's code
Adapt the AppHost to fit the app, not the other way around. Prefer WithEnvironment()
to match existing environment variable names, Aspire-managed ports over fixed ports,
and 1:1 Docker Compose mapping before optimizing. Do not restructure directories,
rename files, or change build scripts unless the user explicitly chooses that tradeoff.
Surface tradeoffs; do not decide silently
When a small code change unlocks better Aspire integration, present both options:
the zero-code-change mapping and the small-change version that enables WithReference,
health checks, service discovery, dynamic ports, or dashboard telemetry. Ask which
approach the user wants, then implement that choice without complaint.
Verify APIs before writing AppHost code
Use aspire docs search <topic> and aspire docs get <slug> for workflow guidance.
Use aspire docs api search <query> --language csharp|typescript and
aspire docs api get <id> for API shape. Use aspire integration list/search to
find integrations before aspire add. Do not invent packages, methods, overloads,
or command shapes; C# and TypeScript AppHost APIs differ.
Keep configuration visible in the AppHost
Scan .env, .env.local, .env.development, secrets.json.example,
<UserSecretsId>, and setup scripts. Propose migrating values into AppHost parameters:
connection strings become Aspire resources, API keys/tokens become secret parameters,
and non-secret config becomes plain parameters or WithEnvironment() values. Never
delete .env files or remove existing UserSecretsId entries without explicit user
approval because non-Aspire workflows may still depend on them.
Local development first
This skill optimizes local development, not production deployment. Prefer persistent
container lifetimes and data volumes for databases/caches, use HTTPS endpoints by
default, pass endpoint references instead of hardcoded URLs, and model external SaaS
URLs/API keys as parameters so they are visible in the dashboard.
Redis TLS edge case
Aspire can automatically provision TLS certificates for container resources. If Redis
health checks fail with SSL/TLS handshake errors, do not fall back to AddContainer().
Use WithoutHttpsCertificate() on the Redis resource when the consuming app expects
plain Redis.
Project-Local Override
If .agents/skills/aspireify/SKILL.md exists (installed by aspire init or
aspire agent init --skills aspireify), warn the user that a project-local
copy is present and defer to it. The plugin version is the fallback.
⚠️ Project-local .agents/skills/aspireify/SKILL.md detected — deferring to it.
Prerequisites
| Requirement |
Install |
| .NET 10.0 SDK (C# AppHost) |
https://dotnet.microsoft.com/download |
| Node.js 20+ (TS AppHost) |
https://nodejs.org |
| Aspire CLI |
curl -sSL https://aspire.dev/install.sh | bash or dotnet tool install -g Aspire.Cli |
| Skeleton already dropped |
aspire init produced aspire.config.json + AppHost stub |
Detection — When to Activate
Activate when ANY signal is present AND the AppHost is unwired (no resources
declared beyond the stub):
| Signal |
How to Detect |
Confidence |
| Skeleton just dropped |
aspire init just ran in this session |
✅ Definitive |
| Empty AppHost stub |
apphost.cs / Program.cs / apphost.ts only contains Build().Run() |
✅ Definitive |
aspire.config.json without resources |
Config present, AppHost has no AddProject/addProject |
High |
| User asks to "wire" / "scaffold resource graph" |
Verb match: wire, scaffold, integrate, hook up, add Postgres/Redis/etc. |
High |
| User asks "what next after aspire init" |
Direct handoff request |
✅ Definitive |
| Existing repo with services + new AppHost |
Repo has .csproj/package.json projects but AppHost references none |
High |
If the AppHost already has wired resources and the user wants to start/stop
the app → aspire-orchestration. If the user wants to deploy → aspire-deployment.
Language Support
| AppHost Style |
Detection |
Edit Target |
| C# SDK-style |
.csproj containing <Sdk Name="Aspire.AppHost.Sdk" /> |
Program.cs (top-level statements) |
| File-based C# |
apphost.cs with #:sdk Aspire.AppHost.Sdk and #:package directives |
apphost.cs itself |
| TypeScript |
apphost.ts with generated .aspire/modules/ |
apphost.ts only — never edit .aspire/modules/ |
See references/csharp-authoring.md and
references/typescript-authoring.md.
Workflow Phases
1. SCAN → discover projects, services, dependencies, integration candidates
2. PROPOSE → resource graph + integration list, confirm with user
3. EDIT → wire AppHost, add ServiceDefaults + OTel + health checks
4. VALIDATE → aspire start --non-interactive → aspire wait <each resource>
5. DEACTIVATE → confirm clean start, hand off to aspire-orchestration
For the detailed, upstream-parity workflow, load these references before editing:
- apphost-wiring.md — full AppHost wiring workflow, API lookup, endpoint/parameter patterns, validation, solution updates, and cleanup.
- docker-compose.md — docker-compose migration, profiles, image mapping, ports, volumes, and
depends_on.
- full-solution-apphosts.md — large solution triage, mixed SDK boundaries, solution membership, ServiceDefaults placement, and legacy host migration.
- javascript-apps.md — JavaScript resource selection, workspace/monorepo package-manager handling, ports, scripts, and TS AppHost package config.
- opentelemetry.md — optional Node.js, Python, and Go OpenTelemetry wiring for non-.NET services.
1. Scan
Walk the repo and inventory:
| What |
How |
| .NET projects |
find . -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*' |
| Node services |
find . -name 'package.json' -not -path '*/node_modules/*' |
| Python services |
find . -name 'pyproject.toml' -o -name 'requirements.txt' |
| Container deps in compose |
docker-compose.yml, compose.yaml (Postgres? Redis? Rabbit?) |
| Connection strings |
grep appsettings*.json, .env*, config/* for Postgres, Redis, Mongo, RabbitMQ, Cosmos, ServiceBus |
| Integration packages |
dotnet list package per project; package.json dependencies |
| Existing endpoints |
hardcoded ports in launchSettings.json, next.config.js, vite.config.ts |
Full heuristics in references/scan-and-propose.md.
2. Propose
Present a resource graph before editing. Ask clarifying questions:
- "I see Postgres in
docker-compose.yml — should I model it as AddPostgres('db') or use Azure Database for PostgreSQL?"
- "Your React app hardcodes
http://localhost:5000 — replace with Aspire service discovery (endpoint.url)?"
- "Your API has an
/admin endpoint — exclude it from WithReference() so consumers don't see it?"
3. Edit
Apply the proposed graph. Use the right authoring style for the AppHost language.
4. Validate
aspire start --non-interactive --format Json
aspire wait <resource> # repeat for each declared resource
aspire describe --format Json # sanity check graph
Full validation flow + recovery in references/validation.md.
5. Self-Deactivate
After a clean aspire start, announce:
✅ AppHost wired and validated. Handing off to aspire-orchestration for
day-to-day start/stop/wait. Aspireify is done.
Integration Discovery Catalog
Map detected services → Aspire integrations. See
references/scan-and-propose.md for the full
catalog.
| Detected |
C# |
TS |
Postgres in compose / Npgsql package |
AddPostgres("pg").AddDatabase("db") |
addPostgres('pg').addDatabase('db') |
Redis in compose / StackExchange.Redis |
AddRedis("cache") |
addRedis('cache') |
| RabbitMQ |
AddRabbitMQ("mq") (v7 client w/ pub-sub tracing) |
addRabbitMQ('mq') |
| MongoDB |
AddMongoDB("mongo") |
addMongoDB('mongo') |
| Cosmos DB |
AddAzureCosmosDB("cosmos") |
addAzureCosmosDB('cosmos') |
| Azure Service Bus |
AddAzureServiceBus("sb") |
addAzureServiceBus('sb') |
| Azure Cache for Redis (Entra) |
AddAzureRedis("cache") (now GA) |
addAzureRedis('cache') |
| Next.js frontend |
AddNextJsApp("web", "./web") |
addNextJsApp('web', '../web') |
| Vite SPA |
AddViteApp("web", "./web") |
addViteApp('web', '../web') |
| Plain Node app |
AddNodeApp("api", "server.js") |
addNodeApp('api', 'server.js') |
Current Authoring Rules
| Rule |
Why |
Use unified withEnvironment(name, value) in TS — never the deprecated per-kind helpers (withEnvironmentEndpoint, withEnvironmentParameter, etc.) |
Single API handles all value kinds; per-kind helpers are deprecated |
Use AddNextJsApp / AddViteApp over hand-rolled Dockerfiles for JS frontends |
First-class lifecycle + PublishAs* integration |
Use PublishAsStaticWebsite / PublishAsNodeServer / PublishAsPackageScript for JS publish |
Replaces hand-rolled Dockerfiles; SPA → static, SSR Node → NodeServer, package-script SSR → PackageScript |
Add WithBrowserLogs() to frontend resources for browser console + screenshots in dashboard |
Aspire.Hosting.Browsers surfaces browser telemetry in the dashboard |
Bind every resource to a compute environment with WithComputeEnvironment(env) when multiple environments exist |
Multi-environment deploys require explicit binding |
Never edit .aspire/modules/ in TS AppHosts |
Generated; edits get clobbered. Edit only apphost.ts |
Use WithEndpoint("name", e => ...) to update endpoints |
Endpoint callbacks update existing endpoints rather than throwing on duplicates |
Mark admin endpoints with ExcludeReferenceEndpoint = true |
Prevents consumers from receiving admin URLs via WithReference() |
Look up unfamiliar API: aspire docs api search <query> --language csharp|typescript |
Don't guess overloads or builder chains |
C# vs TS Quick Reference
| Concept |
C# |
TypeScript |
| Builder |
var builder = DistributedApplication.CreateBuilder(args); |
const builder = await createBuilder(); |
| Add project |
builder.AddProject<Projects.Api>("api") (SDK) or AddProject("api", "../Api/Api.csproj") |
await builder.addProject('api', '../Api/Api.csproj') |
| Wire env var (any value type) |
.WithEnvironment("KEY", value) |
.withEnvironment('KEY', value) ← unified API |
| Wait for dependency |
.WaitFor(db) |
.waitFor(db) |
| Pass connection |
.WithReference(db) |
.withReference(db) |
| External HTTP |
.WithExternalHttpEndpoints() |
.withExternalHttpEndpoints() |
| Endpoint expression |
api.GetEndpoint("http") |
api.getEndpoint('http').url / .host / .port |
| Build + run |
builder.Build().Run(); |
await builder.build().run(); |
ServiceDefaults Wiring
Each project should call builder.AddServiceDefaults(); to opt into OpenTelemetry,
health checks, and service discovery. Add the Aspire.ServiceDefaults project
reference (or NuGet for non-monorepo). See
references/service-defaults.md.
Endpoint & Reference Conventions
// Public-facing API. Mark "admin" endpoint as not-for-consumers.
var api = builder.AddProject<Projects.Api>("api")
.WithExternalHttpEndpoints()
.WithEndpoint("admin", e => e.ExcludeReferenceEndpoint = true);
// Frontend wires the API via service discovery.
builder.AddNextJsApp("web", "./web")
.WithReference(api) // injects services__api__http and __https
.WaitFor(api)
.WithBrowserLogs(); // browser console + screenshots
Validation & Recovery
| Symptom |
Action |
aspire start fails with build error |
Fix code, re-run aspire start |
aspire wait rejects resource name |
Use displayName from aspire ps --format Json (#15842) |
| File-lock errors during edit |
Hand off to aspire-orchestration → aspire stop → retry |
Resource missing from aspire ps |
May be hidden — re-run with --include-hidden |
| TS AppHost change ignored |
Confirm you edited apphost.ts, not .aspire/modules/ |
Mixed JSON output from aspire start |
Strip non-JSON lines before parsing (#15843) |
Full flow in references/validation.md.
Handoff Rules
| Scenario |
Route To |
| AppHost skeleton not yet dropped |
→ aspire-init skill |
| Day-to-day start/stop/wait/restart |
→ aspire-orchestration skill |
| Publish, deploy, destroy, pipeline steps |
→ aspire-deployment skill |
| Logs, traces, metrics, dashboard, browser log inspection |
→ aspire-monitoring skill |
| Deployed (Azure/AKS) app diagnostics |
→ azure-diagnostics skill (azure-skills) |
Key Rules
- Never overwrite existing files — always augment or merge.
- Ask before modifying service code, especially OpenTelemetry and ServiceDefaults injection.
- Respect existing project structure — do not reorganize the repo.
- If stuck, use
aspire doctor to diagnose environment issues.
- Never hardcode URLs in
WithEnvironment / withEnvironment — pass endpoint references such as api.GetEndpoint("http") or api.getEndpoint('http') instead of string literals.
- Never use
WithUrlForEndpoint / withUrlForEndpoint to set dev.localhost URLs — that API is only for dashboard display labels; dev.localhost belongs in AppHost launch/profile configuration.
References
- apphost-wiring.md — Detailed AppHost wiring workflow and API lookup patterns
- docker-compose.md — Docker Compose migration patterns
- full-solution-apphosts.md — Large/full-solution AppHost guidance
- javascript-apps.md — JavaScript/TypeScript app and workspace handling
- opentelemetry.md — Non-.NET OpenTelemetry setup
- scan-and-propose.md — Repo scan heuristics + integration catalog
- csharp-authoring.md — C# AppHost patterns
- typescript-authoring.md — TS AppHost patterns + parity APIs
- service-defaults.md — Wire OTel, health checks, service discovery
- validation.md — End-to-end validation + recovery
1---2name: aspireify3description: >-4 **WORKFLOW SKILL** - Wire an Aspire AppHost after `aspire init` drops a skeleton.5 Scans the repo, proposes a resource graph, edits the AppHost (C#, file-based C#, or6 TypeScript), wires `Aspire.ServiceDefaults` + OTel, validates with `aspire start`,7 then self-deactivates.8 USE FOR: wire AppHost, scaffold resource graph, add Postgres/Redis/Rabbit/Mongo to9 Aspire, connect frontend to API, after `aspire init` what next, AddNextJsApp, AddViteApp,10 WithBrowserLogs, file-based apphost.cs, apphost.ts, unified withEnvironment,11 refuse .aspire/modules edit, migrate .env files, migrate user secrets.12 DO NOT USE FOR: skeleton drop (use aspire-init), start/stop/wait/restart (use13 aspire-orchestration), publish/deploy/destroy (use aspire-deployment), logs/traces14 (use aspire-monitoring).15 INVOKES: aspire CLI (add, start, wait, describe, docs api search, stop), AppHost16 source edits, ServiceDefaults wiring.17 FOR SINGLE OPERATIONS: Run `aspire add PACKAGE` directly for a one-off integration.18license: MIT19metadata:20 source: https://skillmd.com/skills/dotnet/aspireify21 author: Microsoft22 version: "0.0.1"23---2425# Aspireify2627> **One-time wiring skill.** `aspire init` drops a skeleton; `aspireify` turns28> that skeleton into a working AppHost by scanning the repo, proposing a resource29> graph, editing the AppHost, wiring `Aspire.ServiceDefaults`, and validating end30> to end. Self-deactivates after a clean `aspire start`. Aligned with Aspire 13.431> guidance from the current Aspire development branch.3233## 🚫 Hard Refusal: Never Edit `.aspire/modules/`3435> ⛔ **REFUSE** any request to edit, modify, change, open-for-edit, or "tweak" files36> inside `.aspire/modules/` of a TypeScript AppHost. This directory is **generated** by Aspire37> from `apphost.ts` and the integration packages — every file in it gets **clobbered38> on the next build, `aspire add`, or `aspire start`**.39>40> If a user asks to edit something in `.aspire/modules/` (e.g., `.aspire/modules/postgres.module.ts`),41> the correct response is:42>43> 1. **Refuse the edit** with a clear "I won't edit `.aspire/modules/`" statement.44> 2. **Explain** that `.aspire/modules/` is generated and any changes are clobbered.45> 3. **Redirect** the requested change to `apphost.ts` — the **only** file the user46> should hand-edit in a TS AppHost.47> 4. If the user wants a new integration, suggest `aspire add <package>`; if they want48> to change configuration, show the equivalent edit in `apphost.ts`.4950| ❌ Wrong | ✅ Right |51|----------|---------|52| Open `.aspire/modules/postgres.module.ts` and tweak the connection options | Edit `apphost.ts` and change `addPostgres('pg', { ... })` options there |53| Modify a generated `.aspire/modules/*.ts` file directly | Re-run `aspire add <package>` after updating `apphost.ts` |54| Comment out a line in `.aspire/modules/` to disable a resource | Remove or guard the resource declaration in `apphost.ts` |5556This rule applies even if the user insists, even for "one-line" changes, even for57"just to test something." The TS AppHost regenerates `.aspire/modules/` deterministically;58edits are unrecoverable noise.5960## Guiding Principles From Aspire 13.46162### Minimize changes to the user's code6364Adapt the AppHost to fit the app, not the other way around. Prefer `WithEnvironment()`65to match existing environment variable names, Aspire-managed ports over fixed ports,66and 1:1 Docker Compose mapping before optimizing. Do not restructure directories,67rename files, or change build scripts unless the user explicitly chooses that tradeoff.6869### Surface tradeoffs; do not decide silently7071When a small code change unlocks better Aspire integration, present both options:72the zero-code-change mapping and the small-change version that enables `WithReference`,73health checks, service discovery, dynamic ports, or dashboard telemetry. Ask which74approach the user wants, then implement that choice without complaint.7576### Verify APIs before writing AppHost code7778Use `aspire docs search <topic>` and `aspire docs get <slug>` for workflow guidance.79Use `aspire docs api search <query> --language csharp|typescript` and80`aspire docs api get <id>` for API shape. Use `aspire integration list/search` to81find integrations before `aspire add`. Do not invent packages, methods, overloads,82or command shapes; C# and TypeScript AppHost APIs differ.8384### Keep configuration visible in the AppHost8586Scan `.env`, `.env.local`, `.env.development`, `secrets.json.example`,87`<UserSecretsId>`, and setup scripts. Propose migrating values into AppHost parameters:88connection strings become Aspire resources, API keys/tokens become secret parameters,89and non-secret config becomes plain parameters or `WithEnvironment()` values. Never90delete `.env` files or remove existing `UserSecretsId` entries without explicit user91approval because non-Aspire workflows may still depend on them.9293### Local development first9495This skill optimizes local development, not production deployment. Prefer persistent96container lifetimes and data volumes for databases/caches, use HTTPS endpoints by97default, pass endpoint references instead of hardcoded URLs, and model external SaaS98URLs/API keys as parameters so they are visible in the dashboard.99100### Redis TLS edge case101102Aspire can automatically provision TLS certificates for container resources. If Redis103health checks fail with SSL/TLS handshake errors, do not fall back to `AddContainer()`.104Use `WithoutHttpsCertificate()` on the Redis resource when the consuming app expects105plain Redis.106107## Project-Local Override108109If `.agents/skills/aspireify/SKILL.md` exists (installed by `aspire init` or110`aspire agent init --skills aspireify`), **warn the user** that a project-local111copy is present and **defer to it**. The plugin version is the fallback.112113```114⚠️ Project-local .agents/skills/aspireify/SKILL.md detected — deferring to it.115```116117## Prerequisites118119| Requirement | Install |120|-------------|---------|121| .NET 10.0 SDK (C# AppHost) | https://dotnet.microsoft.com/download |122| Node.js 20+ (TS AppHost) | https://nodejs.org |123| Aspire CLI | `curl -sSL https://aspire.dev/install.sh \| bash` or `dotnet tool install -g Aspire.Cli` |124| Skeleton already dropped | `aspire init` produced `aspire.config.json` + AppHost stub |125126## Detection — When to Activate127128Activate when ANY signal is present **AND** the AppHost is unwired (no resources129declared beyond the stub):130131| Signal | How to Detect | Confidence |132|--------|---------------|------------|133| Skeleton just dropped | `aspire init` just ran in this session | ✅ Definitive |134| Empty AppHost stub | `apphost.cs` / `Program.cs` / `apphost.ts` only contains `Build().Run()` | ✅ Definitive |135| `aspire.config.json` without resources | Config present, AppHost has no `AddProject`/`addProject` | High |136| User asks to "wire" / "scaffold resource graph" | Verb match: wire, scaffold, integrate, hook up, add Postgres/Redis/etc. | High |137| User asks "what next after aspire init" | Direct handoff request | ✅ Definitive |138| Existing repo with services + new AppHost | Repo has `.csproj`/`package.json` projects but AppHost references none | High |139140If the AppHost already has wired resources and the user wants to **start/stop**141the app → `aspire-orchestration`. If the user wants to **deploy** → `aspire-deployment`.142143## Language Support144145| AppHost Style | Detection | Edit Target |146|---------------|-----------|-------------|147| **C# SDK-style** | `.csproj` containing `<Sdk Name="Aspire.AppHost.Sdk" />` | `Program.cs` (top-level statements) |148| **File-based C#** | `apphost.cs` with `#:sdk Aspire.AppHost.Sdk` and `#:package` directives | `apphost.cs` itself |149| **TypeScript** | `apphost.ts` with generated `.aspire/modules/` | `apphost.ts` only — **never edit `.aspire/modules/`** |150151See [references/csharp-authoring.md](references/csharp-authoring.md) and152[references/typescript-authoring.md](references/typescript-authoring.md).153154## Workflow Phases155156```1571. SCAN → discover projects, services, dependencies, integration candidates1582. PROPOSE → resource graph + integration list, confirm with user1593. EDIT → wire AppHost, add ServiceDefaults + OTel + health checks1604. VALIDATE → aspire start --non-interactive → aspire wait <each resource>1615. DEACTIVATE → confirm clean start, hand off to aspire-orchestration162```163164For the detailed, upstream-parity workflow, load these references before editing:165166- [apphost-wiring.md](references/apphost-wiring.md) — full AppHost wiring workflow, API lookup, endpoint/parameter patterns, validation, solution updates, and cleanup.167- [docker-compose.md](references/docker-compose.md) — docker-compose migration, profiles, image mapping, ports, volumes, and `depends_on`.168- [full-solution-apphosts.md](references/full-solution-apphosts.md) — large solution triage, mixed SDK boundaries, solution membership, ServiceDefaults placement, and legacy host migration.169- [javascript-apps.md](references/javascript-apps.md) — JavaScript resource selection, workspace/monorepo package-manager handling, ports, scripts, and TS AppHost package config.170- [opentelemetry.md](references/opentelemetry.md) — optional Node.js, Python, and Go OpenTelemetry wiring for non-.NET services.171172### 1. Scan173174Walk the repo and inventory:175176| What | How |177|------|-----|178| .NET projects | `find . -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*'` |179| Node services | `find . -name 'package.json' -not -path '*/node_modules/*'` |180| Python services | `find . -name 'pyproject.toml' -o -name 'requirements.txt'` |181| Container deps in compose | `docker-compose.yml`, `compose.yaml` (Postgres? Redis? Rabbit?) |182| Connection strings | grep `appsettings*.json`, `.env*`, `config/*` for `Postgres`, `Redis`, `Mongo`, `RabbitMQ`, `Cosmos`, `ServiceBus` |183| Integration packages | `dotnet list package` per project; package.json `dependencies` |184| Existing endpoints | hardcoded ports in `launchSettings.json`, `next.config.js`, `vite.config.ts` |185186Full heuristics in [references/scan-and-propose.md](references/scan-and-propose.md).187188### 2. Propose189190Present a resource graph **before editing**. Ask clarifying questions:191192- "I see Postgres in `docker-compose.yml` — should I model it as `AddPostgres('db')` or use Azure Database for PostgreSQL?"193- "Your React app hardcodes `http://localhost:5000` — replace with Aspire service discovery (`endpoint.url`)?"194- "Your API has an `/admin` endpoint — exclude it from `WithReference()` so consumers don't see it?"195196### 3. Edit197198Apply the proposed graph. Use the right authoring style for the AppHost language.199200### 4. Validate201202```bash203aspire start --non-interactive --format Json204aspire wait <resource> # repeat for each declared resource205aspire describe --format Json # sanity check graph206```207208Full validation flow + recovery in [references/validation.md](references/validation.md).209210### 5. Self-Deactivate211212After a clean `aspire start`, announce:213214```215✅ AppHost wired and validated. Handing off to aspire-orchestration for216 day-to-day start/stop/wait. Aspireify is done.217```218219## Integration Discovery Catalog220221Map detected services → Aspire integrations. See222[references/scan-and-propose.md](references/scan-and-propose.md) for the full223catalog.224225| Detected | C# | TS |226|----------|----|----|227| Postgres in compose / `Npgsql` package | `AddPostgres("pg").AddDatabase("db")` | `addPostgres('pg').addDatabase('db')` |228| Redis in compose / `StackExchange.Redis` | `AddRedis("cache")` | `addRedis('cache')` |229| RabbitMQ | `AddRabbitMQ("mq")` (v7 client w/ pub-sub tracing) | `addRabbitMQ('mq')` |230| MongoDB | `AddMongoDB("mongo")` | `addMongoDB('mongo')` |231| Cosmos DB | `AddAzureCosmosDB("cosmos")` | `addAzureCosmosDB('cosmos')` |232| Azure Service Bus | `AddAzureServiceBus("sb")` | `addAzureServiceBus('sb')` |233| Azure Cache for Redis (Entra) | `AddAzureRedis("cache")` (now GA) | `addAzureRedis('cache')` |234| Next.js frontend | `AddNextJsApp("web", "./web")` | `addNextJsApp('web', '../web')` |235| Vite SPA | `AddViteApp("web", "./web")` | `addViteApp('web', '../web')` |236| Plain Node app | `AddNodeApp("api", "server.js")` | `addNodeApp('api', 'server.js')` |237238## Current Authoring Rules239240| Rule | Why |241|------|-----|242| Use **unified `withEnvironment(name, value)`** in TS — never the deprecated per-kind helpers (`withEnvironmentEndpoint`, `withEnvironmentParameter`, etc.) | Single API handles all value kinds; per-kind helpers are deprecated |243| Use `AddNextJsApp` / `AddViteApp` over hand-rolled Dockerfiles for JS frontends | First-class lifecycle + `PublishAs*` integration |244| Use `PublishAsStaticWebsite` / `PublishAsNodeServer` / `PublishAsPackageScript` for JS publish | Replaces hand-rolled Dockerfiles; SPA → static, SSR Node → NodeServer, package-script SSR → PackageScript |245| Add `WithBrowserLogs()` to frontend resources for browser console + screenshots in dashboard | `Aspire.Hosting.Browsers` surfaces browser telemetry in the dashboard |246| Bind every resource to a compute environment with `WithComputeEnvironment(env)` when multiple environments exist | Multi-environment deploys require explicit binding |247| **Never edit `.aspire/modules/`** in TS AppHosts | Generated; edits get clobbered. Edit only `apphost.ts` |248| Use `WithEndpoint("name", e => ...)` to update endpoints | Endpoint callbacks update existing endpoints rather than throwing on duplicates |249| Mark admin endpoints with `ExcludeReferenceEndpoint = true` | Prevents consumers from receiving admin URLs via `WithReference()` |250| Look up unfamiliar API: `aspire docs api search <query> --language csharp\|typescript` | Don't guess overloads or builder chains |251252## C# vs TS Quick Reference253254| Concept | C# | TypeScript |255|---------|----|------------|256| Builder | `var builder = DistributedApplication.CreateBuilder(args);` | `const builder = await createBuilder();` |257| Add project | `builder.AddProject<Projects.Api>("api")` (SDK) or `AddProject("api", "../Api/Api.csproj")` | `await builder.addProject('api', '../Api/Api.csproj')` |258| Wire env var (any value type) | `.WithEnvironment("KEY", value)` | `.withEnvironment('KEY', value)` ← unified API |259| Wait for dependency | `.WaitFor(db)` | `.waitFor(db)` |260| Pass connection | `.WithReference(db)` | `.withReference(db)` |261| External HTTP | `.WithExternalHttpEndpoints()` | `.withExternalHttpEndpoints()` |262| Endpoint expression | `api.GetEndpoint("http")` | `api.getEndpoint('http').url` / `.host` / `.port` |263| Build + run | `builder.Build().Run();` | `await builder.build().run();` |264265## ServiceDefaults Wiring266267Each project should call `builder.AddServiceDefaults();` to opt into OpenTelemetry,268health checks, and service discovery. Add the `Aspire.ServiceDefaults` project269reference (or NuGet for non-monorepo). See270[references/service-defaults.md](references/service-defaults.md).271272## Endpoint & Reference Conventions273274```csharp275// Public-facing API. Mark "admin" endpoint as not-for-consumers.276var api = builder.AddProject<Projects.Api>("api")277 .WithExternalHttpEndpoints()278 .WithEndpoint("admin", e => e.ExcludeReferenceEndpoint = true);279280// Frontend wires the API via service discovery.281builder.AddNextJsApp("web", "./web")282 .WithReference(api) // injects services__api__http and __https283 .WaitFor(api)284 .WithBrowserLogs(); // browser console + screenshots285```286287## Validation & Recovery288289| Symptom | Action |290|---------|--------|291| `aspire start` fails with build error | Fix code, re-run `aspire start` |292| `aspire wait` rejects resource name | Use `displayName` from `aspire ps --format Json` ([#15842](https://github.com/microsoft/aspire/issues/15842)) |293| File-lock errors during edit | Hand off to `aspire-orchestration` → `aspire stop` → retry |294| Resource missing from `aspire ps` | May be hidden — re-run with `--include-hidden` |295| TS AppHost change ignored | Confirm you edited `apphost.ts`, not `.aspire/modules/` |296| Mixed JSON output from `aspire start` | Strip non-JSON lines before parsing ([#15843](https://github.com/microsoft/aspire/issues/15843)) |297298Full flow in [references/validation.md](references/validation.md).299300## Handoff Rules301302| Scenario | Route To |303|----------|----------|304| AppHost skeleton not yet dropped | → `aspire-init` skill |305| Day-to-day start/stop/wait/restart | → `aspire-orchestration` skill |306| Publish, deploy, destroy, pipeline steps | → `aspire-deployment` skill |307| Logs, traces, metrics, dashboard, browser log inspection | → `aspire-monitoring` skill |308| Deployed (Azure/AKS) app diagnostics | → `azure-diagnostics` skill (azure-skills) |309310## Key Rules311312- **Never overwrite existing files** — always augment or merge.313- **Ask before modifying service code**, especially OpenTelemetry and ServiceDefaults injection.314- **Respect existing project structure** — do not reorganize the repo.315- **If stuck, use `aspire doctor`** to diagnose environment issues.316- **Never hardcode URLs in `WithEnvironment` / `withEnvironment`** — pass endpoint references such as `api.GetEndpoint("http")` or `api.getEndpoint('http')` instead of string literals.317- **Never use `WithUrlForEndpoint` / `withUrlForEndpoint` to set `dev.localhost` URLs** — that API is only for dashboard display labels; `dev.localhost` belongs in AppHost launch/profile configuration.318319## References320321- [apphost-wiring.md](references/apphost-wiring.md) — Detailed AppHost wiring workflow and API lookup patterns322- [docker-compose.md](references/docker-compose.md) — Docker Compose migration patterns323- [full-solution-apphosts.md](references/full-solution-apphosts.md) — Large/full-solution AppHost guidance324- [javascript-apps.md](references/javascript-apps.md) — JavaScript/TypeScript app and workspace handling325- [opentelemetry.md](references/opentelemetry.md) — Non-.NET OpenTelemetry setup326- [scan-and-propose.md](references/scan-and-propose.md) — Repo scan heuristics + integration catalog327- [csharp-authoring.md](references/csharp-authoring.md) — C# AppHost patterns328- [typescript-authoring.md](references/typescript-authoring.md) — TS AppHost patterns + parity APIs329- [service-defaults.md](references/service-defaults.md) — Wire OTel, health checks, service discovery330- [validation.md](references/validation.md) — End-to-end validation + recovery