migrate-mstest-v1v2-to-v3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MSTest v1/v2 -> v3 Migration

MSTest v1/v2 -> v3 迁移指南

Migrate a test project from MSTest v1 (assembly references) or MSTest v2 (NuGet 1.x-2.x) to MSTest v3. MSTest v3 is not binary compatible with v1/v2 -- libraries compiled against v1/v2 must be recompiled.

将测试项目从 MSTest v1（程序集引用方式）或 MSTest v2（1.x-2.x 版本 NuGet 包）迁移到 MSTest v3。MSTest v3 与 v1/v2 不具备二进制兼容性——基于 v1/v2 编译的库必须重新编译才能在 v3 下运行。

When to Use

适用场景

Project references

Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll

(MSTest v1)

Project uses
```
MSTest.TestFramework
```
/
```
MSTest.TestAdapter
```
NuGet 1.x or 2.x
Resolving build errors after updating MSTest packages from v1/v2 to v3
Replacing
```
.testsettings
```
with
```
.runsettings
```
Adopting MSTest.Sdk or in-assembly parallel execution

项目引用了

Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll

（MSTest v1）

项目使用了 1.x 或 2.x 版本的
```
MSTest.TestFramework
```
/
```
MSTest.TestAdapter
```
NuGet 包
需要解决将 MSTest 包从 v1/v2 升级到 v3 后的构建错误
需要将
```
.testsettings
```
替换为
```
.runsettings
```
需要适配 MSTest.Sdk 或程序集内并行执行能力

When Not to Use

不适用场景

Project already uses MSTest v3 (3.x packages)
Upgrading v3 to v4 -- use
```
migrate-mstest-v3-to-v4
```
Migrating between frameworks (MSTest to xUnit/NUnit)

项目已经在使用 MSTest v3（3.x 版本包）
从 v3 升级到 v4——请使用
```
migrate-mstest-v3-to-v4
```
跨测试框架迁移（MSTest 转 xUnit/NUnit）

Inputs

输入参数

Input	Required	Description
Project or solution path	Yes	The `.csproj` , `.sln` , or `.slnx` entry point containing MSTest test projects
Build command	No	How to build (e.g., `dotnet build` , a repo build script). Auto-detect if not provided
Test command	No	How to run tests (e.g., `dotnet test` ). Auto-detect if not provided

输入参数	必填	描述
项目或解决方案路径	是	包含 MSTest 测试项目的 `.csproj` 、 `.sln` 或 `.slnx` 入口文件
构建命令	否	构建项目的命令（例如 `dotnet build` 、仓库自定义构建脚本），未提供则自动检测
测试命令	否	运行测试的命令（例如 `dotnet test` ），未提供则自动检测

Breaking Changes Summary

破坏性变更汇总

MSTest v3 introduces these breaking changes from v1/v2. Address only the ones relevant to the project:

Breaking Change	Impact	Fix
`Assert.AreEqual(object, object)` overload removed	Compile error on untyped assertions	Add generic type: `Assert.AreEqual<T>(expected, actual)` . Same for `AreNotEqual` , `AreSame` , `AreNotSame`
`DataRow` strict type matching	Runtime/compile errors when argument types don't match parameter types exactly	Change literals to exact types: `1` for int, `1L` for long, `1.0f` for float
`DataRow` max 16 constructor parameters (early v3)	Compile error if >16 args; fixed in later v3 versions	Update to latest 3.x, or refactor test / wrap extra params in array
`.testsettings` / `<LegacySettings>` no longer supported	Settings silently ignored	Delete `.testsettings` , create `.runsettings` with equivalent config
Timeout behavior unified across .NET Core / Framework	Tests with `[Timeout]` may behave differently	Verify timeout values; adjust if needed
Dropped target frameworks: .NET 5, .NET Fx < 4.6.2, netstandard1.0, UWP < 16299, WinUI < 18362	Build error	Update TFM: .NET 5 -> net8.0 (LTS) or net6.0+, netfx -> net462+, netstandard1.0 -> netstandard2.0. Note: net6.0, net8.0, net9.0 are all supported
Not binary compatible with v1/v2	Libraries compiled against v1/v2 must be recompiled	Recompile all dependencies against v3

MSTest v3 相比 v1/v2 引入了以下破坏性变更，仅需处理项目涉及的部分即可：

