mtp-hot-reload

用于迭代修复测试的 MTP 热重载

设置并使用长期运行的 Microsoft Testing Platform 主机，在应用代码编辑后自动重新运行测试。

适用场景

• 用户明确要求测试热重载
• 用户希望主机持续运行，并在反复编辑后自动重新运行
• 用户需要在项目中设置 MTP 热重载

不适用场景

• 用户需要从头编写新测试（使用通用编码协助）
• 用户需要诊断测试失败的原因（使用诊断技能）
• 用户询问 Visual Studio 或 VS Code Test Explorer 热重载，或 IDE 集成的重新运行体验（这是另一项功能，不是 MTP 控制台主机热重载）
• 用户询问编辑器能否在不使用 MTP 控制台主机的情况下，于源代码编辑后自动重新运行受影响的测试
• 用户只需要一次正常运行且不重新生成（使用 run-tests）
• 用户需要配置 CI/CD 管道

输入

输入	必填	描述
测试项目路径	否	测试项目 (.csproj) 的路径。默认为当前目录。
失败的测试名称或筛选条件	否	要迭代处理的特定测试

响应篇幅

• 如果已完成设置，且用户只询问要使用哪个命令， 则返回一条 dotnet run --project <path> 命令，并用一句话说明 该命令会启动持久运行的主机。不要重复提及程序包、启动配置文件或 不支持的编辑指导。
• 如果已安装程序包，只展示剩余的启用和运行步骤。不要建议重新安装， 也不要添加可选的持久化或恢复方案，除非用户提出要求。
• 如果用户指定了测试名称，请识别测试框架，并返回一条使用该框架筛选语法的可运行命令。绝不能用 MSTest/NUnit 的 --filter 替代 xUnit v3 的 --filter-method 或 TUnit 的 --treenode-filter。
• 直接启动的 MTP 主机本身就是持久运行的监视器：dotnet run 会持续运行，而 HotReload 扩展会响应编辑。正常的 MTP 流程中不要用 dotnet watch run 替代它；仅在下文明确说明的重启备用方案中使用 dotnet watch。

工作流

步骤 1：更改任何内容之前检测平台

热重载需要 MTP，不适用于 VSTest。

按照 platform-detection 技能中的完整已评估属性流程操作。除项目文件外，还要读取导入的 props 和程序包版本。 在安装程序包、编辑文件或返回 MTP 启动命令之前，必须完成此操作。

**VSTest 的硬性停止条件：**说明按当前项目配置无法使用 MTP 热重载，并停止 MTP 设置流程。不要安装扩展、创建 launchSettings.json、设置环境变量、更改运行器属性或程序包，也不要返回 dotnet run 热重载命令。绝不能将设置请求擅自转为从 VSTest 迁移到 MTP。

提供一个保留现有项目的有效非 MTP 备用方案：

dotnet watch --project <project-path> test

当文件发生变化时，此方案会重新生成并重新运行现有的 VSTest 项目；它不是 MTP 热重载。可将明确迁移到 MTP 作为另一种选择提出，但除非用户要求，否则不要执行。一次性测试命令仍由 run-tests 负责。

步骤 2：添加热重载 NuGet 程序包

首先检查生效的程序包引用。如果已经安装 Microsoft.Testing.Extensions.HotReload，则保留其版本并跳过此步骤。否则安装：

dotnet add <project-path> package Microsoft.Testing.Extensions.HotReload

注意：使用 Microsoft.Testing.Platform.MSBuild（由 MSTest、NUnit 和 xUnit 运行器传递引入）时，安装其 NuGet 程序包后会自动注册该扩展——无需更改代码。

步骤 3：启用热重载

将环境变量 TESTINGPLATFORM_HOTRELOAD_ENABLED 设置为 1 即可启用热重载。

选项 A —— 在运行测试前于 Shell 中设置：

# PowerShell
$env:TESTINGPLATFORM_HOTRELOAD_ENABLED = "1"

# bash/zsh
export TESTINGPLATFORM_HOTRELOAD_ENABLED=1

选项 B —— 将其添加到 launchSettings.json（推荐用于重复使用）：

在测试项目中创建或更新 Properties/launchSettings.json：

{
  "profiles": {
    "<ProjectName>": {
      "commandName": "Project",
      "environmentVariables": {
        "TESTINGPLATFORM_HOTRELOAD_ENABLED": "1"
      }
    }
  }
}

