MSBuild 命令行参考

2025-08-08

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。文档仅显示 -switch 窗体。开关不区分大小写。如果从 Windows 命令提示符以外的 shell 运行 MSBuild，则开关（用分号或逗号分隔）的参数列表可能需要单引号或双引号，以确保列表传递到 MSBuild，而不是由 shell 解释。

The .NET CLI commands dotnet build, dotnet publish, dotnet msbuild and related commands pass these switches to MSBuild, so this reference is applicable when you use those commands; however dotnet run does not.

Syntax

MSBuild.exe [Switches] [ProjectFile]

Arguments

Argument Description

ProjectFile 在指定的项目文件中生成目标。 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 解决方案文件。在 Visual Studio 17.12 及更高版本中，支持 .slnx 解决方案文件格式以及 .sln 格式。同一解决方案的 .sln 和 .slnx 文件可以存在于同一目录中;如果两者都存在，则必须显式指定其中一个来生成解决方案。

Argument	Description
`ProjectFile`	在指定的项目文件中生成目标。 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 解决方案文件。在 Visual Studio 17.12 及更高版本中，支持 `.slnx` 解决方案文件格式以及 `.sln` 格式。同一解决方案的 `.sln` 和 `.slnx` 文件可以存在于同一目录中;如果两者都存在，则必须显式指定其中一个来生成解决方案。

Switches

下表中的第一列显示了每个开关的长短形式。这两种形式都是等效的。

方括号 [] 指示可选部分，大括号 {}表示用户提供的值。

Switch	Description
`-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`	Don't include any MSBuild.rsp or Directory.Build.rsp files automatically.
`-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` 有关常用属性列表，请参阅通用 MSBuild 项目属性。完整的可用属性集取决于项目类型、SDK 和导入的文件。
`-restore` `-r`	在生成实际目标之前运行 `Restore` 目标。
`-restoreProperty:{name}={value}` `-rp:{name}={value}`	仅在还原期间设置或重写这些项目级属性，并且不使用 `-property` 参数指定的属性。 `name` 是属性名称，`value` 是属性值。使用分号或逗号分隔多个属性，或单独指定每个属性。
`-target:{targets}` `-t:{targets}`	在项目中生成指定的目标。单独指定每个目标，或使用分号或逗号分隔多个目标，如以下示例所示： `-target:PrepareResources;Compile` 如果使用此开关指定任何目标，则会运行它们，而不是项目文件中 `DefaultTargets` 属性中的任何目标。有关详细信息，请参阅目标生成顺序和如何：指定要生成第一个的目标。目标是一组任务。 For more information, see Targets.
`-targets[:{file}]` `-ts[:{file}]`	将可用目标列表写入指定文件（或输出设备（如果未指定文件），而无需实际执行生成过程。
`-toolsVersion:{version}` `-tv:{version}`	指定自定义工具集。工具集由用于生成应用程序的任务、目标和工具组成。 See Toolset (ToolsVersion) and Standard and custom toolset configurations.
`-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}`	从文本文件插入命令行开关。如果有多个文件，请单独指定这些文件。 For more information, see Response files.
`-warnAsError[:{code; ...}]` `-err[:{code; ...}]`	要视为错误的警告代码列表。使用分号或逗号分隔多个警告代码。若要将所有警告视为错误，请使用不带值的开关。当警告被视为错误时，目标将继续执行，就像是警告一样，但整个生成会失败。示例：`-err:MSB4130`
`-warnNotAsError[:{code; ...}]` `-noerr[:{code; ...}]`	MSBuild 17.0 及更高版本。不应提升为错误的警告代码列表。具体而言，如果将 warnAsError 开关设置为将所有警告提升为错误，则不会提升使用 warnNotAsError 指定的错误代码。如果未将 warnAsError 设置为将所有警告提升为错误，则这不起作用。使用分号或逗号分隔多个警告代码。示例：`-noerr:MSB4130`
`-warnAsMessage[:{code}; ...}]` `-noWarn[:{code; ...}]`	要视为低重要性消息的警告代码列表。使用分号或逗号分隔多个警告代码。示例：`-noWarn:MSB3026`

记录器的开关