破坏性变更	影响	修复方案
移除了 `Assert.AreEqual(object, object)` 重载	无类型断言会触发编译错误	添加泛型类型： `Assert.AreEqual<T>(expected, actual)` ， `AreNotEqual` 、 `AreSame` 、 `AreNotSame` 同理
`DataRow` 启用严格类型匹配	参数类型与方法入参类型不完全匹配时会触发运行时/编译错误	将字面量修改为匹配的类型：int 用 `1` 、long 用 `1L` 、float 用 `1.0f`
早期 v3 版本中 `DataRow` 构造函数最多支持16个参数	参数超过16个会触发编译错误，后续 v3 版本已修复该问题	升级到最新的 3.x 版本，或者重构测试/将多余参数封装到数组中
不再支持 `.testsettings` / `<LegacySettings>` 配置	原有配置会被静默忽略	删除 `.testsettings` ，创建配置等效的 `.runsettings` 文件
统一了 .NET Core / .NET Framework 下的超时行为	带有 `[Timeout]` 标记的测试行为可能发生变化	验证超时配置值，按需调整
不再支持以下目标框架：.NET 5、.NET Fx < 4.6.2、netstandard1.0、UWP < 16299、WinUI < 18362	触发构建错误	升级目标框架：.NET 5 升级到 net8.0（LTS）或 net6.0+；netfx 升级到 net462+；netstandard1.0 升级到 netstandard2.0。注意：net6.0、net8.0、net9.0 均受支持
与 v1/v2 不具备二进制兼容性	基于 v1/v2 编译的依赖库必须重新编译	将所有依赖项基于 v3 重新编译

Response Guidelines

响应准则

Always identify the current version first: Before recommending any migration steps, explicitly state the current MSTest version detected in the project (e.g., "Your project uses MSTest v2 (2.2.10)" or "This is an MSTest v1 project using QualityTools assembly references"). This grounds the migration advice and confirms you've read the project files.
Focused fix requests (user has specific compilation errors after upgrading): Address only the relevant breaking change from the table above. Show a concise before/after fix. Do not walk through the full migration workflow.
Specific feature migration (user asks about one aspect like .testsettings, DataRow, or assertions): Address only that specific aspect with a concrete fix. Do not walk through the entire migration workflow or unrelated breaking changes.
"What to expect" questions (user asks about breaking changes before upgrading): Present only the breaking changes that are clearly relevant to the user's visible code and configuration. For each, give a one-line fix summary. Do not include every possible breaking change -- only the ones that apply. Do not walk through the full workflow.
Full migration requests (user wants complete migration): Follow the complete workflow below.
Comparison questions (user asks about v1 vs v2 differences): Explain concisely -- v1 uses assembly references and requires removing them first; v2 uses NuGet and just needs a version bump. Both converge on the same v3 packages and breaking changes.

始终先识别当前版本：在给出任何迁移步骤建议前，明确说明项目中检测到的当前 MSTest 版本（例如“你的项目使用 MSTest v2 (2.2.10)”或“这是使用 QualityTools 程序集引用的 MSTest v1 项目”），确保迁移建议基于实际项目情况，也证明你已经读取了项目文件。
针对性修复请求（用户升级后出现特定编译错误）：仅处理上述变更表中对应的破坏性变更，给出简洁的修改前后对比示例，不需要走完完整迁移流程。
特定功能迁移需求（用户仅询问 .testsettings、DataRow、断言等某一方面的迁移方案）：仅针对该特性给出具体修复方案，不需要介绍完整迁移流程或无关的破坏性变更。
“预期影响”类问题（用户在升级前询问破坏性变更）：仅展示与用户可见代码和配置明确相关的破坏性变更，每条给出一行修复摘要，不需要列出所有可能的变更，也不需要走完完整流程。
全量迁移需求（用户需要完成完整迁移）：遵循下面的完整工作流执行。
对比类问题（用户询问 v1 与 v2 的差异）：简洁说明——v1 使用程序集引用，需要先移除引用；v2 使用 NuGet 包，仅需要升级版本。两者升级到 v3 时使用的包和需要处理的破坏性变更一致。

Migration Paths

迁移路径

MSTest v1 (assembly reference to QualityTools): Remove the assembly reference (Step 2), add v3 NuGet packages (Step 3), fix breaking changes (Step 5).
MSTest v2 (NuGet packages 1.x-2.x): Update package versions to 3.x (Step 3), fix breaking changes (Step 5). No assembly reference removal needed.

Both paths converge at Step 3 -- the same v3 packages and breaking changes apply regardless of starting version.

