aspire-project-v2-migration

Aspire Project v2 迁移

将受支持的旧版 .NET 项目资源迁移到实验性的 DotnetProjectResource 模型，同时不悄然改变应用程序行为。 此技能首先适用于以 Aspire 13.6 或更高版本为目标的 AppHost。

审批边界：“迁移到 Project v2”之类的请求仅授权进行评估，并不代表可以直接编辑。请先提交逐资源、逐文件的确切计划， 然后在更改 AppHost、程序包、项目引用或应用程序文件之前取得批准。只执行明确获批的部分。

硬性门槛

1. 确认一个确切的 AppHost，并保留无关的本地更改。
2. 根据项目文件、集中式程序包管理、文件指令或已解析的多语言配置，确定 AppHost 实际使用的 Aspire SDK/hosting 版本。
3. 如果版本低于 13.6、无法确定或存在冲突，则停止，不做任何编辑。 不要根据 Aspire CLI 版本、.NET SDK 或服务的 TargetFramework 推断是否符合条件，也不要隐式升级 Aspire。
4. 验证已安装/已解析的程序包提供所有必要 API，包括应用所用的 AddDotnetProject、发布、EF 和 Blazor 功能。 开发版程序包只能作为开发构建的依据，不能作为已发布程序包的依据。
5. 切勿手动编辑生成的 .aspire/modules/ 文件。
6. 在依赖不熟悉或预览版 API 的形态之前，使用 aspire docs search 和 aspire docs api search ... --language csharp|typescript。
7. 对于 TypeScript，必须确认已解析的生成 API 为 addDotnetProject(name, path, options?: DotnetProjectOptions)，且使用扁平 DTO。仅支持旧版句柄式目标的构建应视为能力门槛，不是另一条受支持的迁移路径。 旧版源代码中的 ProjectResourceOptions 值仍是 RPC 句柄。

发布和 TypeScript 选项更改已在上游合并，但仅有 13.6 版本标签并不能证明使用者的程序包包含这些更改。 有关已合并 API 基线和发布边界，请参阅 compatibility-and-validation.md。

项目本地技能覆盖

如果存在 .agents/skills/aspire-project-v2-migration/SKILL.md，请警告用户，并遵循该项目本地技能，同时保留这些安全门槛。

工作流

1. 清点实际行为

在应用工作区中只进行只读评估。检查源代码和已解析的元数据；在获得批准前，不要还原、生成、运行或重新生成 SDK 文件，即使是为了发现功能也不行。如果需要准备工作来验证资格或 API，请说明这一前置要求并请求批准，而不是悄悄修改工作区。

检查所选的 AppHost 和每个旧版候选项：

• AddProject<Projects.T>、路径/目录形式的 AddProject、AddCSharpApp 及其多语言等效项。
• 文档中说明的 Blazor 网关模式和附加的 EF 操作。
• 名称、路径、选项、应用程序参数、环境回调、端点、启动设置、引用、等待项、运行状况检查、副本、生成/发布配置和部署注释。
• AppHost ProjectReference / 基于文件的 #:project 边，以及所有使用生成的项目元数据的使用方。通过实际的 IProjectMetadata、项目引用元数据和 AspireProjectMetadataTypeName 解析 Projects.*；切勿根据类型名称猜测路径。
• 与 ProjectResource 耦合的自定义代码，包括强制转换、约束、GetProjectResources()、发布器、映像管理器、直接构造函数或专用子类。
• SDK 选择、自定义生成属性、仅用于生成的要求、文件应用的 AOT 设置，以及现有的本地更改。
• 对于 Blazor 网关发布，检查生效的前后目标框架、SDK、运行时/基础映像和操作系统/平台、进程用户、工作目录、入口点和端口配置。AppHost 的目标框架不能确定已打包网关文件应用的发布框架。

已迁移的应用或不包含匹配资源的应用无需操作。

2. 分类并提出方案

