MSBuild 命令列參考

  • 發行項

在使用 MSBuild.exe 來建置專案或方案檔時，您可以包含數個參數來指定程序的各個層面。

每個參數都以兩種形式提供：-switch 和 /switch。 本文件僅示範 -switch 形式。 參數不會區分大小寫。 如果從 Windows 命令提示字元以外的 shell 執行 MSBuild，則切換的引數清單 (用分號或逗號分隔) 可能需要單引號或雙引號，以確保清單傳遞給 MSBuild 而不是由 shell 進行解釋。

語法

MSBuild.exe [Switches] [ProjectFile]

引數

Argument 描述
ProjectFile 在所指定的專案檔中建置目標。 如果您未指定專案檔，MSBuild 會搜尋目前工作目錄中結尾為 proj 的檔案名稱副檔名，並使用該檔案。 您也可以為這個引數指定 Visual Studio 方案檔。

交換器

Switch 簡短形式 描述
-detailedSummary[:True 或 False] -ds[:True 或 False] 如果 True，在組建記錄檔結尾顯示關於所建置組態及其如何排程至節點的詳細資訊。
-getItem：itemName,... 在評估之後寫出專案或專案的值，而不執行建置，或者 -targets 如果使用 選項或 -getTargetResult 選項，請在建置之後寫出值。
-getProperty：propertyName,... 在評估之後寫出屬性或屬性的值，而不執行建置，或者 -targets 如果使用選項或 -getTargetResult 選項，請在建置之後寫出值。
-getTargetResult：targetName,... 寫出指定目標的輸出值。
-graphBuild[:True 或 False] -graph[:True 或 False] 導致 MSBuild 建構並產生專案圖表。 建構圖表需要識別專案參考以形成相依性。 建置該圖表需要嘗試建置專案參考 (在可參考它們的專案之前)，這與傳統 MSBuild 排程不同。 需要 MSBuild 16 或更新版本。
-help /? 或 -h 顯示使用資訊。 下列命令是範例：

msbuild.exe -?
-ignoreProjectExtensions：extensions -ignore: extensions 決定要建置哪個專案檔後，請忽略指定的副檔名。 使用分號或逗號分隔多個副檔名，如下列範例所示：

