Microsoft·Testing·Platform（MTP）配置设置

MTP 支持使用配置文件和环境变量来配置测试平台的行为。本文介绍可用于配置测试平台的配置设置。

testconfig.json

测试平台使用名为 [appname] 的配置文件.testconfig.json 来配置测试平台的行为。 testconfig.json 文件是一个 JSON 文件，其中包含测试平台的配置设置。

testconfig.json 文件具有以下结构：

{
    "platformOptions": {
        "resultDirectory": "./TestResults"
    }
}

平台将自动检测并加载位于测试项目的输出目录中 的 [appname].testconfig.json 文件（靠近可执行文件）。

使用 Microsoft.Testing.Platform.MSBuild 时，只需创建 一个testconfig.json 文件，该文件将自动重命名为 [appname].testconfig.json 并移动到测试项目的输出目录。

从 MTP 1.5 开始，可以使用命令行参数 --config-file 指定 testconfig.json的路径。此文件优先于 [appname].testconfig.json 文件。

注释

[appname].testconfig.json 文件将在后续构建时被覆盖。

使用统一的 testconfig.json

如果希望跨多个测试项目共享单个 testconfig.json ，可以将它放置在中心位置并通过该位置传递 --config-file。当 MSBuild 可用时（例如，dotnet test 或 dotnet run），你可以使用 TestingPlatformCommandLineArguments MSBuild 属性自动传递该参数。将此添加到存储库根目录中的 Directory.Build.props 可确保所有测试项目使用相同的配置：

<PropertyGroup>
  <TestingPlatformCommandLineArguments>
    $(TestingPlatformCommandLineArguments) --config-file $(MSBuildThisFileDirectory)testconfig.json
  </TestingPlatformCommandLineArguments>
</PropertyGroup>

配置优先级

当同一设置可以通过多种方式指定时，MTP 按以下顺序解析（首个匹配胜出）：

命令行参数（例如 --results-directory）
环境变量
testconfig.json 设置
内置默认值

平台选项

platformOptions 文件中的部分用于配置测试平台的核心行为。下表列出了所有受支持的平台选项：

项	默认	说明
`resultDirectory`	`TestResults`	用于放置测试结果的目录。可以是相对路径（从当前工作目录解析）或绝对路径。 `--results-directory`命令行选项优先。
`exitProcessOnUnhandledException`	`false`	当设置为 `true` 时，测试主机进程会在发生未处理异常时立即退出，而不是进行优雅关闭。 `TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION`环境变量（值`1`或`0`）优先。

注释

存在用于高级方案的其他内部平台选项（例如测试主机控制器的命名管道超时）。这些选项适用于基础结构使用，此处未介绍。

例：

{
  "platformOptions": {
    "resultDirectory": "../../TestResults",
    "exitProcessOnUnhandledException": false
  }
}

testconfig.json 中的环境变量

注释

从版本 2.3.0 开始，MTP 中可用。

该 environmentVariables 部分在开始之前为测试过程设置环境变量。对每个变量使用字符串值。

{
  "environmentVariables": {
    "DOTNET_ENVIRONMENT": "Development",
    "FEATURE_FLAG": "true"
  }
}

testconfig.json 中的 CLI 选项

在 MTP 2.3.0 之前，扩展功能（如崩溃转储、挂起转储、重试、TRX 报告和代码覆盖率）无法通过 testconfig.json 配置。这些功能仅通过命令行参数进行配置。

从 MTP 2.3.0 开始，MTP 可以通过从 IConfiguration 读取 CLI 选项。此支持包括对扩展选项的支持，因此，对于那些不想在每次运行时都通过命令行传递的选项，你可以使用 JSON 条目。命令行参数仍优先。

配置不会安装或注册扩展。每个测试应用程序都必须直接或通过测试 SDK 配置或配置文件引用提供扩展选项的包。否则，无论将其置于 testconfig.json 还是命令行上，该选项仍无法识别。

将 commandLineOptions 对象用于活动选项。省略每个键的前导 -- 。使用 true 表示零参数选项，并使用 false 禁用某个选项。对于一个参数，请使用字符串或数字。对于重复或多个参数，请使用数组：