Switch	Description
`-binaryLogger[:[LogFile=]{output.binlog}` `[;ProjectImports=None`、`Embed`、`ZipFile]]` `-bl[:[LogFile=]{output.binlog}` `[;ProjectImports=None`、`Embed`、`ZipFile]]`	将所有生成事件序列化为压缩的二进制文件。 By default the file is in the current directory and named msbuild.binlog. 可选 `LogFile` 参数接受窗体 `{filename}.binlog`的字符串，其中 `{filename}` 包含有效的文件系统字符，但也接受占位符符号 `{}`。如果 `{}` 提供，MSBuild 将使用窗体 `yyyyMMdd-HHmmss--<current process id>--<6-character random string>`的“唯一标记”填充该位置。二进制日志是生成过程的详细说明，稍后可用于重新构造文本日志，并由其他分析工具使用。二进制日志通常比最详细的文本诊断级日志小 10-20 倍，但它包含更多信息。默认情况下，二进制记录器收集项目文件的源文本，包括生成过程中遇到的所有导入的项目和目标文件。可选 `ProjectImports` 参数控制此行为： - ProjectImports=None. 不要收集项目导入。 - ProjectImports=Embed. 在日志文件中嵌入项目导入（默认值）。 - ProjectImports=ZipFile. Save project files to {output}.projectimports.zip where <output> is the same name as the binary log file name. ProjectImports 的默认设置为 Embed。 Note: the logger doesn't collect non-MSBuild source files such as `.cs`, `.cpp`, and so on. A .binlog file can be "played back" by passing it to msbuild.exe as an argument instead of a project/solution. 其他记录器接收日志文件中包含的信息，就像原始生成发生一样。可以在 MSBuild 二进制日志概述中详细了解二进制日志及其用法。 Examples: - `-bl` - `-bl:output.binlog` - `-bl:output.binlog;ProjectImports=None` - `-bl:output.binlog;ProjectImports=ZipFile` - `-bl:..\..\custom.binlog` - `-bl:publish-{}.binlog` - `-binaryLogger`
`-consoleLoggerParameters:{parameters}` `-clp:{parameters}`	将指定的参数传递给控制台记录器，该记录器在控制台窗口中显示生成信息。可以指定以下参数： - PerformanceSummary. 显示任务、目标和项目所用的时间。 - Summary. 在末尾显示错误和警告摘要。 - NoSummary. 不要在末尾显示错误和警告摘要。 - ErrorsOnly. 仅显示错误。 - WarningsOnly. 仅显示警告。 - NoItemAndPropertyList. 如果详细级别设置为 `diagnostic`，则不要显示每个项目生成开始时显示的项和属性的列表。 - ShowCommandLine. 显示 `TaskCommandLineEvent` 消息。 - ShowProjectFile. 在诊断消息中显示项目文件的路径。此设置默认处于打开状态。 - ShowTimestamp. 将时间戳显示为任何消息的前缀。 - ShowEventId. 显示每个已启动事件、已完成事件和消息的事件 ID。 - ForceNoAlign. 不要将文本与控制台缓冲区的大小对齐。 - DisableConsoleColor. 对所有日志记录消息使用默认控制台颜色。 - DisableMPLogging. 在非多处理器模式下运行时禁用输出的多处理器日志记录样式。 - EnableMPLogging. 启用多处理器日志记录样式，即使在非多处理器模式下运行也是如此。默认情况下，此日志记录样式处于打开状态。 - ForceConsoleColor. 即使控制台不支持，也可以使用 ANSI 控制台颜色。 - Verbosity. 覆盖此记录器 `-verbosity` 设置。使用分号分隔多个参数，如以下示例所示： `-consoleLoggerParameters:PerformanceSummary;NoSummary -verbosity:minimal` 默认控制台记录器处于正常详细状态，包括 `Summary`。
`-distributedFileLogger` `-dfl`	将每个 MSBuild 节点的生成输出记录到自己的文件中。这些文件的初始位置是当前目录。 By default, the files are named 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}]`	将生成输出记录到当前目录中的单个文件。 If you don't specify `number`, the output file is named 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] \\| 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]`	Enable or disable the terminal logger. 终端记录器实时在主机上提供增强的生成输出，按项目按逻辑组织，旨在突出显示可操作的信息。仅当未重定向标准输出时，指定 `auto`（或使用不带参数的选项）才能使用终端记录器。不要分析输出，否则依赖于它在未来版本中保持不变。此选项在 MSBuild 17.8 及更高版本中可用。

Example

The following example builds the rebuild target of the MyProject.proj project.

MSBuild.exe MyProject.proj -t:rebuild