编辑前先提供一张表：

资源	当前 API 和来源	拟议替代方案	保留的行为／有意变更	包和引用编辑	分类
api	AddProject<Projects.Api> → 已解析路径	AddDotnetProject("api", path)	参数、配置文件、终结点、环境变量、引用、等待、副本数、发布	添加 Aspire.Hosting.Dotnet；仅移除已确认仅供该资源使用的依赖	支持／需决策／不支持

请说明：

• ASPIREDOTNETPROJECT001 是实验性 API 诊断。
• 项目 v2 资源以可执行文件作为标识，并协调初始构建。
• 已知的发布或验证差异，尤其是 Blazor 网关发布、EF 自定义构建输入，以及跨操作系统的文件应用 Native AOT。
• 具体哪些文件和哪些资源子集会发生变更，以及哪些旧资源会保留。

请用户批准这份确切方案。在用户明确批准子集及保留的资源之前，不要先迁移看似“安全”的子集。

对于 Blazor 网关，仅批准替换 API 或将 “Dockerfile to SDK” 切换本身，并不代表批准隐式变更框架、基础映像或进程用户。编辑前，请列出已解析的部署差异，并就这些差异取得明确批准。简要说明运行时／操作系统兼容性，以及非 root 用户带来的文件／卷权限影响；仅列出变更值不构成知情批准。如果无法通过只读方式确定这些值，则将网关归类为需决策，并请求批准进行解决问题所需的准备工作。不要臆造默认值，也不要假设部署等效。

结束该评估时，必须就网关作出明确决策：请求批准进行范围明确的调查，或询问是否保留网关并审查由项目自行维护的发布策略。只询问是否批准 API 编辑，无法解决网关的审批边界问题。

提交包含尚未解决的网关问题的评估前，请检查最后的问题：必须明确请用户在网关范围明确的调查与保留网关并审查自有发布策略之间作出选择。若网关仍需决策，绝不能只以请求批准 API 编辑作为结尾。

评估结尾必须实际请求批准，而不能只描述批准意味着什么。若有可用的宿主用户提问工具，请使用该工具；否则，明确询问用户是否批准所列的资源和文件变更。必须等待答复后再编辑。用户无法联系不代表已获批准。

获批后，如果验证已获授权且可行，请在临时副本中记录旧行为。迁移前后使用相同且符合要求的工具链；报告已有失败，不要将其归因于迁移。

3. 应用已批准的映射

加载 migration-patterns.md，并严格遵循其中针对具体语言的映射。

• 添加 Aspire.Hosting.Dotnet，版本须与已指定目标的 AppHost 兼容，并保留集中式包管理和仓库约定。
• 对于 TypeScript，使用扁平的 DotnetProjectOptions 对象。保留旧版源代码中的既有值；不要重新设计 addProject、addCSharpApp 或共享的 ProjectResourceOptions 句柄。
• 在可用时，使用 Aspire CLI 的常规集成获取／重新生成流程；不要手动编辑生成的 SDK 模块。
• 保留流畅配置和应用程序参数原有的运行时用途。
• 仅更新与已批准资源相关的直接本地 IResourceBuilder<ProjectResource> 注解。不要大范围改写公共／自定义契约。
• C# 迁移必须以最小范围处理 ASPIREDOTNETPROJECT001，以确保编辑后的 AppHost 能编译。优先在已批准的 Project v2 声明两侧紧邻添加成对的 #pragma warning disable ASPIREDOTNETPROJECT001／#pragma warning restore ASPIREDOTNETPROJECT001。只有在仓库约定和已批准的迁移范围都允许同等精确的控制时，才使用项目级 NoWarn。绝不要抑制无关诊断，也不要留下无界的禁用。 为 IDotnetProgramResource 选择的 AddEFMigrations 重载也要求在该 EF 声明两侧添加成对的 ASPIREPROJECTS001 抑制；旧版重载没有此要求。将此编译所必需的编辑纳入批准范围。 如果客户端／网关调用需要，保留现有的 ASPIREBLAZOR001 范围。