MSTest v1（QualityTools 程序集引用方式）：移除程序集引用（步骤2）、添加 v3 NuGet 包（步骤3）、修复破坏性变更（步骤5）。
MSTest v2（1.x-2.x 版本 NuGet 包方式）：将包版本升级到 3.x（步骤3）、修复破坏性变更（步骤5），不需要移除程序集引用。

两条路径在步骤3后完全一致，无论起始版本是哪个，最终使用的 v3 包和需要处理的破坏性变更都相同。

Workflow

工作流

Step 1: Assess the project

步骤1：评估项目情况

Identify which MSTest version is currently in use:
- Assembly reference: Look for
```
Microsoft.VisualStudio.QualityTools.UnitTestFramework
```
  in project references -> MSTest v1
- NuGet packages: Check
```
MSTest.TestFramework
```
  and
```
MSTest.TestAdapter
```
  package versions -> v1 if 1.x, v2 if 2.x
Check if the project uses a
```
.testsettings
```
file (indicated by
```
<LegacySettings>
```
in test configuration)
Check if the target framework is dropped in v3 (see Step 4)
Run a clean build to establish a baseline of existing errors/warnings

识别当前使用的 MSTest 版本：
- 程序集引用：在项目引用中找到
```
Microsoft.VisualStudio.QualityTools.UnitTestFramework
```
  -> 属于 MSTest v1
- NuGet 包：检查
```
MSTest.TestFramework
```
  和
```
MSTest.TestAdapter
```
  的包版本 -> 1.x 为 v1，2.x 为 v2
检查项目是否使用
```
.testsettings
```
文件（测试配置中存在
```
<LegacySettings>
```
即为使用）
检查项目目标框架是否属于 v3 不再支持的版本（见步骤4）
运行一次干净构建，记录现有错误/警告作为基准

Step 2: Remove v1 assembly references (if applicable)

步骤2：移除 v1 程序集引用（如适用）

If the project uses MSTest v1 via assembly references:

Remove the reference to
```
Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll
```
- In SDK-style projects, remove the
```
<Reference>
```
  element from the
```
.csproj
```
- In non-SDK-style projects, remove via Visual Studio Solution Explorer -> References -> right-click -> Remove
Save the project file

如果项目通过程序集引用方式使用 MSTest v1：

移除
```
Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll
```
引用
- SDK 风格项目：从
```
.csproj
```
  中删除
```
<Reference>
```
  节点
- 非 SDK 风格项目：在 Visual Studio 解决方案资源管理器 -> 引用 -> 右键点击对应引用 -> 移除
保存项目文件

Step 3: Update packages to MSTest v3

步骤3：升级包到 MSTest v3

Choose one of these approaches:

Option A -- Install the MSTest metapackage (recommended):

Remove individual

MSTest.TestFramework

and

MSTest.TestAdapter

package references and replace with the unified

MSTest

metapackage:

xml

<PackageReference Include="MSTest" Version="3.8.0" />

Also ensure

Microsoft.NET.Test.Sdk

is referenced (or update individual

MSTest.TestFramework

MSTest.TestAdapter

packages to 3.8.0 if you prefer not using the metapackage).

Option B -- Use MSTest.Sdk (SDK-style projects only):

Change

<Project Sdk="Microsoft.NET.Sdk">

<Project Sdk="MSTest.Sdk/3.8.0">

. MSTest.Sdk automatically provides MSTest.TestFramework, MSTest.TestAdapter, MSTest.Analyzers, and Microsoft.NET.Test.Sdk.

Important: MSTest.Sdk defaults to Microsoft.Testing.Platform (MTP) instead of VSTest. For VSTest compatibility (e.g.,
vstest.console
in CI), add
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />
.

When switching to MSTest.Sdk, remove these (SDK provides them automatically):

Packages:

MSTest

MSTest.TestFramework

MSTest.TestAdapter

MSTest.Analyzers

Microsoft.NET.Test.Sdk

Properties:

<EnableMSTestRunner>

<OutputType>Exe</OutputType>

<IsPackable>false</IsPackable>

<IsTestProject>true</IsTestProject>

选择以下任意一种方式：

方案 A -- 安装 MSTest 元包（推荐）：

移除单独的

MSTest.TestFramework

和

MSTest.TestAdapter

包引用，替换为统一的

MSTest

元包：

xml

<PackageReference Include="MSTest" Version="3.8.0" />

