MSBuild 命令列參考MSBuild command-line reference

在使用 MSBuild.exe 來建置專案或方案檔時,您可以包含數個參數來指定程序的各個層面。When you use MSBuild.exe to build a project or solution file, you can include several switches to specify various aspects of the process.

每個參數都以兩種形式提供:-switch 和 /switch。Every switch is available in two forms: -switch and /switch. 本文件僅示範 -switch 形式。The documentation only shows the -switch form.

語法Syntax

MSBuild.exe [Switches] [ProjectFile]

引數Arguments

引數Argument 描述Description
ProjectFile 在所指定的專案檔中建置目標。Builds the targets in the project file that you specify. 如果您未指定專案檔,MSBuild 會搜尋目前工作目錄中結尾為 proj 的檔案名稱副檔名,並使用該檔案。If you don't specify a project file, MSBuild searches the current working directory for a file name extension that ends in proj and uses that file. 您也可以為這個引數指定 Visual Studio 方案檔。You can also specify a Visual Studio solution file for this argument.

參數Switches

參數Switch 簡短形式Short form 描述Description
-help-help /?/? 或 -hor -h 顯示使用資訊。Display usage information. 下列命令是範例:The following command is an example:

msbuild.exe -?
-detailedsummary-detailedsummary -ds-ds 在組建記錄檔結尾顯示關於所建置組態及其如何排程至節點的詳細資訊。Show detailed information at the end of the build log about the configurations that were built and how they were scheduled to nodes.
-ignoreprojectextensions: extensions-ignoreprojectextensions: extensions -ignore: extensions-ignore: extensions 決定要建置哪個專案檔後,請忽略指定的副檔名。Ignore the specified extensions when determining which project file to build. 使用分號或逗號分隔多個副檔名,如下列範例所示:Use a semicolon or a comma to separate multiple extensions, as the following example shows:

-ignoreprojectextensions:.vcproj,.sln
-maxcpucount[:number]-maxcpucount[:number] -m[:number]-m[:number] 指定要在建置時使用的並行處理最大數目。Specifies the maximum number of concurrent processes to use when building. 如果您未包含此參數,預設值為 1。If you don't include this switch, the default value is 1. 如果您包含此參數但未指定值,MSBuild 將會使用電腦上的處理器最大數目。If you include this switch without specifying a value, MSBuild will use up to the number of processors in the computer. 如需詳細資訊,請參閱同時建置多個專案For more information, see Building multiple projects in parallel.

下列範例會指示 MSBuild 使用三個 MSBuild 處理程序來建置,這可在同一時間建置三個專案:The following example instructs MSBuild to build using three MSBuild processes, which allows three projects to build at the same time:

msbuild myproject.proj -maxcpucount:3
-noautoresponse-noautoresponse -noautorsp-noautorsp 不要自動包含任何 MSBuild.rsp 檔案。Don't include any MSBuild.rsp files automatically.
-nodeReuse:value-nodeReuse:value -nr:value-nr:value 啟用或停用 MSBuild 節點的重複使用功能。Enable or disable the re-use of MSBuild nodes. 您可以指定下列值:You can specify the following values:

- True- True. 組建完成後保留節點,以便後續組建可以加以使用 (預設值)。Nodes remain after the build finishes so that subsequent builds can use them (default).
- False- False. 在組建完成後不保留節點。Nodes don't remain after the build completes.

節點對應至執行中專案。A node corresponds to a project that's executing. 如果您包含 -maxcpucount 參數,就能同時執行多個節點。If you include the -maxcpucount switch, multiple nodes can execute concurrently.
-nologo-nologo 不要顯示程式啟始資訊或著作權訊息。Don't display the startup banner or the copyright message.
-preprocess[:filepath]-preprocess[:filepath] -pp[:filepath]-pp[:filepath] 由內嵌在組建期間匯入的所有檔案,並標上其界限標記,藉此建立單一彙總的專案檔。Create a single, aggregated project file by inlining all the files that would be imported during a build, with their boundaries marked. 您可以使用此參數更輕鬆地判斷正在匯入哪些檔案、從哪裡匯入檔案,以及哪些檔案形成組建。You can use this switch to more easily determine which files are being imported, from where the files are being imported, and which files contribute to the build. 使用這個參數時,並不會建置專案。When you use this switch, the project isn't built.

如果您指定 filepath,則彙總的專案檔會是檔案的輸出。If you specify a filepath, the aggregated project file is output to the file. 否則,輸出會顯示在主控台視窗中。Otherwise, the output appears in the console window.