4. 谨慎清理项目引用

仅当能够证明 AppHost 的 ProjectReference 或 #:project 仅用于已批准迁移的资源，且不存在仍在使用的生成元数据使用方时，才将其删除。保留：

• 代码／库引用以及服务到库的引用；
• 未迁移资源、EF 迁移元数据、Blazor WASM 元数据、条件代码或其他 Projects.* 使用方所依赖的引用边；
• 意图不明确的引用，以及用途尚未确定的仅用于构建的引用边。

ReferenceOutputAssembly="false" 不会阻止 AppHost 引用参与构建，也不能替代安全清理。

5. 保留构建和运行时意图

将运行时 WithEnvironment 值保留在运行时。只有针对已确认且已批准的 MSBuild 输入，才添加 WithBuildEnvironment；绝不要整体迁移环境配置，也不要将运行时工作目录视为构建上下文。

对受支持的映像标识、目标位置、格式和目标平台设置，使用 WithContainerBuildOptions。不要将这些设置转换为被禁止的构建环境属性。

6. 验证并报告

批准的编辑完成后：

1. 按照仓库约定还原/构建。
2. 需要隔离时，使用 aspire start --non-interactive --isolated --apphost <path> 启动确切的 AppHost。
3. 使用 aspire wait <resource> --apphost <path> --non-interactive 和结构化的 Aspire 检查，而不是手动轮询。
4. 验证保留的名称、路径、参数、环境、终结点、引用、等待条件、副本、启动配置文件和发布意图。
5. 区分编译、本地运行、生成的发布构件和镜像构建的证据。aspire publish 不能证明镜像已构建。仅运行获准的验证阶段；不得将推送镜像或部署作为隐含检查。 不得声称未执行、已跳过或不可用的检查已通过。 对于获准的网关镜像更改，应分别验证确切的已接受目标契约和未更改的行为。报告有意为之的差异，而非宣称“镜像一致”；冒烟测试通过并不授权新增框架/用户更改。
6. 再次运行迁移评估以证明操作具有幂等性：不重复添加包、资源、抑制项或配置编辑。

报告已迁移、有意保留和受阻的资源，以及实际验证结果和需要手动跟进的事项。如果验证失败，保留用户的编辑。

兼容性边界

加载 compatibility-and-validation.md 以查看完整的决策矩阵。绝不要自动替换：

• Azure Functions 或未知的专用 ProjectResource 子类型；
• F# 或 Visual Basic 服务；
• 直接调用 new ProjectResource(...) 的代码；
• 未经用户决定的自定义发布器、镜像管理器、类型转换、泛型约束或 GetProjectResources() 使用方；
• 文件应用的仅构建环境或文件应用的 EF CLI 操作。

IDotnetProgramResource 是一个身份标记。它本身不会配置发布；SupportsDotnetProgramPublishing() 是一项功能检查，并非重写每个 ProjectResource 约束的理由。

对于每个基于文件的 .cs 候选项，评估必须明确说明：它需要 .NET 10+，不支持 WithBuildEnvironment 或 EF CLI 操作，保持运行时 WithEnvironment 值不变，并保留 Native AOT，除非用户另行批准 PublishAot=false 或选择面向目标 OS 的发布环境。

除非有明确证据并获得批准，否则不得禁用文件应用的 Native AOT、替换自定义发布模型，或承诺尚未完成的监视/热重载/部分运行行为。

路由

请求	路由
将旧版项目资源迁移到 Project v2	此技能
仅升级 Aspire 包或 CLI	aspire-orchestration
创建或连接 AppHost	aspire-init / aspireify
仅启动、停止、等待或重新构建	aspire-orchestration
迁移后部署或发布	aspire-deployment
诊断运行时行为	aspire-monitoring