同时确保引用了

Microsoft.NET.Test.Sdk

（如果你不想使用元包，也可以单独将

MSTest.TestFramework

MSTest.TestAdapter

升级到 3.8.0 版本）。

方案 B -- 使用 MSTest.Sdk（仅支持 SDK 风格项目）：

将

<Project Sdk="Microsoft.NET.Sdk">

修改为

<Project Sdk="MSTest.Sdk/3.8.0">

。MSTest.Sdk 会自动提供 MSTest.TestFramework、MSTest.TestAdapter、MSTest.Analyzers 和 Microsoft.NET.Test.Sdk。

重要提示：MSTest.Sdk 默认使用 Microsoft.Testing.Platform (MTP) 而非 VSTest。如果需要 VSTest 兼容性（例如 CI 中使用
vstest.console
），请添加
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.13.0" />
。

切换到 MSTest.Sdk 后，请移除以下内容（SDK 会自动提供）：

包引用：

MSTest

、

MSTest.TestFramework

、

MSTest.TestAdapter

、

MSTest.Analyzers

、

Microsoft.NET.Test.Sdk

属性配置：

<EnableMSTestRunner>

、

<OutputType>Exe</OutputType>

、

<IsPackable>false</IsPackable>

、

<IsTestProject>true</IsTestProject>

Step 4: Update target frameworks if needed

步骤4：按需升级目标框架

MSTest v3 supports .NET 6+, .NET Core 3.1, .NET Framework 4.6.2+, .NET Standard 2.0, UWP 16299+, and WinUI 18362+. If the project targets a dropped framework version, update to a supported one:

Dropped	Recommended replacement
.NET 5	.NET 8.0 (current LTS) or .NET 6+
.NET Framework < 4.6.2	.NET Framework 4.6.2
.NET Standard 1.0	.NET Standard 2.0
UWP < 16299	UWP 16299
WinUI < 18362	WinUI 18362

Note: .NET 6, .NET 8, and .NET 9 are all supported by MSTest v3. Do not change TFMs that are already supported.

MSTest v3 支持 .NET 6+、.NET Core 3.1、.NET Framework 4.6.2+、.NET Standard 2.0、UWP 16299+ 和 WinUI 18362+。如果项目使用了不再支持的框架版本，请升级到受支持版本：

不再支持的版本	推荐替换版本
.NET 5	.NET 8.0（当前 LTS 版本）或 .NET 6+
.NET Framework < 4.6.2	.NET Framework 4.6.2
.NET Standard 1.0	.NET Standard 2.0
UWP < 16299	UWP 16299
WinUI < 18362	WinUI 18362

注意：.NET 6、.NET 8 和 .NET 9 都受 MSTest v3 支持，已经在使用受支持版本的不需要修改。

Step 5: Resolve build errors and breaking changes

步骤5：解决构建错误和破坏性变更

Run

dotnet build

and fix errors using the Breaking Changes Summary above. Key fixes:

Assertion overloads -- MSTest v3 removed

Assert.AreEqual(object, object)

and

Assert.AreNotEqual(object, object)

. Add explicit generic type parameters:

csharp

// Before (v1/v2)                           // After (v3)
Assert.AreEqual(expected, actual);        -> Assert.AreEqual<MyType>(expected, actual);
Assert.AreNotEqual(a, b);                -> Assert.AreNotEqual<MyType>(a, b);
Assert.AreSame(expected, actual);         -> Assert.AreSame<MyType>(expected, actual);

DataRow strict type matching -- argument types must exactly match parameter types. Implicit conversions that worked in v2 fail in v3:

csharp

// Error: 1L (long) won't convert to int parameter -> fix: use 1 (int)
// Error: 1.0 (double) won't convert to float parameter -> fix: use 1.0f (float)

Timeout behavior -- unified across .NET Core and .NET Framework. Verify

[Timeout]

values still work.

运行

dotnet build

，参考上面的破坏性变更汇总修复错误，核心修复点：

断言重载问题——MSTest v3 移除了

Assert.AreEqual(object, object)

和

Assert.AreNotEqual(object, object)

，需要添加显式泛型类型参数：

csharp

// 修改前 (v1/v2)                           // 修改后 (v3)
Assert.AreEqual(expected, actual);        -> Assert.AreEqual<MyType>(expected, actual);
Assert.AreNotEqual(a, b);                -> Assert.AreNotEqual<MyType>(a, b);
Assert.AreSame(expected, actual);         -> Assert.AreSame<MyType>(expected, actual);