{ "commandLineOptions": {
  "report-trx": true,
  "report-trx-filename": "results.trx",
  "filter-uid": ["test-1", "test-2"]
} }

MTP 将字符串或数字标量视为参数承载选项的第一个参数。若要传递布尔参数，请使用数组，例如 [true] 或 [false]。数组将参数与布尔状态值区分开来。

MTP 验证配置的条目，如命令行条目。未知选项、无效值以及参数个数不正确的值都无法通过验证。显式命令行选项替代相应的 commandLineOptions 条目。

仅限引导的选项会在 MTP 加载配置之前运行。不要将config-file、diagnostic-output-directory、diagnostic-file-prefix、diagnostic-verbosity、diagnostic-synchronous-write、enable-dynamic-extensions或commandLineOptions放入diagnostic中。

被动命令行选项默认值

Important

commandLineOptionDefaults 在 MTP 2.4 预览版中提供。

仅当启用的功能请求该选项且不存在高优先级值时，才可用于 commandLineOptionDefaults 提供参数。被动默认值不会启用选项、注册扩展或激活功能。省略每个键的前导 -- 。

{ "commandLineOptionDefaults": {
  "report-trx-filename": "{asm}.trx",
  "show-test-results": ["failed", "skipped"]
} }

MTP 使用此优先级顺序中的第一个匹配项解析选项值：

显式的命令行值。
一个处于活动状态的commandLineOptions条目。
commandLineOptionDefaults testconfig.json中的条目。
MSBuild 提供的默认值。

对于 MSBuild 提供的默认项，请添加一个 TestingPlatformCommandLineOptionDefault 项。该值 Include 必须省略前导连字符：

<TestingPlatformCommandLineOptionDefault Include="report-trx-filename"
                                         Value="{asm}.trx" />

有关命令行选项的完整参考，请参阅 MTP CLI 选项参考。

特定框架的测试设置

测试框架可以在 testconfig.json 文件中定义其自己的配置节。请参阅测试框架的文档：

MSTest：配置 MSTest — testconfig.json
xUnit.net v3： xUnit.net testconfig.json
NUnit：有关最新的 Microsoft.Testing.Platform 支持信息，请参阅 NUnit 文档。
TUnit：有关最新的 Microsoft.Testing.Platform 支持，请参阅 TUnit 文档。

示例 testconfig.json

以下示例显示了一个用于配置平台选项和 MSTest 设置的 testconfig.json 文件：

{
  "platformOptions": {
    "resultDirectory": "./TestResults"
  },
  "mstest": {
    "parallelism": {
      "enabled": true,
      "workers": 4,
      "scope": "method"
    },
    "timeout": {
      "test": 30000
    },
    "execution": {
      "considerFixturesAsSpecialTests": true
    }
  }
}

从 .runsettings 迁移到 testconfig.json

如果要从 .runsettings 文件迁移，下表将通用设置映射到其 testconfig.json 等效项或替代项：

.runsettings 设置	testconfig.json 等效项	备注
`RunConfiguration/ResultsDirectory`	`platformOptions.resultDirectory`
`RunConfiguration/MaxCpuCount`	无等效项	进程级并行度由 `dotnet test --max-parallel-test-modules` MSBuild `/m` 选项控制。
`MSTest/*`	`mstest.*`	请参阅配置 MSTest — testconfig.json。
`xUnit/*`	`xUnit.*`	请参阅 xUnit.net testconfig.json。
`LoggerRunSettings/Loggers`	CLI 选项	使用已安装报表扩展中的选项。例如，`--report-trx` 要求 `Microsoft.Testing.Extensions.TrxReport`。从 MTP 2.3.0 开始，MTP 可以从 testconfig.json读取 CLI 选项。请参阅测试报告。
`DataCollectionRunSettings`（归咎）	CLI 选项	使用来自 `--hangdump` 的 `Microsoft.Testing.Extensions.CrashDump`，或来自 `--crashdump` 的 `Microsoft.Testing.Extensions.HangDump`。从 MTP 2.3.0 开始，MTP 可以从 testconfig.json读取 CLI 选项。请参阅崩溃和挂起转储。
`DataCollectionRunSettings` （覆盖范围）	CLI 选项	使用 `Microsoft.Testing.Extensions.CodeCoverage` 中的 `--coverage`。从 MTP 2.3.0 开始，MTP 可以从 testconfig.json读取 CLI 选项。请参阅代码覆盖率。
`TestRunParameters`	`--test-parameter` CLI（命令行界面）	在命令行中使用 `--test-parameter key=value`。