如需如何使用 Import 項目將專案檔插入另一個專案檔的資訊,請參閱 Import 項目 (MSBuild)如何:在多個專案檔中使用相同的目標For information about how to use the Import element to insert a project file into another project file, see Import element (MSBuild) and How to: Use the same target in multiple project files.
-property:name=value-property:name=value -p:name=value-p:name=value 設定或覆寫所指定的專案層級屬性,其中 name 是屬性名稱,而 value 是屬性值。Set or override the specified project-level properties, where name is the property name and value is the property value. 分別指定每個屬性,或使用分號或逗號分隔多個屬性,如下列範例所示:Specify each property separately, or use a semicolon or comma to separate multiple properties, as the following example shows:

-property:WarningLevel=2;OutDir=bin\Debug
-restore-restore -r-r 在建置實際目標前執行 Restore 目標。Runs the Restore target prior to building the actual targets.
-target:targets-target:targets -t:targets-t:targets 在專案中建置指定的目標。Build the specified targets in the project. 分別指定每個目標,或使用分號或逗號分隔多個目標,如下列範例所示:Specify each target separately, or use a semicolon or comma to separate multiple targets, as the following example shows:

-target:PrepareResources;Compile

如果您使用這個參數指定任何目標,便會執行這些目標,而不是專案檔中 DefaultTargets 屬性的任何目標。If you specify any targets by using this switch, they are run instead of any targets in the DefaultTargets attribute in the project file. 如需詳細資訊,請參閱目標建置順序如何:指定要優先建置的目標For more information, see Target build order and How to: Specify which target to build first.

目標是一組工作。A target is a group of tasks. 如需詳細資訊,請參閱目標For more information, see Targets.
-toolsversion:version-toolsversion:version -tv:version-tv:version 指定用來建置專案的工具組版本,如下列範例所示:-toolsversion:3.5Specifies the version of the Toolset to use to build the project, as the following example shows: -toolsversion:3.5

使用此參數,即可建置專案,並指定有別於 Project 項目 (MSBuild) 中所指定的版本。By using this switch, you can build a project and specify a version that differs from the version that's specified in the Project element (MSBuild). 如需詳細資訊,請參閱覆寫 ToolsVersion 設定For more information, see Overriding ToolsVersion settings.

針對 MSBuild 4.5,您可以為 version 指定下列值:2.0、3.5 和 4.0。For MSBuild 4.5, you can specify the following values for version: 2.0, 3.5, and 4.0. 如果您指定 4.0,則 VisualStudioVersion 組建屬性會指定要使用哪個子工具組。If you specify 4.0, the VisualStudioVersion build property specifies which sub-toolset to use. 如需詳細資訊,請參閱工具組 (ToolsVersion) 的<子工具組>一節。For more information, see the Sub-toolsets section of Toolset (ToolsVersion).

工具組包含用於建置應用程式的工作、目標和工具。A Toolset consists of tasks, targets, and tools that are used to build an application. 工具包括編譯器,例如 csc.exe 和 vbc.exe。The tools include compilers such as csc.exe and vbc.exe. 如需工具組的詳細資訊,請參閱工具組 (ToolsVersion)標準和自訂工具組的組態多目標For more information about Toolsets, see Toolset (ToolsVersion), Standard and custom toolset configurations, and Multitargeting. 注意: 工具組版本與目標架構的版本不同,它是在其上建置專案來執行的 .NET Framework 版本。Note: The toolset version isn't the same as the target framework, which is the version of the .NET Framework on which a project is built to run. 如需詳細資訊,請參閱目標架構和目標平台For more information, see Target framework and target platform.
-validate:[schema]-validate:[schema] -val[schema]-val[schema] 驗證專案檔,如果驗證成功,則會建置專案。Validate the project file and, if validation succeeds, build the project.

如果您沒有指定 schema,專案會針對預設結構描述進行驗證。If you don't specify schema, the project is validated against the default schema.

如果您指定 schema,專案會針對您指定的結構描述進行驗證。If you specify schema, the project is validated against the schema that you specify.

下列設定為範例:-validate:MyExtendedBuildSchema.xsdThe following setting is an example: -validate:MyExtendedBuildSchema.xsd
-verbosity:level-verbosity:level -v:level-v:level 指定要在組建記錄檔中顯示的資訊量。Specifies the amount of information to display in the build log. 每個記錄器都會顯示根據您為該記錄器所設詳細資訊層級的事件。Each logger displays events based on the verbosity level that you set for that logger.

