dotnet/skills xUnit v2升v3清单：12个关键变更点一次看懂
【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills
📦skills17/skills仓库（.NET 团队官方维护的 AI 编码智能体技能库）提供了一个开箱即用的dotnet-test-migration插件，其中migrate-xunit-to-xunit-v3技能可自动完成xUnit.net v2 → v3 升级：更新包引用、修复破坏性变更、保证所有测试按迁移前结果通过。下面把官方迁移清单拆解为12 个关键变更点，帮你一次看懂 v3 到底改了什么。
🚀 先确认：你的项目能升吗？
v3 对运行框架有硬性要求，升级前先核对：
- ✅.NET 8 及以上，或.NET Framework 4.7.2 及以上
- ✅ 测试库项目支持 .NET Standard 2.0
- ✅ 项目为 SDK-style 格式
⛔ 如果目标框架低于上述版本，官方技能的策略是立即停止迁移并提示先升级目标框架——见 migrate-xunit-to-xunit-v3/SKILL.md 中的 Step 1 与 eval.yaml 里的 "detect-incompatible-target-framework" 评测用例。
📌提交策略：官方要求每个大步骤后提交一次代码，且把"项目文件改动"与"代码改动"分开提交，保证迁移可审查、可二分回滚。
📋 必做的 5 个基础变更点
1️⃣ 定位 xUnit v2 测试项目
全局搜索以下 7 个 v2 包名，注意不要只查.csproj——Directory.Build.props、Directory.Build.targets、Directory.Packages.props（中央包管理）里也可能声明版本：
| v2 包 | v3 对应 |
|---|---|
xunit | xunit.v3 |
xunit.abstractions | 直接删除 |
xunit.assert | xunit.v3.assert |
xunit.core | xunit.v3.core |
xunit.extensibility.core+xunit.extensibility.execution | 合并为xunit.v3.extensibility.core（二合一） |
xunit.runner.visualstudio | 升级到最新版 |
2️⃣ 测试项目改为可执行程序
v3 的测试项目会生成自带运行器的可执行文件，因此每个测试项目需设置<OutputType>Exe</OutputType>。技巧：如果测试项目命名统一（如*.Tests.csproj），可以集中写在Directory.Build.props里，避免逐项目修改。
3️⃣ 保持原有测试平台不变
| 迁移前 | 迁移后配置 |
|---|---|
| 使用 VSTest（常见情况） | Directory.Build.props加<IsTestingPlatformApplication>false</IsTestingPlatformApplication> |
使用YTest.MTP.XUnit2 | 删除该包，改为<UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> |
4️⃣ 删除using Xunit.Abstractions;
v2 中常见的这个 using 在 v3 中不再需要，搜索后整体移除即可。
5️⃣async void测试方法必须改造
v3不再支持async void测试方法（会直接编译失败），凡是用[Fact]/[Theory]标注的async void方法一律改为async Task。这是最容易踩的坑，也是评测中被反复验证的场景。
🔧 条件触发的 7 个进阶变更点
以下步骤只在你项目里出现对应代码模式时才需要处理：
6️⃣ 四个常用属性：字符串改typeof
CollectionBehaviorAttribute、TestCaseOrdererAttribute、TestCollectionOrdererAttribute、TestFrameworkAttribute的构造方式从两个字符串（类型全名 + 程序集名）改为传入System.Type，即：
// 旧写法 [assembly: CollectionBehavior("MyNamespace.MyCollectionFactory", "MyAssembly")] // 新写法 [assembly: CollectionBehavior(typeof(MyNamespace.MyCollectionFactory))]7️⃣ 自定义 Fact/Theory 特性要补"源码信息"
继承FactAttribute或TheoryAttribute的自定义特性，v3 要求构造函数提供[CallerFilePath]和[CallerLineNumber]参数并传给base(...)，否则编译器会报错。
8️⃣ 自定义 BeforeAfterTest 特性要改签名
继承BeforeAfterTestAttribute的特性类，Before/After方法签名多了一个IXunitTest参数，重写和base调用都要同步更新。
9️⃣ 处理新增的 xUnit 分析器警告
v3 引入了新的分析器规则，最典型的是xUnit1051：接收CancellationToken的测试方法应改用TestContext.Current.CancellationToken。
🔟 告别Xunit.SkippableFact包
该包整体移除，对应替换关系：
[SkippableFact]→[Fact]，[SkippableTheory]→[Theory]Skip.If(...)→Assert.SkipWhen(...)Skip.IfNot(...)→Assert.SkipUnless(...)
1️⃣1️⃣ 同步升级"伴生包"
| 伴生包 | 版本 |
|---|---|
Xunit.Combinatorial | 1.x → 最新 2.x |
Xunit.StaFact | 1.x → 最新 3.x |
漏掉这两个包是"主包升了、编译还是报错"的常见原因。
1️⃣2️⃣ 构建验证 + 回归测试
最后一步永远是：构建解决方案 → 修复残留编译错误 →dotnet test跑全量测试，确认结果与迁移前完全一致。仓库为该技能准备了 13 组真实迁移场景的评测与夹具（含中央包管理、MTP 项目、SkippableFact 等），可在 tests/dotnet-test-migration/migrate-xunit-to-xunit-v3/ 中逐一参考。
🤖 让 AI 帮你自动执行迁移
这些步骤不必手工敲——dotnet-test-migration插件还带了一个test-migration 编排智能体，它能自动检测你的框架、版本和平台（VSTest 还是 MTP），然后路由到正确的迁移技能并逐步执行：
- 技能定义：plugins/dotnet-test-migration/skills/migrate-xunit-to-xunit-v3/SKILL.md
- 编排智能体：plugins/dotnet-test-migration/agents/test-migration.agent.md
- 插件说明：plugins/dotnet-test-migration/README.md
💡 在 Copilot CLI 或 Claude Code 中执行/plugin marketplace add dotnet/skills安装插件后，直接说"Migrate to xUnit v3"即可触发自动迁移；智能体会先做兼容性检查，不满足条件时会主动停下来告诉你该先做什么。
✅ 迁移完成自检清单
- 所有包引用已切换到
xunit.v3.*，xunit.abstractions已删除 - 测试项目
OutputType为Exe - 测试平台配置正确（VSTest 或 MTP，与迁移前一致）
- 无
async void测试方法残留 - 字符串式特性参数已全部改为
typeof - 伴生包（Combinatorial / StaFact）已升级
dotnet test全量通过，结果与迁移前一致
🎯 按这份清单逐项过一遍，v2 升 v3 就不再是"玄学升级"，而是一次可预期、可回滚的版本升级。
【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
