名称: update-dotnet-version 描述: 全面的单次 .NET 版本升级，包括 SDK、TFM、包和构建验证 参数提示: “[–version <版本>] [–check-only] [–force] [–skip-packages]” 允许工具: Bash、Read、Write、Edit、Glob、Grep、Task、AskUserQuestion、mcp__perplexity__search、mcp__perplexity__reason、mcp__microsoft-learn__microsoft_docs_search
/dotnet:update-dotnet-version
旗舰命令: 全面的 .NET 版本升级工具，处理 SDK 安装、TFM 更新、包兼容性和构建验证，支持自动错误解决。
参数
从 $ARGUMENTS 解析参数：
| 标志 | 描述 | 默认值 |
|---|---|---|
--version <版本> |
目标 .NET 版本（例如，10、10.0） | 最新稳定版 |
--check-only |
仅分析，不进行更改 | false |
--force |
跳过兼容性警告并继续 | false |
--skip-packages |
跳过包升级 | false |
--skip-build |
跳过构建验证 | false |
工作流概述
┌─────────────────────────────────────────────────────────────┐
│ /dotnet:update-dotnet-version │
├─────────────────────────────────────────────────────────────┤
│ 1. 预飞行分析 │
│ ├── 检测所有项目的当前 TFM │
│ ├── 检查包与目标的兼容性 │
│ └── 报告阻塞问题 │
├─────────────────────────────────────────────────────────────┤
│ 2. SDK 安装 │
│ ├── 检查目标 SDK 是否已安装 │
│ └── 如果需要，通过 /dotnet:install-sdk 安装 │
├─────────────────────────────────────────────────────────────┤
│ 3. 更新 global.json │
│ └── 设置 SDK 版本和 rollForward 策略 │
├─────────────────────────────────────────────────────────────┤
│ 4. 更新目标框架 │
│ ├── 更新所有 .csproj 中的 <TargetFramework> │
│ ├── 如果需要，更新 <LangVersion> │
│ └── 如果集中化，更新 Directory.Build.props │
├─────────────────────────────────────────────────────────────┤
│ 5. 升级包 │
│ └── 运行 /dotnet:upgrade-nuget-packages --major --auto │
├─────────────────────────────────────────────────────────────┤
│ 6. 构建与修复循环 │
│ ├── 运行 dotnet build │
│ ├── 如果错误：生成构建修复代理 │
│ └── 最多重试 5 次 │
├─────────────────────────────────────────────────────────────┤
│ 7. 验证 │
│ ├── 如果可用，运行测试 │
│ └── 报告最终状态 │
└─────────────────────────────────────────────────────────────┘
详细工作流
阶段 1: 预飞行分析
1.1 检测当前状态:
# 查找所有项目文件
find . -name "*.csproj" -type f
# 提取当前 TFM
grep -h "<TargetFramework" **/*.csproj | sort -u
解析并报告：
当前 .NET 版本分析
找到项目：12
当前 TFM：net9.0（10 个项目）、net8.0（2 个项目）
目标 TFM：net10.0
检测到混合 TFM：2 个项目在 net8.0
- src/Legacy/Legacy.csproj
- tests/Legacy.Tests/Legacy.Tests.csproj
1.2 包兼容性检查:
对于每个唯一包，检查 .NET 10 支持：
使用 mcp__perplexity__search：
查询："<包名称> .NET 10 支持 兼容性 2026 年 1 月"
报告发现：
包兼容性分析
兼容（已确认）：
- Microsoft.Extensions.*（10.0.0 可用）
- Serilog（4.0.0 支持 net10.0）
- xunit（2.9.0 支持 net10.0）
需要升级：
- Newtonsoft.Json 12.0.0 -> 13.0.3（支持 net10.0）
- AutoMapper 11.0.0 -> 13.0.0（支持 net10.0）
潜在阻塞：
- OldLibrary 2.0.0 - 未找到 .NET 10 支持
选项：查找替代方案、等待更新或移除依赖
未知（需手动验证）：
- CustomInternalLib 1.0.0
1.3 破坏性变更研究:
使用 mcp__microsoft-learn__microsoft_docs_search：
查询：".NET 10 破坏性变更 从 .NET 9 迁移"
使用 mcp__perplexity__reason：
查询：".NET 9 到 .NET 10 迁移 破坏性变更 C# 14 需要注意"
报告相关破坏性变更：
需要注意的破坏性变更
.NET 10 破坏性变更：
- System.Text.Json：新源生成器要求
- ASP.NET Core：最小 API 变更
- EF Core：查询行为变更
C# 14 新功能可用：
- 属性中的 field 关键字
- 集合表达式改进
- 扩展类型（预览）
1.4 决策点:
如果 --check-only：
- 报告分析并退出
如果找到阻塞问题且非 --force：
找到阻塞问题 - 无法继续
1. OldLibrary 2.0.0 无 .NET 10 支持
选项：
1. 先移除 OldLibrary 依赖
2. 使用 --force 继续（可能失败）
3. 取消并手动解决
[使用 AskUserQuestion 提供选项]
阶段 2: SDK 安装
检查目标 SDK 是否安装：
dotnet --list-sdks | grep "^10\."
如果未安装：
未找到 .NET 10 SDK。正在安装...
[调用 /dotnet:install-sdk --version 10.0 --update-global-json]
阶段 3: 更新 global.json
创建或更新 global.json：
{
"sdk": {
"version": "10.0.100",
"rollForward": "latestPatch"
}
}
阶段 4: 更新目标框架
4.1 检查集中化 TFM：
查找 Directory.Build.props：
<TargetFramework>net9.0</TargetFramework>
如果找到，仅更新 Directory.Build.props。
4.2 更新单个项目：
对于每个 .csproj 文件：
<!-- 之前 -->
<TargetFramework>net9.0</TargetFramework>
<!-- 之后 -->
<TargetFramework>net10.0</TargetFramework>
4.3 如果显式设置，更新 LangVersion：
<!-- 如果 LangVersion 显式设置 -->
<LangVersion>13.0</LangVersion>
<!-- 更新为 -->
<LangVersion>14.0</LangVersion>
<!-- 或移除以使用 SDK 默认 -->
4.4 处理多目标：
<!-- 之前 -->
<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
<!-- 之后 -->
<TargetFrameworks>net9.0;net10.0</TargetFrameworks>
阶段 5: 升级包
除非 --skip-packages：
升级包以支持 .NET 10 兼容性...
[调用内部包升级逻辑]
重点关注：
- Microsoft.* 包（与 .NET 版本对齐）
- 已知有 .NET 10 版本的包
- 有安全漏洞的包
阶段 6: 构建与修复循环
6.1 初始构建：
dotnet build --verbosity minimal
6.2 如果错误，生成构建修复代理：
构建失败，有 12 个错误。尝试自动修复...
[任务：dotnet:build-fixer 带错误上下文]
6.3 重试循环：
修复尝试 1/5：
- 修复了 8 个错误
- 剩余 4 个错误
修复尝试 2/5：
- 修复了 3 个错误
- 剩余 1 个错误
修复尝试 3/5：
- 修复了 1 个错误
- 构建成功！
6.4 达到最大尝试次数：
经过 5 次修复尝试后，构建仍失败。
剩余错误：
CS0012：类型 'OldType' 在未引用的程序集中定义
这些错误需要手动干预：
1. OldLibrary 使用 .NET 10 中不可用的类型
2. 考虑移除或替换 OldLibrary
部分升级完成。需要手动修复。
阶段 7: 验证
7.1 运行测试（如果可用）：
dotnet test --no-build
7.2 报告最终状态：
输出格式
仅检查模式：
.NET 版本升级分析（--check-only）
当前：net9.0
目标：net10.0
项目：12
包兼容性：
兼容：45 个包
需要升级：8 个包
阻塞：1 个包（OldLibrary）
破坏性变更：找到 3 个相关变更
- System.Text.Json 源生成器变更
- ASP.NET Core 最小 API 更新
- EF Core 查询翻译变更
建议：在升级前解决 OldLibrary 依赖问题。
运行不带 --check-only 以继续升级。
成功升级：
.NET 版本升级完成
升级：net9.0 -> net10.0
修改项目：12
SDK：10.0.100
所做更改：
- global.json：创建了 SDK 10.0.100
- Directory.Build.props：更新了 TFM 为 net10.0
- 12 个 .csproj 文件：更新了 TFM
- 8 个包升级为 .NET 10 兼容版本
构建：成功（经过 2 次修复迭代）
测试：142 通过，0 失败
应用的修复：
- 添加了 System.Text.Json 源生成器属性（3 个文件）
- 更新了弃用的 API 调用（5 个文件）
升级完成！您的项目现在目标为 .NET 10。
部分升级：
.NET 版本升级部分完成
目标：net10.0
修改项目：12
所做更改：
- 更新了 TFM 为 net10.0
- 6 个包升级
构建状态：失败（经过 5 次修复尝试）
剩余问题：
1. OldLibrary.OldType 不可用（3 个错误）
- src/MyApp/Services/LegacyService.cs:42
- src/MyApp/Services/LegacyService.cs:78
- src/MyApp/Models/LegacyModel.cs:15
需要手动操作：
替换或移除 OldLibrary 依赖。
然后运行：dotnet build
回滚命令（如果需要）：
git checkout -- .
dotnet restore
示例
# 仅分析升级而不做更改
/dotnet:update-dotnet-version --check-only
# 升级到最新稳定 .NET
/dotnet:update-dotnet-version
# 升级到特定版本
/dotnet:update-dotnet-version --version 10.0
# 强制升级，忽略警告
/dotnet:update-dotnet-version --force
# 仅升级 TFM，跳过包
/dotnet:update-dotnet-version --skip-packages
回滚
如果升级失败或导致问题：
# 恢复所有更改
git checkout -- .
# 恢复原始包
dotnet restore
# 验证原始状态构建
dotnet build
相关命令
/dotnet:install-sdk- 仅安装 SDK/dotnet:upgrade-nuget-packages- 仅升级包/dotnet:build --fix- 构建并自动修复/dotnet:solution-health- 分析项目健康状态