SuperAPI AI 工具集

converting-to-cpm

编程与开发

查看项目

更新于 10-21 20:49

技能介绍

用途

该技能用于将 .NET 项目从按项目单独管理包版本的方式,迁移到 NuGet 中央包管理(CPM),把所有包版本集中到一个 Directory.Packages.props 文件中,形成单一版本来源。

适用场景

  • 用户希望为仓库、解决方案或项目采用 CPM。
  • 包版本分散在各个项目文件中,用户希望建立单一事实来源。
  • 用户提到 Directory.Packages.props、CPM 或集中管理 NuGet 版本。
  • 用户希望在多个项目之间对齐或同步某个包版本(若尚未启用 CPM,可建议采用)。
  • 各项目之间的包版本不同步或存在冲突。

不适用场景

  • 所有范围内项目已完全启用 CPM。
  • 项目使用 packages.config(必须先迁移到 PackageReference)。
  • 用户明确希望使用不带 CPM 的自定义 MSBuild 属性文件。

输入

  • 范围(必填):要转换的项目文件、解决方案文件或包含 .NET 项目的目录。
  • 版本冲突策略(可选):如何解决版本冲突。不要假设默认值——检测到冲突时应询问用户。

工作流程

  1. 确定范围:单个项目由用户指定项目文件;解决方案由用户指定 .sln/.slnx,并用 dotnet sln list 列出项目;仓库/目录则从第一个共同祖先目录递归查找所有项目文件。范围不明确时询问用户。
  2. 建立基线构建:验证范围可成功构建并捕获基线产物,完整流程见 baseline-comparison.md。若基线构建失败,停止并告知用户——转换前范围必须能干净构建。不要删除产物,后续转换后比较需要用到。
  3. 检查现有 CPM:在范围内或祖先目录中搜索 Directory.Packages.props。若 CPM 已完全启用,告知用户并停止。若文件存在但未启用 CPM,询问用户如何处理。
  4. 审计包引用:对所有范围内项目运行 dotnet package list --format json;扫描 <Import> 元素,查找包含包引用的共享 .props/.targets 文件。按 audit-complexities.md 检查复杂性:版本冲突、基于 MSBuild 属性的版本、条件引用、安全公告、现有 VersionOverride 用法。在继续之前向用户展示审计结果——包括包、版本、使用项目的表格,以及需要决策的冲突或复杂点。对于版本冲突,逐个展示解决选项与权衡。不要将任何包升级到超过当前已使用的最高版本——将公告记为后续事项。在继续前请用户对每个冲突做出决定。
  5. 创建或更新 Directory.Packages.props:使用 dotnet new packagesprops(.NET 8+)或手动创建。为每个唯一包添加 <PackageVersion> 条目。放置位置、条件版本和 VersionOverride 模式见 directory-packages-props.md。
  6. 更新项目文件:从每个有对应 <PackageVersion> 的 <PackageReference> 中移除 Version。同时更新第 4 步发现的共享 .props/.targets 文件。当项目需要与中央版本不同的版本时,经用户确认后使用 VersionOverride。不要重新格式化或重排未更改的行。
  7. 处理 MSBuild 版本属性:对于使用 MSBuild 属性作为版本的 PackageReference 项,决定是内联还是保留属性引用。决策流程、导入顺序要求和清理过程见 msbuild-property-handling.md。仅在第 8 步验证成功后清理内联属性。
  8. 还原与验证:运行干净的还原和构建,捕获转换后产物,流程见 baseline-comparison.md。若出现错误,参见 validation-and-errors.md 中的 NuGet 错误代码和多 TFM 指南。不要删除任何产物——baseline.binlog、after-cpm.binlog、baseline-packages.json、after-cpm-packages.json 是交付给用户的成果物。
  9. 转换后报告:在产物旁创建 convert-to-cpm.md 文件——不要用聊天内联输出替代。内容包括:转换概览(范围、项目数、集中化的包、跳过项);版本冲突解决及其对各项目的影响;基线与结果包比较表(见 baseline-comparison.md);风险评估(低/中/高,基于版本是否变化);后续事项清单(安全公告、已弃用包、VersionOverride 对齐机会)。

验证清单

  • 任何更改前基线构建成功。
  • Directory.Packages.props 中 ManagePackageVersionsCentrally 设置为 true。
  • 每个范围内的 PackageReference 没有 Version 属性或使用 VersionOverride。
  • 每个被引用的包都有对应的 PackageVersion 条目。
  • 从干净状态执行 dotnet restore 和 dotnet build 成功。
  • 包列表比较未显示意外的版本变化。
  • 没有遗留孤立的版本属性(除非有意保留)。