Back to Details

aspireify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Aspireify

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
.
一次性搭建技能。 
aspire init
会生成骨架结构；
aspireify
通过扫描仓库、提出资源图方案、编辑AppHost、配置
Aspire.ServiceDefaults
并进行端到端验证，将该骨架转化为可运行的AppHost。在
aspire start
成功运行后会自动停用。

🚫 Hard Refusal: Never Edit 
.aspire/modules/

🚫 严格拒绝：绝不编辑 
.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 from the installed Aspire integration package graph. It is regenerated by 
aspire add
, 
aspire restore
, and startup when package changes require it.
If a user asks to edit something in 
.aspire/modules/
(e.g., 
.aspire/modules/postgres.module.ts
), the correct response is:
  1. Refuse the edit with a clear "I won't edit 
    .aspire/modules/
    " statement.
  2. Explain that 
    .aspire/modules/
    is generated and any changes are clobbered.
  3. Redirect the requested change to the configured AppHost entry point: current 
    apphost.mts
    , or legacy 
    apphost.ts
    .
  4. If the user wants a new integration, suggest 
    aspire add <package>
    ; if they want to change configuration, show the equivalent edit in the AppHost entry point.
❌ Wrong✅ Right
Open 
.aspire/modules/postgres.module.ts
and tweak the connection options		Edit 
apphost.mts
and change 
addPostgres('pg', { ... })
options there
Modify a generated 
.aspire/modules/*
file directly		Re-run 
aspire add <package>
after updating 
apphost.mts
Comment out a line in 
.aspire/modules/
to disable a resource		Remove or guard the resource declaration in 
apphost.mts
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.
⛔ 拒绝任何编辑、修改、更改、打开编辑或“微调”TypeScript AppHost中
.aspire/modules/
目录下文件的请求。该目录是根据已安装的Aspire集成包依赖图自动生成的。当包发生变更时，
aspire add
、
aspire restore
命令以及启动过程都会重新生成该目录。
如果用户要求编辑
.aspire/modules/
中的内容（例如
.aspire/modules/postgres.module.ts
），正确的响应方式是：
  1. 拒绝编辑，明确说明“我不会编辑
    .aspire/modules/
    目录”。
  2. 解释
    .aspire/modules/
    是自动生成的，任何修改都会被覆盖。
  3. 引导用户在配置的AppHost入口文件中进行修改：当前版本为
    apphost.mts
    ，旧版本为
    apphost.ts
    。
  4. 如果用户需要新的集成，建议使用
    aspire add <package>
    ；如果用户想要修改配置，展示在AppHost入口文件中的等效修改方式。
❌ 错误做法✅ 正确做法
打开
.aspire/modules/postgres.module.ts
并微调连接选项		编辑
apphost.mts
，在其中修改
addPostgres('pg', { ... })
的选项
直接修改生成的
.aspire/modules/*
文件		更新
apphost.mts
后重新运行
aspire add <package>
注释掉
.aspire/modules/
中的某一行来禁用某个资源		在
apphost.mts
中移除或条件化资源声明
即使用户坚持要求，哪怕是“一行代码”的修改，甚至只是“测试一下”，都必须遵守此规则。TS AppHost会确定性地重新生成
.aspire/modules/
目录，编辑操作产生的修改会被覆盖且无法恢复。

Guiding Principles

指导原则

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.
让AppHost适配现有应用，而非反过来。优先使用
WithEnvironment()
匹配现有的环境变量名，优先使用Aspire管理的端口而非固定端口，在优化前先保持与Docker Compose的1:1映射。除非用户明确选择接受相应的取舍，否则不要重构目录、重命名文件或修改构建脚本。

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.
当少量代码修改可以带来更好的Aspire集成效果时，要同时展示两种方案：无需修改代码的映射方案，以及可以启用
WithReference
、健康检查、服务发现、动态端口或仪表盘遥测的少量修改方案。询问用户想要哪种方式，然后毫无怨言地实现用户的选择。

Verify APIs before writing AppHost code

编写AppHost代码前先验证API

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.
使用
aspire docs search <topic>
和
aspire docs get <slug>
获取工作流指导。使用
aspire docs api search <query> --language csharp\|typescript
和
aspire docs api get <id>
查看API结构。在使用
aspire add
之前，使用
aspire integration list/search
查找可用集成。不要虚构包、方法、重载或命令格式；C#和TypeScript的AppHost API存在差异。

Keep configuration visible in the AppHost

保持配置在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.
扫描
.env
、
.env.local
、
.env.development
、
secrets.json.example
、
<UserSecretsId>
和设置脚本。建议将配置值迁移到AppHost参数中：连接字符串转为Aspire资源，API密钥/令牌转为密钥参数，非涉密配置转为普通参数或
WithEnvironment()
值。未经用户明确批准，切勿删除
.env
文件或移除现有的
UserSecretsId
条目，因为非Aspire工作流可能仍依赖这些配置。

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.
本技能针对本地开发优化，而非生产部署。优先为数据库/缓存使用持久化容器生命周期和数据卷，默认使用HTTPS端点，传递端点引用而非硬编码URL，将外部SaaS URL/API密钥建模为参数，以便在仪表盘中可见。

Redis TLS edge case

Redis TLS特殊情况

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.
Aspire可以自动为容器资源提供TLS证书。如果Redis健康检查因SSL/TLS握手错误失败，不要退而使用
AddContainer()
。当消费应用期望使用普通Redis连接时，在Redis资源上使用
WithoutHttpsCertificate()
。

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.
如果存在
.agents/skills/aspireify/SKILL.md
文件（由
aspire init
或
aspire agent init --skills aspireify
安装），警告用户存在项目本地副本，并优先使用该副本。插件版本作为后备方案。
⚠️ Project-local .agents/skills/aspireify/SKILL.md detected — deferring to it.

Prerequisites

前置要求

RequirementInstall
.NET 10.0 SDK (C# AppHost)https://dotnet.microsoft.com/download
Node.js 
^20.19.0
, 
^22.13.0
, or 
>=24
(TS AppHost)		https://nodejs.org
Aspire CLI
npm install -g @microsoft/aspire-cli
, install script, or 
dotnet tool install -g Aspire.Cli
Skeleton already dropped
aspire init
produced 
aspire.config.json
+ AppHost stub
要求安装方式
.NET 10.0 SDK（C# AppHost）https://dotnet.microsoft.com/download
Node.js 
^20.19.0
、
^22.13.0
或
>=24
（TS AppHost）		https://nodejs.org
Aspire CLI
npm install -g @microsoft/aspire-cli
、安装脚本，或
dotnet tool install -g Aspire.Cli
已生成骨架
aspire init
已生成
aspire.config.json
+ AppHost存根

Detection — When to Activate

触发条件 — 何时激活

Activate when ANY signal is present AND the AppHost is unwired (no resources declared beyond the stub):
SignalHow to DetectConfidence
Skeleton just dropped
aspire init
just ran in this session		✅ Definitive
Empty AppHost stub
apphost.cs
/ 
Program.cs
/ current 
apphost.mts
(or legacy 
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 AppHostRepo 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
.
当存在以下任意信号且AppHost尚未搭建（除存根外没有声明任何资源）时激活：
信号检测方式置信度
刚生成骨架本次会话中刚运行过
aspire init
✅ 确定
空的AppHost存根
apphost.cs
/ 
Program.cs
/ 当前版本
apphost.mts
（或旧版
apphost.ts
）仅包含
Build().Run()
✅ 确定
aspire.config.json
无资源配置		配置文件存在，但AppHost中没有
AddProject
/
addProject
高
用户要求“搭建”/“脚手架生成资源图”动词匹配：搭建、脚手架生成、集成、连接、添加Postgres/Redis等高
用户询问“aspire init之后下一步做什么”直接的交接请求✅ 确定
现有仓库包含服务 + 新的AppHost仓库中有
.csproj
/
package.json
项目，但AppHost未引用任何项目		高
如果AppHost已经搭建好资源，而用户想要启动/停止应用 → 转交
aspire-orchestration
技能。如果用户想要部署 → 转交
aspire-deployment
技能。

Language Support

语言支持

AppHost StyleDetectionEdit 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
TypeScriptCurrent 
apphost.mts
or legacy 
apphost.ts
with generated 
.aspire/modules/
Configured AppHost entry point only — never edit 
.aspire/modules/
See references/csharp-authoring.md and references/typescript-authoring.md.
aspire-orchestration
owns the CLI-driven migration from legacy 
apphost.ts
. After it updates packages and migration artifacts, return to aspireify only when the user still needs AppHost source wiring or authoring.
AppHost类型检测方式编辑目标
C# SDK风格
.csproj
中包含
<Sdk Name="Aspire.AppHost.Sdk" />
Program.cs
（顶级语句）
基于文件的C#
apphost.cs
中包含
#:sdk Aspire.AppHost.Sdk
和
#:package
指令
apphost.cs
本身
TypeScript当前版本
apphost.mts
或旧版
apphost.ts
，带有生成的
.aspire/modules/
目录		仅编辑配置的AppHost入口文件 — 绝不编辑
.aspire/modules/
参见references/csharp-authoring.md和references/typescript-authoring.md。
aspire-orchestration
负责从旧版
apphost.ts
进行CLI驱动的迁移。在它更新包和迁移产物后，仅当用户仍需要AppHost源码搭建或编写时，才回到aspireify处理。

TypeScript AppHost package managers

TypeScript AppHost包管理器

Dependency and toolchain failures belong to this skill. Before recommending a command, inspect the AppHost directory and then its immediate eligible parent. Within each directory, the first recognized marker wins in this order:
  1. packageManager
    in 
    package.json
    (
    npm
    , 
    pnpm
    , 
    yarn
    , or 
    bun
    , optionally versioned)
  2. bun.lock
  3. bun.lockb
  4. pnpm-lock.yaml
  5. yarn.lock
  6. .yarnrc.yml
  7. package-lock.json
An AppHost-local marker takes precedence over every parent marker. If neither directory has a recognized marker, Aspire defaults to npm. Report the selected manager and marker.
Use the selected manager only to repair dependencies or diagnose the toolchain. The resolver commands are 
npm install
, 
bun install
, and 
yarn install
; a generated brownfield pnpm AppHost uses 
pnpm install --ignore-workspace
, while other pnpm dependency installs use 
pnpm install
. Yarn Classic (
yarn@1...
or a v1 lockfile) is unsupported: stop and ask the user to upgrade to Yarn 4+ or explicitly migrate to npm, pnpm, or Bun.
Do not change 
packageManager
or create, replace, or regenerate a lockfile merely to influence detection or switch managers. Preserve existing files until the user explicitly chooses an upgrade or migration. Start the AppHost with 
aspire start --non-interactive
, not a raw package-manager launcher. See references/typescript-authoring.md for the full command matrix and resolver details.
依赖和工具链故障属于本技能的处理范围。在推荐命令之前，先检查AppHost目录，再检查其直接上级目录。在每个目录中，按以下顺序匹配，第一个识别到的标记生效：
  1. package.json
    中的
    packageManager
    字段（
    npm
    、
    pnpm
    、
    yarn
    或
    bun
    ，可带版本号）
  2. bun.lock
  3. bun.lockb
  4. pnpm-lock.yaml
  5. yarn.lock
  6. .yarnrc.yml
  7. package-lock.json
AppHost本地目录的标记优先级高于所有上级目录的标记。如果两个目录都没有识别到的标记，Aspire默认使用npm。需告知用户所选的包管理器和匹配的标记。
仅在修复依赖或诊断工具链问题时使用选定的包管理器。依赖解析命令为
npm install
、
bun install
和
yarn install
；生成的存量项目pnpm AppHost使用
pnpm install --ignore-workspace
，其他pnpm依赖安装使用
pnpm install
。不支持Yarn Classic（
yarn@1...
或v1版本的锁文件）：需停止操作并要求用户升级到Yarn 4+，或明确迁移到npm、pnpm或Bun。
不要为了影响检测结果或切换包管理器而修改
packageManager
字段，也不要创建、替换或重新生成锁文件。在用户明确选择升级或迁移之前，保留现有文件。使用
aspire start --non-interactive
启动AppHost，而非直接使用包管理器的启动命令。完整的命令矩阵和解析器详情参见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     → 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
如需详细的、与上游一致的工作流，请在编辑前查阅以下参考资料：
  • apphost-wiring.md — 完整的AppHost搭建工作流、API查询、端点/参数模式、验证、解决方案更新和清理。
  • docker-compose.md — Docker Compose迁移、配置文件、镜像映射、端口、卷和
    depends_on
    。
  • full-solution-apphosts.md — 大型解决方案分类、混合SDK边界、解决方案成员关系、ServiceDefaults放置和旧版宿主迁移。
  • javascript-apps.md — JavaScript资源选择、工作区/ monorepo包管理器处理、端口、脚本和TS AppHost包配置。
  • opentelemetry.md — 非.NET服务的可选Node.js、Python和Go OpenTelemetry配置。

1. Scan

1. 扫描

Walk the repo and inventory:
WhatHow
.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 stringsgrep 
appsettings*.json
, 
.env*
, 
config/*
for 
Postgres
, 
Redis
, 
Mongo
, 
RabbitMQ
, 
Cosmos
, 
ServiceBus
Integration packages
dotnet list package
per project; package.json 
dependencies
Existing endpointshardcoded ports in 
launchSettings.json
, 
next.config.js
, 
vite.config.ts
Full heuristics in references/scan-and-propose.md.
遍历仓库并盘点以下内容：
内容方式
.NET项目
find . -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*'
Node服务
find . -name 'package.json' -not -path '*/node_modules/*'
Python服务
find . -name 'pyproject.toml' -o -name 'requirements.txt'
Compose中的容器依赖
docker-compose.yml
、
compose.yaml
（Postgres？Redis？Rabbit？）
连接字符串在
appsettings*.json
、
.env*
、
config/*
中grep
Postgres
、
Redis
、
Mongo
、
RabbitMQ
、
Cosmos
、
ServiceBus
集成包每个项目执行
dotnet list package
；查看package.json的
dependencies
现有端点
launchSettings.json
、
next.config.js
、
vite.config.ts
中的硬编码端口
完整的启发式规则参见references/scan-and-propose.md。

2. Propose

2. 提出方案

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?"
在编辑之前先展示资源图。询问澄清问题：
  • “我在
    docker-compose.yml
    中发现了Postgres — 我应该将其建模为
    AddPostgres('db')
    还是使用Azure Database for PostgreSQL？”
  • “你的React应用硬编码了
    http://localhost:5000
    — 是否替换为Aspire服务发现（
    endpoint.url
    ）？”
  • “你的API有一个
    /admin
    端点 — 是否将其从
    WithReference()
    中排除，这样消费方就看不到它了？”

3. Edit

3. 编辑

Apply the proposed graph. Use the right authoring style for the AppHost language.
应用提出的资源图。根据AppHost的语言使用正确的编写风格。

4. Validate

4. 验证

bash
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.
bash
aspire start --non-interactive --format Json
aspire wait <resource>          # repeat for each declared resource
aspire describe --format Json   # sanity check graph
完整的验证流程和故障恢复参见references/validation.md。

5. Self-Deactivate

5. 自动停用

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.
在
aspire start
成功运行后，告知用户：
✅ 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.
DetectedC#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')
将检测到的服务映射到Aspire集成。完整目录参见references/scan-and-propose.md。
检测到的内容C#TS
Compose中的Postgres / 
Npgsql
包
AddPostgres("pg").AddDatabase("db")
addPostgres('pg').addDatabase('db')
Compose中的Redis / 
StackExchange.Redis
AddRedis("cache")
addRedis('cache')
RabbitMQ
AddRabbitMQ("mq")
（v7客户端，带发布订阅追踪）
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")
（现已正式发布）
addAzureRedis('cache')
Next.js前端
AddNextJsApp("web", "./web")
addNextJsApp('web', '../web')
Vite SPA
AddViteApp("web", "./web")
addViteApp('web', '../web')
普通Node应用
AddNodeApp("api", "server.js")
addNodeApp('api', 'server.js')

Current Authoring Rules

当前编写规则

RuleWhy
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 the configured 
apphost.mts
(or legacy 
apphost.ts
) only
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
Use context 
.Services
/ 
await ctx.services().getInteractionService()
.ServiceProvider
is obsolete, and 
ctx.services()
alone returns a services accessor
Use 
AddConnectionString
for external connection strings
PublishAsConnectionString
is obsolete
Check 
IInteractionService.IsAvailable
before prompting		CLI-invoked commands may be noninteractive; prefer command arguments for dashboard + CLI input
Treat 
WithTerminal()
as experimental		Suppress 
ASPIRETERMINAL001
; do not generate removed 
TerminalOptions.Shell
or TypeScript dimension options
Keep all Aspire SDK and 
Aspire.Hosting.*
packages on the same release family		Mixed release families can fail at startup
Migrate GitHub Models integrations to Azure AI Foundry
Aspire.Hosting.GitHub.Models
is deprecated and absent from integration discovery
Use 
WithModule(RedisModules.*)
for Redis 8 modules		Prefer typed JSON, Search, Bloom Filter, and TimeSeries constants over raw module paths
Use Foundry 
AsHostedAgent(...)
for hosted executable/container agents		Current Azure AI Foundry path replaces deprecated GitHub Models
规则原因
在TS中使用统一的
withEnvironment(name, value)
 — 不要使用已弃用的按类型辅助方法（
withEnvironmentEndpoint
、
withEnvironmentParameter
等）		单一API可处理所有值类型；按类型的辅助方法已弃用
JS前端优先使用
AddNextJsApp
/ 
AddViteApp
，而非手写Dockerfile		提供一流的生命周期管理 + 
PublishAs*
集成
JS发布使用
PublishAsStaticWebsite
/ 
PublishAsNodeServer
/ 
PublishAsPackageScript
替代手写Dockerfile；SPA → 静态站点，SSR Node → NodeServer，包脚本SSR → PackageScript
为前端资源添加
WithBrowserLogs()
，以便在仪表盘中查看浏览器控制台日志和截图
Aspire.Hosting.Browsers
在仪表盘中展示浏览器遥测数据
存在多个环境时，使用
WithComputeEnvironment(env)
将每个资源绑定到计算环境		多环境部署需要显式绑定
在TS AppHost中绝不编辑
.aspire/modules/
该目录是自动生成的；编辑会被覆盖。仅编辑配置的
apphost.mts
（或旧版
apphost.ts
）
使用
WithEndpoint("name", e => ...)
更新端点		端点回调会更新现有端点，而非因重复而抛出错误
使用
ExcludeReferenceEndpoint = true
标记管理端点		防止消费方通过
WithReference()
获取管理端URL
不熟悉的API先查询：
aspire docs api search <query> --language csharp|typescript
不要猜测重载或构建器链
使用上下文的
.Services
/ 
await ctx.services().getInteractionService()
.ServiceProvider
已过时，仅调用
ctx.services()
会返回服务访问器
外部连接字符串使用
AddConnectionString
PublishAsConnectionString
已过时
提示用户前先检查
IInteractionService.IsAvailable
CLI调用的命令可能是非交互式的；优先使用命令参数来支持仪表盘和CLI输入
将
WithTerminal()
视为实验性功能		抑制
ASPIRETERMINAL001
警告；不要生成已移除的
TerminalOptions.Shell
或TypeScript维度选项
所有Aspire SDK和
Aspire.Hosting.*
包保持在同一发布系列		混合发布系列可能导致启动失败
将GitHub Models集成迁移到Azure AI Foundry
Aspire.Hosting.GitHub.Models
已弃用，且不在集成发现范围内
Redis 8模块使用
WithModule(RedisModules.*)
优先使用类型化的JSON、Search、Bloom Filter和TimeSeries常量，而非原始模块路径
托管的可执行/容器代理使用Foundry的
AsHostedAgent(...)
当前Azure AI Foundry路径替代了已弃用的GitHub Models

C# vs TS Quick Reference

C#与TS快速参考

ConceptC#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();
概念C#TypeScript
构建器
var builder = DistributedApplication.CreateBuilder(args);
const builder = await createBuilder();
添加项目
builder.AddProject<Projects.Api>("api")
（SDK风格）或
AddProject("api", "../Api/Api.csproj")
await builder.addProject('api', '../Api/Api.csproj')
配置环境变量（任意值类型）
.WithEnvironment("KEY", value)
.withEnvironment('KEY', value)
← 统一API
等待依赖就绪
.WaitFor(db)
.waitFor(db)
传递连接引用
.WithReference(db)
.withReference(db)
外部HTTP端点
.WithExternalHttpEndpoints()
.withExternalHttpEndpoints()
端点表达式
api.GetEndpoint("http")
api.getEndpoint('http').url
/ 
.host
/ 
.port
构建并运行
builder.Build().Run();
await builder.build().run();

ServiceDefaults Wiring

ServiceDefaults配置

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.
每个项目都应调用
builder.AddServiceDefaults();
以启用OpenTelemetry、健康检查和服务发现。添加
Aspire.ServiceDefaults
项目引用（非monorepo项目使用NuGet包）。参见references/service-defaults.md。

Endpoint & Reference Conventions

端点与引用约定

csharp
// 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
csharp
// 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

验证与故障恢复

SymptomAction
aspire start
fails with build error		Fix code, re-run 
aspire start
File-lock errors during editHand off to 
aspire-orchestration
→ 
aspire stop
→ retry
Resource missing from 
aspire describe
Re-run 
aspire describe --include-hidden
; 
aspire ps
is AppHost-level
TS AppHost change ignoredConfirm you edited the configured 
apphost.mts
(or legacy 
apphost.ts
), not 
.aspire/modules/
Mixed JSON output from 
aspire start
Strip non-JSON lines before parsing (#15843)
Full flow in references/validation.md.
症状处理方式
aspire start
因构建错误失败		修复代码，重新运行
aspire start
编辑过程中出现文件锁定错误转交
aspire-orchestration
→ 执行
aspire stop
→ 重试
aspire describe
中缺少资源		重新运行
aspire describe --include-hidden
；
aspire ps
是AppHost级别的命令
TS AppHost的修改未生效确认你编辑的是配置的
apphost.mts
（或旧版
apphost.ts
），而非
.aspire/modules/
aspire start
的JSON输出混杂其他内容		解析前先剥离非JSON行（#15843）
完整流程参见references/validation.md。

Handoff Rules

交接规则

ScenarioRoute 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)
场景转交至
AppHost骨架尚未生成→ 
aspire-init
技能
日常启动/停止/等待/重启→ 
aspire-orchestration
技能
发布、部署、销毁、流水线步骤→ 
aspire-deployment
技能
日志、链路追踪、指标、仪表盘、浏览器日志检查→ 
aspire-monitoring
技能
已部署（Azure/AKS）应用的诊断→ 
azure-diagnostics
技能（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.
  • 绝不覆盖现有文件 — 始终采用增量或合并的方式。
  • 修改服务代码前先询问，尤其是OpenTelemetry和ServiceDefaults注入。
  • 尊重现有项目结构 — 不要重构仓库。
  • **如果遇到问题，使用
    aspire doctor
    **诊断环境问题。
  • 不要在
    WithEnvironment
    / 
    withEnvironment
    中硬编码URL     — 传递端点引用，例如
    api.GetEndpoint("http")
    或
    api.getEndpoint('http')
    ，而非字符串字面量。
  • 不要使用
    WithUrlForEndpoint
    / 
    withUrlForEndpoint
    设置
    dev.localhost
    URL     — 该API仅用于仪表盘显示标签；
    dev.localhost
    应在AppHost启动/配置文件中设置。

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
  • aspire-13-5-breaking-changes.md — Breaking changes introduced in 13.5 and fixes for affected releases
  • apphost-wiring.md — 详细的AppHost搭建工作流和API查询模式
  • docker-compose.md — Docker Compose迁移模式
  • full-solution-apphosts.md — 大型/完整解决方案AppHost指南
  • javascript-apps.md — JavaScript/TypeScript应用和工作区处理
  • opentelemetry.md — 非.NET OpenTelemetry设置
  • scan-and-propose.md — 仓库扫描启发式规则 + 集成目录
  • csharp-authoring.md — C# AppHost模式
  • typescript-authoring.md — TS AppHost模式 + 等效API
  • service-defaults.md — 配置OTel、健康检查、服务发现
  • validation.md — 端到端验证 + 故障恢复
  • aspire-13-5-breaking-changes.md — 13.5版本引入的破坏性变更及受影响版本的修复方法