您可以指定下列詳細資訊層級:q[uiet]m[inimal]n[ormal]d[etailed]diag[nostic]You can specify the following verbosity levels: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic].

下列設定為範例:-verbosity:quietThe following setting is an example: -verbosity:quiet
-version-version -ver-ver 只顯示版本資訊。Display version information only. 不會建置專案。The project isn't built.
@file 從文字檔中插入命令列參數。Insert command-line switches from a text file. 如果您有多個檔案,請個別指定。If you have multiple files, you specify them separately. 如需詳細資訊,請參閱回應檔For more information, see Response files.

記錄器的參數Switches for loggers

參數Switch 簡短形式Short form 描述Description
-consoleloggerparameters:-consoleloggerparameters:

parameters
-clp:parameters-clp:parameters 將您所指定的參數傳遞至主控台記錄器,其會在主控台視窗中顯示組建資訊。Pass the parameters that you specify to the console logger, which displays build information in the console window. 您可以指定下列參數:You can specify the following parameters:

- PerformanceSummary- PerformanceSummary. 顯示工作、目標及專案所花費的時間。Show the time that's spent in tasks, targets, and projects.
- Summary- Summary. 在結尾顯示錯誤和警告摘要。Show the error and warning summary at the end.
- NoSummary- NoSummary. 不要在結尾顯示錯誤和警告摘要。Don't show the error and warning summary at the end.
- ErrorsOnly- ErrorsOnly. 僅顯示錯誤。Show only errors.
- WarningsOnly- WarningsOnly. 僅顯示警告。Show only warnings.
- NoItemAndPropertyList- NoItemAndPropertyList. 如果詳細資訊層級設為 diagnostic,不要在每個專案組件開頭顯示項目和屬性的清單。Don't show the list of items and properties that would appear at the start of each project build if the verbosity level is set to diagnostic.
- ShowCommandLine- ShowCommandLine. 顯示 TaskCommandLineEvent 訊息。Show TaskCommandLineEvent messages.
- ShowTimestamp- ShowTimestamp. 顯示時間戳記做為任何訊息的前置詞。Show the timestamp as a prefix to any message.
- ShowEventId- ShowEventId. 顯示每個已啟動事件、已完成事件及訊息的事件識別碼。Show the event ID for each started event, finished event, and message.
- ForceNoAlign- ForceNoAlign. 不要讓文字對齊主控台緩衝區的大小。Don't align the text to the size of the console buffer.
- DisableConsoleColor- DisableConsoleColor. 對所有記錄訊息使用預設的主控台色彩。Use the default console colors for all logging messages.
- DisableMPLogging- DisableMPLogging. 在非多處理器模式中執行時,停用多處理器的輸出記錄樣式。Disable the multiprocessor logging style of output when running in non-multiprocessor mode.
- EnableMPLogging- EnableMPLogging. 即使在非多處理器模式中執行時也啟用多記錄器記錄樣式。Enable the multiprocessor logging style even when running in non-multiprocessor mode. 這個記錄樣式預設為開啟。This logging style is on by default.
- Verbosity- Verbosity. 覆寫此記錄器的 -verbosity 設定。Override the -verbosity setting for this logger.

請使用分號來分隔多個參數,如下列範例所示:Use a semicolon to separate multiple parameters, as the following example shows:

-consoleloggerparameters:PerformanceSummary;NoSummary -verbosity:minimal
-distributedFileLogger-distributedFileLogger -dfl-dfl 將每個 MSBuild 節點的組建輸出記錄到自己的檔案。Log the build output of each MSBuild node to its own file. 這些檔案的初始位置是目前的目錄。The initial location for these files is the current directory. 根據預設,系統會將檔案命名為 MSBuild<NodeId>.logBy default, the files are named MSBuild<NodeId>.log. 您可以使用 -fileLoggerParameters 參數,指定檔案位置及 fileLogger 的其他參數。You can use the -fileLoggerParameters switch to specify the location of the files and other parameters for the fileLogger.

如果您使用 -fileLoggerParameters 參數為記錄檔命名,分散式記錄器便會使用該名稱作為範本,並在為每個節點建立記錄檔時,將節點識別碼附加至該名稱。If you name a log file by using the -fileLoggerParameters switch, the distributed logger will use that name as a template and append the node ID to that name when creating a log file for each node.
-distributedlogger:-distributedlogger:

