診斷 MSBuild 工作失敗

發行項
03/05/2024

MSB6006 當衍生類別執行工具程式時 ToolTask，如果工作未記錄更具體的錯誤，就會發出此工具進程，以傳回非零結束代碼。

識別失敗的工作

當您遇到工作錯誤時，第一個步驟是識別失敗的工作。

錯誤的文字可指出工具名稱 (ToolName 的工作實作或可執行檔的名稱所提供的易記名稱)，以及數字結束代碼。例如，在 error MSB6006: "custom tool" exited with code 1. 中，工具名稱為 custom tool，而結束代碼為 1。

若要尋找失敗的 MSBuild 工作：

在命令行組建中：如果組建設定為包含摘要（預設值），摘要看起來會像這樣：
```
Build FAILED.

"S:\MSB6006_demo\MSB6006_demo.csproj" (default target) (1) ->
(InvokeToolTask target) ->
  S:\MSB6006_demo\MSB6006_demo.csproj(19,5): error MSB6006: "custom tool" exited with code 1.
```
此結果表示在專案 S:\MSB6006_demo\MSB6006_demo.csproj 中名為 InvokeToolTask 的目標中，於檔案 S:\MSB6006_demo\MSB6006_demo.csproj 的第 19 行所定義的工作中發生錯誤。
Visual Studio UI：Visual Studio 錯誤清單的 Project、File 和 Line 欄位中提供了相同的資訊。

尋找更多失敗資訊

當工作未記錄特定錯誤時，就會發出錯誤MSB6006。記錄錯誤的失敗通常是因為工作未設定為瞭解所呼叫工具發出的錯誤格式。

表現良好的工具通常會將某些內容或錯誤資訊發出至其標準輸出或錯誤資料流程，而工作預設會擷取和記錄此資訊。在發生錯誤之前查看記錄項目，以取得其他資訊。可能需要以更高的記錄層級重新執行組建，以保留這些資訊。希望記錄中發現的其他內容或錯誤會顯示問題的根本原因。如果沒有，您可能需要通過檢查失敗工作的輸入屬性和項目，以縮小可能的原因。

注意

MSBuild 可識別特定的診斷輸出格式。此格式的詳細資料記載於 MSBuild 和 Visual Studio 的診斷訊息格式。

對工作進行偵錯

偵錯 MSBuild 工作時，以下是一些一般秘訣。

盡可能縮小重現案例的範圍（例如，藉由設定 /p:BuildProjectReferences=false 和啟動 MSBuild 與一個特定專案或一個特定目標），以較少的程式代碼使用。
使用 MSBuild 命令行選項 /m:1 ，讓單一 MSBuild 進程進行偵錯。
將環境變數 MSBUILDDEBUGONSTART 設定為 1，以在啟動時取得附加至 MSBuild 的調試程式。
在要逐步執行的工作方法上 Execute 設定斷點。

對自定義工作進行偵錯

如果您要撰寫自定義工作的程式碼，您可以藉由在工作的 Execute 方法中新增呼叫來叫用調試程式，讓偵錯變得更容易。您可以使用環境變數檢查來隔離該程式代碼，如此一來，當使用者設定該環境變數時，工作就會停止，並讓使用者有機會進行偵錯。您可以使用 System.Diagnostics.Debugger.Launch 或 System.Diagnostics.Debugger.Break 在調試程式中啟動或中斷。

您應該務必在自定義工作中盡可能新增記錄，讓使用者更輕鬆地進行偵錯。當您最終找出失敗的根本案例時，這很重要;新增足夠的記錄程式代碼，以偵測並報告未來的失敗模式。

請考慮使用 xUnit 為工作設定測試環境。請參閱使用 dotnet test 和 xUnit 在 .NET Core 中對 C# 進行單元測試。您可以將 xUnit 測試設定為使用 MSBuild API，以程式設計方式使用模擬項目檔叫用 MSBuild，其中包含執行有問題的工作所需的屬性、專案和目標。在某些情況下，建立模擬組建引擎可能很合理。您可以在使用 Visual Studio 對自訂 MSBuild 工作進行單元測試時看到範例。

在 .NET SDK 專案中，您也可以修改 launch 設定.json 新增特殊的偵錯配置檔，此配置檔會搭配本文稍早所述的命令行自變數和環境變數來執行MSBuild.exe。

"profiles": {
  "Debug Build": {
    "commandName": "Executable",
    "executablePath": "$(MSBuildBinPath)\\MSBuild.exe",
    "commandLineArgs": "/p:Configuration=$(Configuration) $(ProjectFileName) /m:1",
    "workingDirectory": "$(ProjectDir)"
  }
}

如果您要在執行時間提示附加自己的除錯程式，請將環境變數 MSBUILDDEBUGONSTART 設定為 2。當您使用不同的調試程式時，這非常有用，例如在無法使用 Visual Studio 時，在 macOS 上。