MSBuild 配置

Important

TestingPlatformEnvironmentVariable 在 MTP 2.4 预览版中提供。

若要在 InvokeTestingPlatform 启动的测试进程中设置环境变量，请添加一个 TestingPlatformEnvironmentVariable 项：

<TestingPlatformEnvironmentVariable Include="MY_OPTIONS"
                                    Value="first;second" />

元数据 Value 保留分号，而不是将它们拆分为 MSBuild 项。声明的值覆盖 MSBuild 进程继承的环境。如果没有这些项，启动的进程将继承环境不变。

环境变量

环境变量可用于提供某些运行时配置信息。

注释

环境变量优先于 testconfig.json 文件中的配置设置。

`TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION` 环境变量

当设置为 1 时，测试主机进程会在发生未处理的异常时立即退出。设置为 0时，平台允许正常关闭。此设置优先于 platformOptions:exitProcessOnUnhandledException 配置。

`TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT` 环境变量

覆盖测试主机控制器与测试主机之间命名管道连接的默认超时时间（300 秒）。该值必须是 TimeSpan兼容字符串。

`TESTINGPLATFORM_UI_LANGUAGE` 环境变量

从 MTP 1.5 开始，此环境变量设置平台的语言，以便使用区域设置值（例如 en-us）显示消息和日志。此语言优先于 Visual Studio 和 .NET SDK 语言。支持的值与 Visual Studio 中的值相同。有关详细信息，请参阅 Visual Studio 安装文档中有关更改安装程序语言一节。

`TESTINGPLATFORM_DIAGNOSTIC` 环境变量

如果设置为 1，则启用诊断日志记录。

`TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY` 环境变量

定义启用诊断时的详细级别。可用值包括 Trace、Debug、Information、Warning、Error 和 Critical。

`TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY` 环境变量

诊断日志的输出目录。如果未指定，则会在默认 TestResults 目录中生成该文件。

`TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX` 环境变量

日志文件名的前缀。默认情况下，MTP 使用 <asm>_<tfm>_<arch> 并追加时间戳。生成的文件名为 <asm>_<tfm>_<arch>_<timestamp>.diag. 该变量与命令行选项匹配 --diagnostic-file-prefix 。

注释

从版本 2.3.0 开始，MTP 中提供了此环境变量名称。旧 TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX 版环境变量仍遵循向后兼容性，但已弃用，并可能在将来的主版本中删除。设置这两个变量时， TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX 优先。

`TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE` 环境变量

强制内置的文件记录器以同步方式写入日志。对于在进程崩溃时不想丢失任何日志条目的场景非常有用。这会降低测试执行速度。匹配 --diagnostic-synchronous-write 命令行选项。

注释

从版本 2.3.0 开始，MTP 中提供了此环境变量名称。旧 TESTINGPLATFORM_DIAGNOSTIC_FILELOGGER_SYNCHRONOUSWRITE 版环境变量仍遵循向后兼容性，但已弃用，并可能在将来的主版本中删除。设置这两个变量时， TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE 优先。

`TESTINGPLATFORM_EXITCODE_IGNORE` 环境变量

要忽略的、以分号分隔的退出代码列表。当退出代码被忽略时，进程将改为返回 0。例如， TESTINGPLATFORM_EXITCODE_IGNORE=2;8 忽略测试失败和未运行测试的方案。

`TESTINGPLATFORM_NOBANNER` 环境变量

当设置为 1 或 true 时，将不显示启动横幅、版权信息和遥测横幅。等效于 --no-banner 命令行选项。环境变量 DOTNET_NOLOGO 具有相同的效果。

