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時，您只要建立會自動重新命名為 [appname] .testconfig.json 的 testconfig.json 檔案，並移至測試專案的輸出目錄。

從 MTP 1.5 開始，你可以用命令列參數 --config-file 來指定 testconfig.json的路徑。此檔案的優先順序高於 [appname].testconfig.json 檔案。

備註

[appname].testconfig.json 檔案將會在後續組建上覆寫。

使用集中管理的 testconfig.json

如果你想讓單一 testconfig.json 在多個測試專案間共享，你可以把它放在中央位置，並透過 --config-file傳遞。當 MSBuild 可用（例如 dotnet testdotnet 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 之前，crash dump、hang dump、retry、TRX reports 和 code coverage 等延伸功能無法透過 testconfig.json 進行設定。這些功能完全透過命令列參數來配置。

從 MTP 2.3.0 開始，MTP 可以讀取從 testconfig.json 到 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 的條目。

僅限 Bootstrap 的選項會在 MTP 載入設定前執行。不要將 config-file、diagnostic、diagnostic-output-directory、commandLineOptions、diagnostic-file-prefix、diagnostic-verbosity 或 diagnostic-synchronous-write 放入 enable-dynamic-extensions 中。

被動式命令列選項預設值

Important

commandLineOptionDefaults 可在 MTP 2.4 預覽版中取得。

僅在啟用功能請求該選項且沒有更高優先權值時，提供 commandLineOptionDefaults 參數。被動預設不會啟用選項、註冊擴充功能或啟用功能。省略每個鍵前導的 --。

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

MTP 透過以下優先順序中的第一個匹配來解析選項值：

一個明確的命令列值。
一個作用中的 commandLineOptions 項目。
commandLineOptionDefaults 中的一個項目。
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：請參閱 NUnit 文件以獲得最新Microsoft。測試。平台支援。
TUnit：請參閱 TUnit 文件以獲得最新Microsoft。測試。平台支援。

範例 testconfig.json

以下範例展示了一個 testconfig.json 檔案，用以配置平台選項和 MSTest 設定：

{
  "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 等價物	Notes
`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 選項	使用來自 `Microsoft.Testing.Extensions.CrashDump` 的 `--hangdump`，或來自 `--crashdump` 的 `Microsoft.Testing.Extensions.HangDump`。從 MTP 2.3.0 開始，MTP 可以從 testconfig.json讀取 CLI 選項。請參見崩盤與懸浮傾倒。
`DataCollectionRunSettings` （報導範圍）	CLI 選項	使用 `--coverage` 來源 `Microsoft.Testing.Extensions.CodeCoverage`。從 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 。

備註

此環境變數名稱自 MTP 版本 2.3.0 起提供。舊有 TESTINGPLATFORM_DIAGNOSTIC_OUTPUT_FILEPREFIX 環境變數仍被尊重以符合向下相容性，但已棄用，未來主要版本可能會被移除。當兩個變數都已設定時，TESTINGPLATFORM_DIAGNOSTIC_FILE_PREFIX 會優先。

`TESTINGPLATFORM_DIAGNOSTIC_SYNCHRONOUS_WRITE` 環境變數

強制內建檔案記錄器同步寫入記錄。適用於如果程序崩潰時，您不想遺失任何日誌條目的情況。這會讓測試執行變慢。符合 --diagnostic-synchronous-write 命令列選項。

備註

此環境變數名稱自 MTP 版本 2.3.0 起提供。舊有 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 網域 socket 檔案時所使用的目錄。當沙盒或容器不允許在預設的暫存目錄中建立通訊端時，請使用它。 MTP 會建立並檢查該目錄，當目錄無法寫入或產生的 socket 路徑太長時，會錯誤失敗。

該變數在 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 環境變數