MSBuild 命令行参考
使用 MSBuild.exe 生成项目或解决方案文件时，可以包含多个开关来指定流程的各个方面。
每个开关都以两种形式提供：-switch 和 /switch。 文档仅显示 -switch 窗体。 开关不区分大小写。 如果从 Windows 命令提示符以外的 shell 运行 MSBuild，则开关（用分号或逗号分隔）的参数列表可能需要单引号或双引号，以确保列表传递到 MSBuild，而不是由 shell 解释。
.NET CLI 命令 dotnet build，dotnet publish，dotnet msbuild 和相关命令将这些开关传递给 MSBuild，因此，使用这些命令时，此引用适用;但是，dotnet run 没有。
语法
MSBuild.exe [Switches] [ProjectFile]
参数
| 论点 | 描述 |
|---|---|
ProjectFile |
在指定的项目文件中生成目标。 如果未指定项目文件，MSBuild 将在当前工作目录中搜索以 proj 结尾的文件扩展名，并使用该文件。 还可以为此参数指定 Visual Studio 解决方案文件。 |
开关
下表中的第一列显示了每个开关的长短形式。 这两种形式都是等效的。
方括号 [] 指示可选部分，大括号 {}表示用户提供的值。
| 开关 | 描述 |
|---|---|
-detailedSummary[:{True or False}]-ds[:{True or False}] |
如果 True，请在生成日志末尾显示有关生成的配置及其计划到节点的详细信息。 |
-getItem:{itemName,...} |
在评估后写出项或项的值，而不执行生成，或者如果使用 -targets 选项或 -getTargetResult 选项，请在生成后写出值。 |
-getProperty:{propertyName,...} |
在计算后写出属性或属性的值，而不执行生成，或者如果使用 -targets 选项或 -getTargetResult 选项，请在生成后写出值。 |
-getTargetResult:{targetName,...} |
写出指定目标的输出值。 |
-graphBuild[:{True or False}]-graph[:{True or False}] |
导致 MSBuild 构造和生成项目图。 构造图形涉及标识对表单依赖项的项目引用。 生成该图涉及尝试在引用它们的项目之前生成项目引用，这不同于传统的 MSBuild 计划。 需要 MSBuild 16 或更高版本。 |
-help/? 或 -h |
显示使用情况信息。 以下命令是一个示例：msbuild.exe -? |
-ignoreProjectExtensions: {extensions}-ignore: {extensions} |
确定要生成的项目文件时，请忽略指定的扩展。 使用分号或逗号分隔多个扩展，如以下示例所示：-ignoreprojectextensions:.vcproj,.sln |
-inputResultsCaches[:{cacheFile; ...}]-irc[:{cacheFile; ...}] |
MSBuild 将从中读取生成结果的输入缓存文件的分号分隔列表。 如果 -isolateProjects 设置为 False，则会将其设置为 True。 |
-interactive[:{True or False}] |
指示允许生成中的操作与用户交互。 请勿在不需要交互的自动化方案中使用此参数。 指定 -interactive 与指定 -interactive:true相同。 使用参数替代来自响应文件的值。 |
-isolateProjects[:{True, MessageUponIsolationViolation, False}]-isolate[:{True, MessageUponIsolationViolation, False}] |
使 MSBuild 以隔离的方式生成每个项目。 如果设置为 MessageUponIsolationViolation（或其短格式 Message），则仅当提供 -outputResultsCache 开关时，才会序列化顶级目标的结果。 此选项是使用不正确的状态缓解依赖项目的隔离违反目标的可能性，因为它依赖于缓存目标，其副作用不会被考虑。 （例如，属性的定义。此模式更具限制性，因为它要求在评估时静态发现项目图，但在生成大型项目时可以改进计划和减少内存开销。 |
-lowPriority[:{True or False}]-low[:{True or 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 节点的重用。 可以指定以下值： - 真。 生成完成后，节点将保持不变，以便后续生成可以使用它们（默认值）。 - 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有关常用属性列表，请参阅 通用 MSBuild 项目属性。 完整的可用属性集取决于项目类型、SDK 和导入的文件。 |
-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; ...}]-err[:{code; ...}] |
要视为错误的警告代码列表。 使用分号或逗号分隔多个警告代码。 若要将所有警告视为错误，请使用不带值的开关。 当警告被视为错误时，目标将继续执行，就像是警告一样，但整个生成会失败。 示例： -err:MSB4130 |
-warnNotAsError[:{code; ...}]-noerr[:{code; ...}] |
MSBuild 17.0 及更高版本。 不应提升为错误的警告代码列表。 具体而言，如果将 warnAsError 开关设置为将所有警告提升为错误，则不会提升使用 warnNotAsError 指定的错误代码。 如果未将 warnAsError 设置为将所有警告提升为错误，则这不起作用。 使用分号或逗号分隔多个警告代码。 示例： -noerr:MSB4130 |
-warnAsMessage[:{code}; ...}]-noWarn[:{code; ...}] |
要视为低重要性消息的警告代码列表。 使用分号或逗号分隔多个警告代码。 示例： -noWarn:MSB3026 |
记录器的开关
| 开关 | 描述 |
|---|---|
-binaryLogger[:[LogFile=]{output.binlog}[;ProjectImports=None、Embed、ZipFile]]-bl[:[LogFile=]{output.binlog}[;ProjectImports=None、Embed、ZipFile]] |
将所有生成事件序列化为压缩的二进制文件。 默认情况下，该文件位于当前目录中，msbuild.binlog命名。 二进制日志是生成过程的详细说明，稍后可用于重新构造文本日志，并由其他分析工具使用。 二进制日志通常比最详细的文本诊断级日志小 10-20 倍，但它包含更多信息。 默认情况下，二进制记录器收集项目文件的源文本，包括生成过程中遇到的所有导入的项目和目标文件。 可选 ProjectImports 参数控制此行为：- ProjectImports=None。 不要收集项目导入。 - ProjectImports=Embed。 在日志文件中嵌入项目导入（默认值）。 - ProjectImports=ZipFile。 将项目文件保存到 {output}.projectimports.zip，其中 <输出> 与二进制日志文件名称相同。 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。 显示每个已启动事件、已完成事件和消息的事件 ID。 - ForceNoAlign。 不要将文本与控制台缓冲区的大小对齐。 - DisableConsoleColor。 对所有日志记录消息使用默认控制台颜色。 - DisableMPLogging。 在非多处理器模式下运行时禁用输出的多处理器日志记录样式。 - EnableMPLogging。 启用多处理器日志记录样式，即使在非多处理器模式下运行也是如此。 默认情况下，此日志记录样式处于打开状态。 - ForceConsoleColor。 即使控制台不支持，也可以使用 ANSI 控制台颜色。 - 详细程度。 覆盖此记录器 -verbosity 设置。使用分号分隔多个参数，如以下示例所示： -consoleLoggerParameters:PerformanceSummary;NoSummary -verbosity:minimal默认控制台记录器处于正常详细状态，包括 Summary。 |
-distributedFileLogger-dfl |
将每个 MSBuild 节点的生成输出记录到自己的文件中。 这些文件的初始位置是当前目录。 默认情况下，这些文件 MSBuild{NodeId}.log命名。 可以使用 -fileLoggerParameters 开关指定 fileLogger 的文件和其他参数的位置。如果使用 -fileLoggerParameters 开关命名日志文件，则分布式记录器使用该名称作为模板，并在为每个节点创建日志文件时将该节点 ID 追加到该名称。 |
-distributedLogger:{central logger},{forwarding logger}, ...-dl:{central logger},{forwarding 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。 将生成日志写入到的日志文件的路径。 分布式文件记录器将此路径作为其日志文件名称的前缀。 - 追加。 确定生成日志是追加到日志文件中还是覆盖它。 设置开关时，生成日志将追加到日志文件中。 当开关不存在时，将覆盖现有日志文件的内容。 示例： 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- 编码。 指定文件的编码（例如 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] \| 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 及更高版本中可用。 |
例
以下示例生成 MyProject.proj 项目的 rebuild 目标。
MSBuild.exe MyProject.proj -t:rebuild
另请参阅
- MSBuild 参考
- 通用 MSBuild 项目属性