`NO_COLOR` 环境变量

如果设置为任何非空值，则禁止显示所有 ANSI 颜色输出。 MTP 遵循该 NO_COLOR 约定。

注释

从版本 2.3.0 开始，MTP 中可用。

`DOTNET_NOLOGO` 环境变量

当设置为 1 或 true 时，将不显示启动横幅、版权信息和遥测横幅。这是标准.NET CLI 环境变量，MTP 遵循此标准。另请参阅 TESTINGPLATFORM_NOBANNER。

`TESTINGPLATFORM_PIPE_DIRECTORY` 环境变量

从 MTP 2.4.0 开始，此变量会替代 MTP 为命名管道通信创建 Unix 域套接字文件的目录。当沙盒或容器不允许在默认临时目录中创建套接字时，请使用此变量。 MTP 创建并检查目录，当目录不可写或生成的套接字路径过长时出错。

该变量对Windows没有影响，其中命名管道不使用文件系统路径。它还不会重新定位另一个进程（如 .NET SDK）创建的管道。

截止时间取消原型

Warning

实验性/原型： 截止期限取消是 MTP 2.4 预览版中的一项原型功能。其变量和行为可以更改或删除。

将 TESTINGPLATFORM_DEADLINE 设置为截止时间生成器提供的完整硬取消时刻。使用 ISO 8601 UTC 值。不要从值中减去 MTP 的边距。

MTP 会在截止时间之前请求正常停止。 TESTINGPLATFORM_DEADLINE_STOP_MARGIN 控制提前多久，默认值为 60 秒。不支持正常停止的测试框架将忽略此请求。

作为后备措施，TESTINGPLATFORM_DEADLINE_DUMP_MARGIN 会在截止期限前启动一个已激活的 HangDump 扩展。边距默认为 30 秒。 HangDump 捕获进程树，然后终止测试宿主进程。如果没有截止时间，MTP 不会启动截止时间计时器。

截止时间生成方仍负责在指定时刻执行硬取消。

`TESTINGPLATFORM_WAIT_ATTACH_DEBUGGER` 环境变量

当设置为 1 时，测试进程会在启动时暂停，并在继续之前等待调试器附加。等效于 --debug 命令行选项。浏览器平台上不受支持。

注释

从版本 1.6.0 开始，MTP 中提供了此环境变量。

`TESTINGPLATFORM_LAUNCH_ATTACH_DEBUGGER` 环境变量

当设置为 1 时，测试进程会在启动时调用 Debugger.Launch()，这会提示系统启动即时调试器并将其附加到该进程。使用此变量调试启动时间问题（例如，服务器模式握手），这些问题发生在你可以手动附加之前。在非Windows平台上，行为取决于配置的 JIT 调试器。

注释

从版本 1.6.0 开始，MTP 中提供了此环境变量。

注释

与诊断相关的环境变量优先于其相应的 --diagnostic-* 命令行参数。

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-09-03

Microsoft·Testing·Platform（MTP）配置设置

testconfig.json

使用统一的 testconfig.json

配置优先级

平台选项

testconfig.json 中的环境变量

testconfig.json 中的 CLI 选项

被动命令行选项默认值

特定框架的测试设置

示例 testconfig.json

从 .runsettings 迁移到 testconfig.json

MSBuild 配置

环境变量

TESTINGPLATFORM_EXIT_PROCESS_ON_UNHANDLED_EXCEPTION 环境变量

TESTINGPLATFORM_DEFAULT_HANG_TIMEOUT 环境变量

TESTINGPLATFORM_UI_LANGUAGE 环境变量

TESTINGPLATFORM_DIAGNOSTIC 环境变量

TESTINGPLATFORM_DIAGNOSTIC_VERBOSITY 环境变量

TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_DIRECTORY 环境变量

TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX 环境变量

TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE 环境变量

TESTINGPLATFORM_EXITCODE_IGNORE 环境变量

TESTINGPLATFORM_NOBANNER 环境变量

NO_COLOR 环境变量

DOTNET_NOLOGO 环境变量

TESTINGPLATFORM_PIPE_DIRECTORY 环境变量