central logger*

forwarding logger
-dl:central logger*forwarding logger-dl:central logger*forwarding logger 從 MSBuild 記錄事件,將不同的記錄器執行個體附加至每個節點。Log events from MSBuild, attaching a different logger instance to each node. 若要指定多個記錄器,請分別指定每個記錄器。To specify multiple loggers, specify each logger separately.

您可以使用記錄器語法來指定記錄器。You use the logger syntax to specify a logger. 如需記錄器語法,請參閱下列 -logger 參數。For the logger syntax, see the -logger switch below.

下列範例顯示如何使用此參數:The following examples show how to use this switch:

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

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

[number][number]
-fl[number]-fl[number] 在目前目錄中將組建輸出記錄至單一檔案。Log the build output to a single file in the current directory. 如果您未指定 number,輸出檔案就會命名為 msbuild.logIf you don't specify number, the output file is named msbuild.log. 如果您指定 number,則輸出檔案會命名為 msbuild<n>.log,其中 <n> 是 numberIf you specify number, the output file is named msbuild<n>.log, where <n> is number. Number 可以是從 1 到 9 的數字。Number can be a digit from 1 to 9.

您可以使用 -fileLoggerParameters 參數,指定檔案位置及 fileLogger 的其他參數。You can use the -fileLoggerParameters switch to specify the location of the file and other parameters for the fileLogger.
-fileloggerparameters:[number]-fileloggerparameters:[number]

parameters
-flp:[ number] parameters-flp:[ number] parameters 指定檔案記錄器和分散式檔案記錄器的任何額外參數。Specifies any extra parameters for the file logger and the distributed file logger. 這個參數的存在表示對應的 -filelogger[ number ] 參數已存在。The presence of this switch implies that the corresponding -filelogger[number] switch is present. Number 可以是從 1 到 9 的數字。Number can be a digit from 1 to 9.

您可以使用針對 -consoleloggerparameters 列出的所有參數。You can use all parameters that are listed for -consoleloggerparameters. 您也可以使用一個或多個下列參數:You can also use one or more of the following parameters:

- LogFile- LogFile. 要寫入組建記錄檔的記錄檔路徑。The path to the log file into which the build log is written. 分散式檔案記錄器會在這個路徑放上其記錄檔名稱做為前置詞。The distributed file logger prefixes this path to the names of its log files.
- Append- Append. 決定是否要將組建記錄檔附加到記錄檔,或者加以覆寫。Determines whether the build log is appended to the log file or overwrites it. 在設定這個參數時,會將組建記錄檔附加至記錄檔。When you set the switch, the build log is appended to the log file. 若這個參數不存在,則會覆寫現有記錄檔的內容。When the switch is not present, the contents of an existing log file are overwritten.
如果您包含該附加參數,則無論是否設定為 True 或 False,都會附加記錄。If you include the append switch, no matter whether it is set to true or false, the log is appended. 如果您沒有包含該附加參數,則會覆寫記錄。If you do not include the append switch, the log is overwritten.
在此情況下會覆寫檔案:msbuild myfile.proj -l:FileLogger,Microsoft.Build;logfile=MyLog.logIn this case the file is overwritten: msbuild myfile.proj -l:FileLogger,Microsoft.Build;logfile=MyLog.log
在此情況下會附加檔案:msbuild myfile.proj -l:FileLogger,Microsoft.Build;logfile=MyLog.log;append=trueIn this case the file is appended: msbuild myfile.proj -l:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true
在此情況下會附加檔案:msbuild myfile.proj -l:FileLogger,Microsoft.Build;logfile=MyLog.log;append=falseIn this case the file is appended: msbuild myfile.proj -l:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false
- Encoding- Encoding. 指定檔案的編碼 (例如,UTF-8、Unicode 或 ASCII)。Specifies the encoding for the file (for example, UTF-8, Unicode, or ASCII).

下列範例會為警告與錯誤產生個別的記錄檔:The following example generates separate log files for warnings and errors:

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

下列範例會顯示其他可能性:The following examples show other possibilities:

-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
-binaryLogger[:[LogFile=]output.binlog[;ProjectImports=[None,Embed,ZipFile]]]-binaryLogger[:[LogFile=]output.binlog[;ProjectImports=[None,Embed,ZipFile]]] -bl-bl 將所有建置事件序列化為壓縮的二進位檔案。Serializes all build events to a compressed binary file. 根據預設,檔案位於目前目錄中,並命名為 msbuild.binlogBy default the file is in the current directory and named msbuild.binlog. 二進位記錄是建置程序的詳細描述,稍後可用來重構文字記錄並供其他分析工具所使用。The binary log is a detailed description of the build process that can later be used to reconstruct text logs and used by other analysis tools. 二進位記錄通常是 10-20x 小於最詳細的文字診斷層級記錄,但包含詳細資訊。A binary log is usually 10-20x smaller than the most detailed text diagnostic-level log, but it contains more information.

二進位記錄器預設會收集專案檔的來源文字,包含在建置期間發生的所有已匯入的專案和目標檔案。The binary logger by default collects the source text of project files, including all imported projects and target files encountered during the build. 選擇性 ProjectImports 參數控制此行為:The optional ProjectImports switch controls this behavior:

- ProjectImports=None.- ProjectImports=None. 不收集專案匯入。Don't collect the project imports.
- ProjectImports=Embed.- ProjectImports=Embed. 在記錄檔中內嵌專案匯入 (預設值)。Embed project imports in the log file (default).
- ProjectImports=ZipFile.- ProjectImports=ZipFile. 將專案檔儲存至 <輸出>.projectimports.zip其中,<> 與二進位記錄檔名稱同名。Save project files to <output>.projectimports.zip where <output> is the same name as the binary log file name.

ProjectImports 的預設設定為 Embed。The default setting for ProjectImports is Embed.
注意:記錄器不會收集非 MSBuild 原始程式檔,例如 .cs.cpp 等。Note: the logger does not collect non-MSBuild source files such as .cs, .cpp etc.
「播放」 .binlog 檔案的方式是將它傳遞至 msbuild.exe 作為引數,而不是專案/方案。A .binlog file can be "played back" by passing it to msbuild.exe as an argument instead of a project/solution. 其他記錄器將會收到記錄檔中所包含的資訊,就像發生原始組建一樣。Other loggers will receive the information contained in the log file as if the original build was happening. 您可以閱讀更多有關二進位記錄檔及其使用方式, 網址為: https://github.com/Microsoft/msbuild/wiki/Binary-LogYou can read more about the binary log and its usages at: https://github.com/Microsoft/msbuild/wiki/Binary-Log

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

logger
-l:logger-l:logger 從 MSBuild 指定要用於記錄事件的記錄器。Specifies the logger to use to log events from MSBuild. 若要指定多個記錄器,請分別指定每個記錄器。To specify multiple loggers, specify each logger separately.

針對 logger 使用下列語法:[``LoggerClass``,]``LoggerAssembly``[;``LoggerParameters``]Use the following syntax for logger: [``LoggerClass``,]``LoggerAssembly``[;``LoggerParameters``]

針對 LoggerClass 使用下列語法:[``PartialOrFullNamespace``.]``LoggerClassNameUse the following syntax for LoggerClass: [``PartialOrFullNamespace``.]``LoggerClassName

如果組件恰好包含一個記錄器,就不必指定記錄器類別。You don't have to specify the logger class if the assembly contains exactly one logger.

針對 LoggerAssembly 使用下列語法:{``AssemblyName``[,``StrongName``] &#124; AssemblyFile``}Use the following syntax for LoggerAssembly: {``AssemblyName``[,``StrongName``] &#124; AssemblyFile``}

記錄器參數是選擇性,只有在輸入時才會傳遞至記錄器。Logger parameters are optional and are passed to the logger exactly as you enter them.

下列範例會使用 -logger 參數。The following examples use the -logger switch.

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

-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML
-noconsolelogger-noconsolelogger -noconlog-noconlog 停用預設主控台記錄器,而且不將事件記錄至主控台。Disable the default console logger, and don't log events to the console.

範例Example

下列範例會建置 rebuild 專案的 MyProject.proj 目標。The following example builds the rebuild target of the MyProject.proj project.

MSBuild.exe MyProject.proj -t:rebuild

範例Example

您可以使用 MSBuild.exe 來執行更複雜的組建。You can use MSBuild.exe to perform more complex builds. 例如,您可以用來在方案中建置特定專案的特定目標。For example, you can use it to build specific targets of specific projects in a solution. 下列範例會重建 NotInSolutionFolder 專案並清除 InSolutionFolder 專案,這會位於 NewFolder 方案資料夾中。The following example rebuilds the project NotInSolutionFolder and cleans the project InSolutionFolder, which is in the NewFolder solution folder.

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

另請參閱See also