MSBuild command-line reference

Artikel
06/13/2024

When you use MSBuild.exe to build a project or solution file, you can include several switches to specify various aspects of the process.

Every switch is available in two forms: -switch and /switch. The documentation only shows the -switch form. Switches aren't case-sensitive. If you run MSBuild from a shell other than the Windows command prompt, lists of arguments to a switch (separated by semicolons or commas) might need single or double quotes to ensure that lists are passed to MSBuild instead of interpreted by the 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`	Builds the targets in the project file that you specify. 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. You can also specify a Visual Studio solution file for this argument.

Switches

The first column in the following table shows a long and short form of each switch. Both forms are equivalent.

Square brackets [] indicate optional parts, and curly braces {}indicate user-supplied values.

Switch	Description
`-detailedSummary[:{True or False}]` `-ds[:{True or False}]`	If `True`, show detailed information at the end of the build log about the configurations that were built and how they were scheduled to nodes.
`-getItem:{itemName,...}`	Write out the value of the item or items after evaluation, without executing the build, or if either the `-targets` option or the `-getTargetResult` option is used, write out the values after the build.
`-getProperty:{propertyName,...}`	Write out the value of the property or properties after evaluation, without executing the build, or if either the `-targets` option or the `-getTargetResult` option is used, write out the values after the build.
`-getTargetResult:{targetName,...}`	Write out the output values of the specified targets.
`-graphBuild[:{True or False}]` `-graph[:{True or False}]`	Causes MSBuild to construct and build a project graph. Constructing a graph involves identifying project references to form dependencies. Building that graph involves attempting to build project references prior to the projects that reference them, differing from traditional MSBuild scheduling. Requires MSBuild 16 or later.
`-help` `/?` or `-h`	Display usage information. The following command is an example: `msbuild.exe -?`
`-ignoreProjectExtensions: {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`
`-inputResultsCaches[:{cacheFile; ...}]` `-irc[:{cacheFile; ...}]`	Semicolon separated list of input cache files that MSBuild will read build results from. If `-isolateProjects` is set to `False`, this sets it to `True`.
`-interactive[:{True or False}]`	Indicates that actions in the build are allowed to interact with the user. Don't use this argument in an automated scenario where interactivity is not expected. Specifying `-interactive` is the same as specifying `-interactive:true`. Use the parameter to override a value that comes from a response file.
`-isolateProjects[:{True, MessageUponIsolationViolation, False}]` `-isolate[:{True, MessageUponIsolationViolation, False}]`	Causes MSBuild to build each project in isolation. When set to `MessageUponIsolationViolation` (or its short form `Message`), only the results from top-level targets are serialized if the `-outputResultsCache` switch is supplied. This option is to mitigate the chances of an isolation-violating target on a dependency project using incorrect state due to its dependency on a cached target whose side effects wouldn't be taken into account. (For example, the definition of a property.) This mode is more restrictive, as it requires that the project graph be statically discoverable at evaluation time, but can improve scheduling and reduce memory overhead when building a large set of projects.
`-lowPriority[:{True or False}]` `-low[:{True or False}]`	Causes MSBuild to run at low process priority. Specifying `-lowPriority` is the same as specifying `-lowPriority:True`.
`-maxCpuCount[:{number}]` `-m[:{number}]`	Specifies the maximum number of concurrent processes to use when building. If you don't include this switch, the default value is 1. If you include this switch without specifying a value, MSBuild uses up to the number of processors in the computer. For more information, see Building multiple projects in parallel. 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` `-noautorsp`	Don't include any MSBuild.rsp or Directory.Build.rsp files automatically.
`-nodeReuse:{value}` `-nr:{value}`	Enable or disable the reuse of MSBuild nodes. You can specify the following values: - True. Nodes remain after the build finishes so that subsequent builds can use them (default). - False. Nodes don't remain after the build completes. A node corresponds to a project that's executing. If you include the `-maxcpucount` switch, multiple nodes can execute concurrently.
`-nologo`	Don't display the startup banner or the copyright message.
`-preprocess[:{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. If you specify a `filepath`, the aggregated project file is output to the file. Otherwise, the output appears in the console window. 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.
`-outputResultsCache[:{cacheFile}]` `-orc[:{cacheFile}]`	Output cache file where MSBuild writes the contents of its build result caches at the end of the build. If `-isolateProjects` is set to `False`, this sets it to `True`.
`profileEvaluation:{file}`	Profiles MSBuild evaluation and writes the result to the specified file. If the extension of the specified file is '.md', the result is generated in Markdown format. Otherwise, a tab-separated file is produced.
`-property:{name}={value}` `-p:{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` See Common MSBuild project properties for a list of commonly used properties. The full set of available properties depends on the project type, SDK, and imported files.
`-restore` `-r`	Runs the `Restore` target prior to building the actual targets.
`-restoreProperty:{name}={value}` `-rp:{name}={value}`	Set or override these project-level properties only during restore and don't use properties specified with the `-property` argument. `name` is the property name, and `value` is the property value. Use a semicolon or a comma to separate multiple properties, or specify each property separately.
`-target:{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` If you specify any targets by using this switch, they're 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.
`-targets[:{file}]` `-ts[:{file}]`	Write the list of available targets to the specified file (or the output device, if no file is specified), without actually executing the build process.
`-toolsVersion:{version}` `-tv:{version}`	Specifies a custom toolset. A toolset consists of tasks, targets, and tools that are used to build an application. See Toolset (ToolsVersion) and Standard and custom toolset configurations.
`-validate:[{schema}]` `-val[{schema}]`	Validate the project file and, if validation succeeds, build the project. If you don't specify `schema`, the project is validated against the default schema. If you specify `schema`, the project is validated against the schema that you specify. The following setting is an example: `-validate:MyExtendedBuildSchema.xsd`
`-verbosity:{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. You can specify the following verbosity levels: `q[uiet]`, `m[inimal]`, `n[ormal]` (default), `d[etailed]`, and `diag[nostic]`. The following setting is an example: `-verbosity:quiet`
`-version` `-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.
`-warnAsError[:{code; ...}]` `-err[:{code; ...}]`	List of warning codes to treats as errors. Use a semicolon or a comma to separate multiple warning codes. To treat all warnings as errors, use the switch with no values. When a warning is treated as an error, the target continues to execute as if it was a warning, but the overall build fails. Example: `-err:MSB4130`
`-warnNotAsError[:{code; ...}]` `-noerr[:{code; ...}]`	MSBuild 17.0 and later. List of warning codes that shouldn't be promoted to errors. Specifically, if the warnAsError switch is set to promote all warnings to errors, error codes specified with warnNotAsError aren't promoted. This has no effect if warnAsError isn't set to promote all warnings to errors. Use a semicolon or a comma to separate multiple warning codes. Example: `-noerr:MSB4130`
`-warnAsMessage[:{code}; ...}]` `-noWarn[:{code; ...}]`	List of warning codes to treats as low importance messages. Use a semicolon or a comma to separate multiple warning codes. Example: `-noWarn:MSB3026`

Switches for loggers

Switch	Description
`-binaryLogger[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]` `-bl[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]`	Serializes all build events to a compressed binary file. By 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. 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. The optional `ProjectImports` parameter controls this behavior: - ProjectImports=None. Don't collect the project imports. - ProjectImports=Embed. Embed project imports in the log file (default). - ProjectImports=ZipFile. Save project files to {output}.projectimports.zip where <output> is the same name as the binary log file name. The default setting for ProjectImports is 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. Other loggers receive the information contained in the log file as if the original build was happening. You can read more about the binary log and its usages at: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md Examples: - `-bl` - `-bl:output.binlog` - `-bl:output.binlog;ProjectImports=None` - `-bl:output.binlog;ProjectImports=ZipFile` - `-bl:..\..\custom.binlog` - `-binaryLogger`
`-consoleLoggerParameters:{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. Show the time that's spent in tasks, targets, and projects. - Summary. Show the error and warning summary at the end. - NoSummary. Don't show the error and warning summary at the end. - ErrorsOnly. Show only errors. - WarningsOnly. Show only warnings. - NoItemAndPropertyList. 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. Show `TaskCommandLineEvent` messages. - ShowProjectFile. Show the path to the project file in diagnostic messages. This setting is on by default. - ShowTimestamp. Show the timestamp as a prefix to any message. - ShowEventId. Show the event ID for each started event, finished event, and message. - ForceNoAlign. Don't align the text to the size of the console buffer. - DisableConsoleColor. Use the default console colors for all logging messages. - DisableMPLogging. Disable the multiprocessor logging style of output when running in non-multiprocessor mode. - EnableMPLogging. Enable the multiprocessor logging style even when running in non-multiprocessor mode. This logging style is on by default. - ForceConsoleColor. Use ANSI console colors even if console doesn't support it. - 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` The default console logger is at normal verbosity and includes a `Summary`.
`-distributedFileLogger` `-dfl`	Log the build output of each MSBuild node to its own file. The initial location for these files is the current directory. By default, the files are named MSBuild{NodeId}.log. You can use the `-fileLoggerParameters` switch to specify the location of the files and other parameters for the fileLogger. If you name a log file by using the `-fileLoggerParameters` switch, the distributed logger uses that name as a template and append the node ID to that name when creating a log file for each node.
`-distributedLogger:{central logger},{forwarding logger}, ...` `-dl:{central logger},{forwarding logger, ...}`	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, except you provide and additional class for the forwarding logger. For the logger syntax, see the `-logger` switch. 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[{number}]` `-fl[{number}]`	Log the build output to a single file in the current directory. If you don't specify `number`, the output file is named msbuild.log. If you specify `number`, the output file is named msbuild<n>.log, where <n> is `number`. `Number` can be a digit from 1 to 9. You can use the `-fileLoggerParameters` switch to specify the location of the file and other parameters for the fileLogger.
`-fileLoggerParameters[{number}]:` `parameters` `-flp[{number}]: {parameters}`	Specifies any extra parameters for the file logger and the distributed file logger. The presence of this switch implies that the corresponding `-filelogger[number]` switch is present. `Number` can be a digit from 1 to 9. You can use all parameters that are listed for `-consoleloggerparameters`. You can also use one or more of the following parameters: - 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. 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 isn't present, the contents of an existing log file are overwritten. Example: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append` If you include an explicit `true` or `false` setting, the log is appended regardless of the setting. If you don't include the append switch, the log is overwritten. In this case, the file is overwritten: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log` In this case, the file is appended: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true` In this case, the file is appended: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false` - Encoding. 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`
`-logger:logger` `-l:logger`	Specifies the logger to use to log events from MSBuild. To specify multiple loggers, specify each logger separately. Use the following syntax for `logger`: `[LoggerClass,]LoggerAssembly[;LoggerParameters]` Use the following syntax for `LoggerClass`: `[PartialOrFullNamespace.]LoggerClassName` You don't have to specify the logger class if the assembly contains exactly one logger. Use the following syntax for `LoggerAssembly`: `AssemblyName[,StrongName] \\| AssemblyFile` Logger parameters are optional and are passed to the logger exactly as you enter them. The following examples use the `-logger` switch. `-logger:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML`
`-noConsoleLogger` `-noconlog`	Disable the default console logger, and don't log events to the console.
`-terminalLogger[:auto`,`on`,`off]` `-tl[:auto`,`on`,`off]`	Enable or disable the terminal logger. Terminal logger provides enhanced build output on the console in real time, organized logically by project, and designed to highlight actionable information. Specify `auto` (or use the option without arguments) to use the terminal logger only if the standard output is not redirected. Don't parse the output or otherwise rely on it remaining unchanged in future versions. This option is available in MSBuild 17.8 and later.

Example 1

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

MSBuild.exe MyProject.proj -t:rebuild

Example 2

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. 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

Dela via