-ignoreprojectextensions:.vcproj,.sln
-inputResultsCaches[：cacheFile[;cacheFile2] -irc[:cacheFile[;cacheFile2] MSBuild 將從中讀取建置結果的輸入快取檔案之分號分隔清單。 如果 -isolateProjects 設定為 False，則此將其設定為 True。
-interactive[:True 或 False] - 指示允許建置中的動作與使用者互動。 請勿在不需要互動的自動化案例中使用這個自變數。 指定 interactive 與指定 -interactive:true 相同。 使用參數可以覆寫來自回應檔的值。
-isolateProjects[:True 或 MessageUponIsolationViolation 或 False] -isolate[:True 或 MessageUponIsolationViolation 或 False] 導致 MSBuild 分開建置每個專案。 當設定為 MessageUponIsolationViolation (或其簡短形式 Message) 時，如果提供了 -outputResultsCache 切換，則僅序列化頂層目標的結果。 此選項是降低相依性專案中發生隔離違規目標的機會，因為其相依於快取目標的相依性不會考慮其副作用。 （例如，屬性的定義。此模式比較嚴格，因為它需要在評估階段以靜態方式探索專案圖形，但在建置一組大型專案時可以改善排程並減少記憶體負荷。
-lowPriority[:True 或 False] -low[:True 或 False] 導致 MSBuild 以低流程優先順序執行。 指定 -lowPriority 等同於指定 -lowPriority:True。
-maxCpuCount[:number] -m[:number] 指定要在建置時使用的並行處理最大數目。 如果您未包含此參數，預設值為 1。 如果您在未指定值的情況下包含此參數，MSBuild 最多會用到電腦中的處理器數目。 如需詳細資訊，請參閱同時建置多個專案。

下列範例會指示 MSBuild 使用三個 MSBuild 處理程序來建置，這可在同一時間建置三個專案：

msbuild myproject.proj -maxcpucount:3
-noAutoResponse -noautorsp 請勿自動包含任何 MSBuild.rsp 或 Directory.Build.rsp 檔案。
-nodeReuse:value -nr:value 啟用或停用 MSBuild 節點的重複使用。 您可以指定下列值：

- True。 組建完成後保留節點，以便後續組建可以加以使用 (預設值)。
- False。 在組建完成後不保留節點。

節點對應至執行中專案。 如果您包含 -maxcpucount 參數，就能同時執行多個節點。
-nologo 不要顯示程式啟始資訊或著作權訊息。
-preprocess[:filepath] -pp[:filepath] 由內嵌在組建期間匯入的所有檔案，並標上其界限標記，藉此建立單一彙總的專案檔。 您可以使用此參數更輕鬆地判斷正在匯入哪些檔案、從哪裡匯入檔案，以及哪些檔案形成組建。 使用這個參數時，並不會建置專案。

如果您指定 filepath，則彙總的專案檔會是檔案的輸出。 否則，輸出會顯示在主控台視窗中。

如需如何使用 Import 項目來將專案檔插入另一個專案檔的資訊，請參閱 Import 項目 (MSBuild) 和如何：在多個專案檔中使用相同的目標。
-outputResultsCache[:cacheFile] -orc[:cacheFile] MSBuild 會在組建結尾寫入其組建結果快取內容的輸出快取檔案。 如果 -isolateProjects 設定為 False，則此將其設定為 True。
-profileEvaluation：<file> - 設定 MSBuild 評估，並將結果寫入指定檔案。 如果指定檔案的副檔名為「.md」，則會以 Markdown 格式產生結果。 否則，將產生定位字元分隔檔案。
-property:name=value -p:name=value 設定或覆寫所指定的專案層級屬性，其中 name 是屬性名稱，而 value 是屬性值。 分別指定每個屬性，或使用分號或逗號分隔多個屬性，如下列範例所示：

-property:WarningLevel=2;OutDir=bin\Debug
-restore -r 在建置實際目標前執行 Restore 目標。
-restoreProperty:name=value -rp：name=value 只在還原期間設定或覆寫這些專案層級屬性，而且不會使用與 -property 自變數一起指定的屬性。 name 是屬性名稱，value 是屬性值。 使用分號或逗號分隔多個屬性，或者分別指定每個屬性。
-target:targets -t:targets 在專案中建置指定的目標。 分別指定每個目標，或使用分號或逗號分隔多個目標，如下列範例所示：

-target:PrepareResources;Compile

如果您使用此參數指定任何目標，則會執行它們，而不是項目檔中 屬性中的任何 DefaultTargets 目標。 如需詳細資訊，請參閱目標建置順序和如何：指定要優先建置的目標。

目標是一組工作。 如需詳細資訊，請參閱目標。
-targets[:file] -ts[:file] 將可用目標的清單寫入指定檔案 (如果未指定檔案，則寫入輸出裝置)，而無需實際執行建置流程。
-toolsVersion：version -tv:version 指定自訂工具組。 工具組包含用於建置應用程式的工作、目標和工具。 請參閱工具組 (ToolsVersion) 及標準和自訂工具組的組態。
-validate:[schema] -val[schema] 驗證專案檔，如果驗證成功，則會建置專案。

如果您沒有指定 schema，專案會針對預設結構描述進行驗證。

如果您指定 schema，專案會針對您指定的結構描述進行驗證。

下列設定為範例：-validate:MyExtendedBuildSchema.xsd
-verbosity:level -v:level 指定要在組建記錄檔中顯示的資訊量。 每個記錄器都會顯示根據您為該記錄器所設詳細資訊層級的事件。

您可以指定下列詳細程度層級：q[uiet]、m[inimal]、n[ormal] (預設)、d[etailed] 及 diag[nostic]。

下列設定為範例：-verbosity:quiet
-version ver - 只顯示版本資訊。 不會建置專案。
@file 從文字檔中插入命令列參數。 如果您有多個檔案，請個別指定。 如需詳細資訊，請參閱回應檔。
-warnAsError[:code[;code2] -err[:code[;code2] 要視為錯誤的警告程式碼清單。 使用分號或逗號分隔多個警告程式碼。 若要將所有警告視為錯誤，請使用不帶值的切換。 當警告視為錯誤時，目標會繼續執行，就像是警告一樣，但整體組建會失敗。

範例: -err:MSB4130
-warnNotAsError[:code[;code2] -noerr[:code[;code2] 不應升階為錯誤的警告碼清單。 具體來說，如果 warnAsError 參數設定為將所有警告升階為錯誤，則不會升級以 warnNotAsError 指定的錯誤碼。 如果 warnAsError 未設定為將所有警告升階為錯誤，則不會有任何作用。 使用分號或逗號分隔多個警告程式碼。

範例: -noerr:MSB4130
-warnAsMessage[:code[;code2] -noWarn[:code[;code2] 要視為低重要性訊息的警告程式碼清單。 使用分號或逗號分隔多個警告程式碼。

範例: -noWarn:MSB3026

記錄器的參數

Switch 簡短形式 描述
-binaryLogger[:[LogFile=]output.binlog
[;ProjectImports=[None,Embed,ZipFile]]]		 -bl 將所有建置事件序列化為壓縮的二進位檔案。 根據預設，檔案位於目前目錄中，並命名為 msbuild.binlog。 二進位記錄是建置程序的詳細描述，稍後可用來重構文字記錄並供其他分析工具所使用。 二進位記錄通常是 10-20x 小於最詳細的文字診斷層級記錄，但包含詳細資訊。

二進位記錄器預設會收集專案檔的來源文字，包含在建置期間發生的所有已匯入的專案和目標檔案。 選擇性 ProjectImports 參數控制此行為：

- ProjectImports=None. 不收集專案匯入。
- ProjectImports=Embed. 在記錄檔中內嵌專案匯入 (預設值)。
- ProjectImports=ZipFile. 將專案檔儲存至 <output>.projectimports.zip，其中 <output> 與二進位記錄檔名稱相同。

ProjectImports 的預設設定為 Embed。
注意：記錄器不會收集非 MSBuild 來源檔案，例如 .cs、 .cpp 等。
「播放」.binlog 檔案的方式是將它傳遞至 msbuild.exe 作為引數，而不是專案/方案。 其他記錄器會接收記錄檔中包含的資訊，就像原始組建發生一樣。 您可以閱讀更多有關二進位記錄檔及其使用方式，　網址為：https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md

範例：
- -bl
- -bl:output.binlog
- -bl:output.binlog;ProjectImports=None
- -bl:output.binlog;ProjectImports=ZipFile
- -bl:..\..\custom.binlog
- -binaryLogger
-consoleLoggerParameters：

parameters		 -clp:parameters 將您所指定的參數傳遞至主控台記錄器，其會在主控台視窗中顯示組建資訊。 您可以指定下列參數：

- PerformanceSummary。 顯示工作、目標及專案所花費的時間。
- 摘要。 在結尾顯示錯誤和警告摘要。
- NoSummary。 不要在結尾顯示錯誤和警告摘要。
- ErrorsOnly。 僅顯示錯誤。
- WarningsOnly。 僅顯示警告。
- NoItemAndPropertyList。 如果詳細資訊層級設為 diagnostic，不要在每個專案組件開頭顯示項目和屬性的清單。
- ShowCommandLine。 顯示 TaskCommandLineEvent 訊息。
- ShowProjectFile。 在診斷訊息中顯示專案檔的路徑。 此設定預設為開啟。
- ShowTimestamp。 顯示時間戳記做為任何訊息的前置詞。
- ShowEventId。 顯示每個已啟動事件、已完成事件及訊息的事件識別碼。
- ForceNoAlign。 不要讓文字對齊主控台緩衝區的大小。
- DisableConsoleColor。 對所有記錄訊息使用預設的主控台色彩。
- DisableMPLogging。 在非多處理器模式中執行時，停用多處理器的輸出記錄樣式。
- EnableMPLogging。 即使在非多處理器模式中執行時也啟用多記錄器記錄樣式。 這個記錄樣式預設為開啟。
- ForceConsoleColor。 即使主控台不支援，也請使用 ANSI 控制台色彩。
- Verbosity。 覆寫此記錄器的 -verbosity 設定。

使用分號分隔多個參數，如下列範例所示：

-consoleloggerparameters:PerformanceSummary;NoSummary -verbosity:minimal

預設的主控台記錄器具有正常的詳細程度，並包括 Summary。
-distributedFileLogger -dfl 將每個 MSBuild 節點的組建輸出記錄到自己的檔案。 這些檔案的初始位置是目前的目錄。 根據預設，系統會將檔案命名為 MSBuild<NodeId>.log。 您可以使用 -fileLoggerParameters 參數，指定檔案位置及 fileLogger 的其他參數。

如果您使用 -fileLoggerParameters 參數命名記錄檔，分散式記錄器會使用該名稱做為範本，並在為每個節點建立記錄檔時，將該節點標識符附加至該名稱。
-distributedLogger：

central logger

forwarding logger		 -dl:central loggerforwarding logger 從 MSBuild 記錄事件，將不同的記錄器執行個體附加至每個節點。 若要指定多個記錄器，請分別指定每個記錄器。

您可以使用記錄器語法來指定記錄器。 如需記錄器語法，請參閱 -logger 參數。

下列範例顯示如何使用此參數：

-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral

-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll
-fileLogger

[number]		 -fl[number] 在目前目錄中將組建輸出記錄至單一檔案。 如果您未指定 number，輸出檔案就會命名為 msbuild.log。 如果您指定 number，則輸出檔案會命名為 msbuild<n>.log，其中 <n> 是 number。 Number 可以是從 1 到 9 的數字。

您可以使用 -fileLoggerParameters 參數，指定檔案位置及 fileLogger 的其他參數。
-fileLoggerParameters[number]：

parameters		 -flp[ number]：parameters 指定檔案記錄器和分散式檔案記錄器的任何額外參數。 這個參數的存在表示對應的 -filelogger[number] 參數已存在。 Number 可以是從 1 到 9 的數字。

您可以使用針對 -consoleloggerparameters 列出的所有參數。 您也可以使用一個或多個下列參數：

- LogFile。 要寫入組建記錄檔的記錄檔路徑。 分散式檔案記錄器會在這個路徑放上其記錄檔名稱做為前置詞。
- Append。 決定是否要將組建記錄檔附加到記錄檔，或者加以覆寫。 在設定這個參數時，會將組建記錄檔附加至記錄檔。 當參數不存在時，會覆寫現有記錄檔的內容。
範例: msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append
如果包含明確 true 或 false 設定，則無論設定如何，都會附加記錄。 如果您沒有包含附加參數，則會覆寫記錄檔。
在此情況下，會覆寫檔案： msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log
在此情況下，檔案會附加： msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true
在此情況下，檔案會附加： msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false
- Encoding。 指定檔案的編碼 (例如，UTF-8、Unicode 或 ASCII)。

下列範例會為警告與錯誤產生個別的記錄檔：

-flp1:logfile=errors.txt;errorsonly -flp2:logfile=warnings.txt;warningsonly

下列範例會顯示其他可能性：

-fileLoggerParameters:LogFile=MyLog.log;Append; Verbosity=diagnostic;Encoding=UTF-8

-flp:Summary;Verbosity=minimal;LogFile=msbuild.sum

-flp1:warningsonly;logfile=msbuild.wrn

-flp2:errorsonly;logfile=msbuild.err
-logger:

logger		 -l:logger 從 MSBuild 指定要用於記錄事件的記錄器。 若要指定多個記錄器，請分別指定每個記錄器。

針對 logger 使用下列語法：[``LoggerClass``,]``LoggerAssembly``[;``LoggerParameters``]

針對 LoggerClass 使用下列語法：[``PartialOrFullNamespace``.]``LoggerClassName

如果組件恰好包含一個記錄器，就不必指定記錄器類別。

針對 LoggerAssembly 使用下列語法：{``AssemblyName``[,``StrongName``] &#124;AssemblyFile``}

記錄器參數是選擇性，只有在輸入時才會傳遞至記錄器。

下列範例會使用 -logger 參數。

-logger:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral

-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML
-noConsoleLogger -noconlog 停用預設主控台記錄器，而且不將事件記錄至主控台。
-terminalLogger[：auto，on，off] -tl[：auto，on，off] 啟用或停用 終端機記錄器。 終端機記錄器會即時在控制臺上提供增強的建置輸出，依專案以邏輯方式組織，並設計來醒目提示可採取動作的資訊。 只有在標準輸出未重新導向時，才指定 auto （或使用不含自變數的選項）來使用終端機記錄器。 請勿剖析輸出，或依賴其在未來版本中維持不變。 此選項適用於 MSBuild 17.8 和更新版本。

範例 1

下列範例會建置 rebuild 專案的 MyProject.proj 目標。

MSBuild.exe MyProject.proj -t:rebuild

範例 2

您可以使用 MSBuild.exe 來執行更複雜的組建。 例如，您可以用來在方案中建置特定專案的特定目標。 下列範例會重建 NotInSolutionFolder 專案並清除 InSolutionFolder 專案，這會位於 NewFolder 方案資料夾中。

msbuild SlnFolders.sln -t:NotInSolutionfolder:Rebuild;NewFolder\InSolutionFolder:Clean

另請參閱