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