步骤 4：通过热重载运行测试

直接运行测试项目（而不是通过 dotnet test），以便在控制台模式下使用热重载：

dotnet run --project <project-path>

如需筛选特定的失败测试，请在 -- 后传入筛选条件。仅当以下示例无法确定框架的语法时，才阅读随附或运行时列出的 filter-syntax 目录文件；不要调用这个仅供参考的辅助工具。快速示例：

框架	筛选语法
MSTest	dotnet run --project <path> -- --filter "FullyQualifiedName~TestMethodName"
NUnit	dotnet run --project <path> -- --filter "FullyQualifiedName~TestMethodName"
xUnit v3	dotnet run --project <path> -- --filter-method "*TestMethodName"
TUnit	dotnet run --project <path> -- --treenode-filter "/*/*/ClassName/TestMethodName"

测试宿主将启动并运行测试，然后保持运行，等待代码变更。

步骤 5：迭代修复

1. 在编辑器中编辑源代码（测试代码或生产代码）
2. 测试宿主会检测到变更，并自动重新运行受影响的测试
3. 在控制台中查看更新后的结果
4. 重复上述步骤，直至所有目标测试通过

重要提示：热重载目前仅支持控制台模式。Visual Studio 或 Visual Studio Code 的测试资源管理器不支持热重载。

不支持的编辑和不兼容编辑

方法签名变更、新类型及其他不支持的编辑无法应用到正在运行的进程。切勿声称过时的宿主已载入这些变更。

对于直接启动的 MTP 宿主：

1. 保留启动当前宿主时使用的确切命令、配置文件、环境、筛选条件和参数。
2. 使用 Ctrl+C 停止宿主。
3. 重新生成同一项目：dotnet build <project-path>。
4. 重新运行相同的原始宿主命令。不要将未知的现有调用替换为通用的 dotnet run 命令。

如果预计会有反复出现的不支持编辑，请提供由监视工具管理的重启备用方案：

# PowerShell
$env:TESTINGPLATFORM_HOTRELOAD_ENABLED = "1"
$env:DOTNET_WATCH_RESTART_ON_RUDE_EDIT = "1"
dotnet watch --project <project-path> run -- <existing-MTP-arguments>

如果无法应用不兼容编辑，dotnet watch 会重启进程。未设置自动重启变量时，请接受重启提示或按 Ctrl+R。保留 -- 后已有的任何测试筛选条件。 DOTNET_WATCH_RESTART_ON_RUDE_EDIT 是有文档说明的 .NET SDK 开关，而不是 MTP 扩展设置。如果用户可能质疑其正确性，请引用 dotnet watch 文档，并说明该设置会让监视器重启，而不是发出提示。切勿省略原有筛选条件，也不要用一次性 dotnet run 替代用户要求的由监视工具管理的备用方案。

步骤 6：完成

所有测试通过后：

1. 停止测试宿主（Ctrl+C）
2. 当用户要求确切的一次性验证命令、标志、筛选条件、TRX 或转储时，使用 run-tests
3. 可以选择从环境中移除 TESTINGPLATFORM_HOTRELOAD_ENABLED，或保留 launchSettings.json 供将来使用

验证

• 项目使用 Microsoft Testing Platform（而非 VSTest）
• 已安装 Microsoft.Testing.Extensions.HotReload 包
• TESTINGPLATFORM_HOTRELOAD_ENABLED 环境变量已设置为 1
• 测试已运行，且宿主保持活动状态，等待变更
• 代码变更无需手动重启即可生效

常见问题

问题	解决方案
使用 dotnet test 而不是 dotnet run	热重载要求使用 dotnet run --project <path>，在控制台模式下直接运行测试宿主
项目使用 VSTest，而非 MTP	不要修改它。提供 dotnet watch --project <path> test 作为重新生成并重新运行的备用方案，或另行明确迁移
忘记设置环境变量	运行前设置 TESTINGPLATFORM_HOTRELOAD_ENABLED=1
期待与测试资源管理器集成	仅支持控制台模式——不支持 VS/VS Code 测试资源管理器
进行不支持的代码变更（不兼容编辑）	停止、重新生成并重新运行相同的宿主调用，或使用 dotnet watch 的不兼容编辑后重启功能