DataRow 严格类型匹配——参数类型必须与方法入参类型完全匹配，v2 中可用的隐式转换在 v3 中会失败：

csharp

// 错误：1L (long) 无法转换为 int 类型参数 -> 修复：使用 1 (int)
// 错误：1.0 (double) 无法转换为 float 类型参数 -> 修复：使用 1.0f (float)

超时行为——.NET Core 和 .NET Framework 下的超时逻辑已统一，验证

[Timeout]

配置值是否仍然符合预期。

Step 6: Replace .testsettings with .runsettings

步骤6：将 .testsettings 替换为 .runsettings

The

.testsettings

file and

<LegacySettings>

are no longer supported in MSTest v3. Delete the
.testsettings
file and create a

.runsettings

file -- do not keep both.

Key mappings:

.testsettings	.runsettings equivalent
`TestTimeout` property	`<MSTest><TestTimeout>30000</TestTimeout></MSTest>`
Deployment config	`<MSTest><DeploymentEnabled>true</DeploymentEnabled></MSTest>` or remove
Assembly resolution settings	Remove -- not needed in modern .NET
Data collectors	`<DataCollectionRunSettings><DataCollectors>` section

Important: Map timeout to
<MSTest><TestTimeout>
(per-test), not
<TestSessionTimeout>
(session-wide). Remove
<LegacySettings>
entirely.

MSTest v3 不再支持

.testsettings

文件和

<LegacySettings>

配置。删除
.testsettings
文件并创建

.runsettings

文件，不要同时保留两个文件。

核心配置映射关系：

.testsettings 配置	.runsettings 等效配置
`TestTimeout` 属性	`<MSTest><TestTimeout>30000</TestTimeout></MSTest>`
部署配置	`<MSTest><DeploymentEnabled>true</DeploymentEnabled></MSTest>` 或直接移除
程序集解析配置	移除——现代 .NET 不需要该配置
数据采集器	`<DataCollectionRunSettings><DataCollectors>` 节点

重要提示：超时配置要映射到
<MSTest><TestTimeout>
（单测试维度），不要映射到
<TestSessionTimeout>
（会话维度）。完全移除
<LegacySettings>
配置。

Step 7: Verify

步骤7：验证

Run
```
dotnet build
```
-- confirm zero errors and review any new warnings
Run
```
dotnet test
```
-- confirm all tests pass
Compare test results (pass/fail counts) to the pre-migration baseline
Check that no tests were silently dropped due to discovery changes

运行
```
dotnet build
```
——确认无构建错误，检查新增的警告
运行
```
dotnet test
```
——确认所有测试通过
对比迁移前后的测试结果（通过/失败数量）是否一致
确认没有测试因为发现逻辑变更被静默忽略

Validation

校验清单

MSTest v3 packages (or MSTest.Sdk) correctly referenced; v1/v2 references removed
Project builds with zero errors
All tests pass (
```
dotnet test
```
) -- compare pass/fail counts to pre-migration baseline
```
.testsettings
```
replaced with
```
.runsettings
```
(if applicable)

已正确引用 MSTest v3 包（或 MSTest.Sdk），已移除 v1/v2 引用
项目构建无错误
所有测试通过（
```
dotnet test
```
）——与迁移前基准的通过/失败数量一致
已将
```
.testsettings
```
替换为
```
.runsettings
```
（如适用）

Next Step

后续步骤

After v3 migration, use

migrate-mstest-v3-to-v4

for MSTest v4.

完成 v3 迁移后，可使用

migrate-mstest-v3-to-v4

工具迁移到 MSTest v4。

Common Pitfalls

常见陷阱

Pitfall	Solution
Missing `Microsoft.NET.Test.Sdk`	Add package reference -- required for test discovery with VSTest
MSTest.Sdk tests not found by `vstest.console`	MSTest.Sdk defaults to Microsoft.Testing.Platform; add explicit `Microsoft.NET.Test.Sdk` for VSTest compatibility

陷阱	解决方案
缺失 `Microsoft.NET.Test.Sdk` 引用	添加该包引用——VSTest 测试发现需要该依赖
`vstest.console` 无法发现 MSTest.Sdk 测试	MSTest.Sdk 默认使用 Microsoft.Testing.Platform，添加显式的 `Microsoft.NET.Test.Sdk` 引用获得 VSTest 兼容性