Command-Line Reference

This section documents MSBuild 18.9, the .NET SDK 10.0.402 (with its dotnet CLI) and NuGet 7.9, as published in the MSBuild, .NET and NuGet documentation on learn.microsoft.com, which is the reference these pages are written and verified against. Material about .NET 11 / NuGet 8.0 is still in preview and is always flagged as such — never presented as baseline.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The C# Reference bibliography lists the reference material consulted while preparing these pages.

msbuild.exe and dotnet msbuild take the same command line: an optional project or solution file and a list of switches. The dotnet build, test, pack, publish, restore, clean and run commands also accept every MSBuild switch after their own options. This page lists every switch of MSBuild 18.9 (as printed by dotnet msbuild -help from .NET SDK 10.0.402) grouped by purpose, with the short form and the dotnet equivalent where one exists.

Syntax

msbuild.exe [options] [project file | directory]
dotnet msbuild [options] [project file | directory]

  • Switches start with - or / (-t:Build, /t:Build; on Linux and macOS use -) and -- is accepted too (--property:); values follow a colon. Switch names are case-insensitive.

  • Without a file, MSBuild uses the single project or solution file in the current directory (MSB1011 if it cannot decide; see Solutions and .slnx).

  • @file.rsp reads switches from a response file; Directory.Build.rsp and MSBuild.rsp are read automatically.

  • Exit code 0 means success, 1 means the build (or the command line) failed.

dotnet msbuild missing.proj -nologo; echo "exit=$?"
MSBUILD : error MSB1009: Project file does not exist.
Switch: missing.proj
exit=1

Source: MSBuild command-line reference: Syntax, Arguments, MSB1009, MSB1011.

Targets and properties

Switch Effect dotnet form

-target:<t1;t2>, -t:

Build these targets (otherwise DefaultTargets or the first target).

dotnet msbuild -t:X; dotnet build -t:X

-property:<n>=<v>, -p:

Set a global property (overrides the project; several with ; or repeated switches).

-p: or --property:; in dotnet build/publish/pack, -c = -p:Configuration=, -f = -p:TargetFramework=, -r = -p:RuntimeIdentifier=

-restore[:True|False], -r

Run Restore in a separate evaluation first, then build with the restored logic.

implicit in dotnet build; --no-restore turns it off

-restoreProperty:<n>=<v>, -rp:

A global property for the restore phase only.

same

-ignoreProjectExtensions:<.ext>, -ignore:

Ignore files with these extensions when looking for the project to build.

same

-toolsVersion:<v>, -tv:

Legacy toolset selection.

 — 

Parallelism

Switch Effect

-maxCpuCount[:n], -m

Use up to n worker nodes (processes); -m alone means one per processor. dotnet build passes -maxcpucount by default.

-multiThreaded[:True|False], -mt

(MSBuild 18.6+) build projects in parallel inside one process; tasks not marked multithreadable run in a task host. Listed only in the second copy of the reference’s switch table.

-nodeReuse:<bool>, -nr:

Keep worker nodes alive after the build (default true) for faster next builds; false on CI agents that must not leave processes behind.

-lowPriority[:bool], -low

Run at low process priority.

Graph builds and caches

Switch Effect

-graphBuild[:bool], -graph

Build the static project graph from ProjectReference items first, then build bottom-up (Parallel, Graph and Server Builds).

-isolateProjects[:True|MessageUponIsolationViolation|False], -isolate

Forbid a project from building targets of projects it did not declare as references.

-inputResultsCaches[:<files>], -irc; -outputResultsCache[:<file>], -orc

Read/write build results from/to cache files (implies -isolate); documented only as switches.

Evaluation queries

Switch Effect

-getProperty:<names>, -getItem:<types>, -getTargetResult:<targets>

(17.8+) Print evaluated values (or, with -t:, values after the build) as text or JSON.

-getResultOutputFile:<file>

Write the -get* output to a file. Not in the online reference.

-featureAvailability:<names>, -fa

Ask whether a named MSBuild feature is Available, NotAvailable, Preview or Undefined. Not in the online reference.

 
dotnet msbuild tasks.proj -getProperty:OutDir -getResultOutputFile:outdir.txt
cat outdir.txt
dotnet msbuild -featureAvailability:TerminalLogger
~/tasks/out/
Undefined

(Undefined means the name is unknown to the checker; the feature names are not documented.)

Source: MSBuild: Evaluate items and properties.

Output, inspection and response files

Switch Effect

-preprocess[:file], -pp

Write the project with every import inlined.

-targets[:file], -ts

List the project’s targets.

-verbosity:<q|m|n|d|diag>, -v:

Console verbosity: quiet, minimal, normal, detailed, diagnostic.

-version, -ver; -help, -h, -?; -noLogo

Version, help, banner.

-noAutoResponse, -noautorsp

Ignore MSBuild.rsp and Directory.Build.rsp.

@<file>

Read switches from a response file.

-validate[:schema], -val

Validate the project against the MSBuild schema — msbuild.exe only: the .NET MSBuild answers MSB1001: Unknown switch.

-question, -q

(Experimental) Fail if any incremental target or task is not up to date — a check that a build is fully incremental. Not in the online reference.

-profileEvaluation:<file>

Profile evaluation; .md gives a Markdown report. Not in the online reference.

-detailedSummary[:bool], -ds

Print node usage and per-project timing at the end.

-question makes a build that would do work fail instead. On the journal generator from Incremental Builds and Batching, after touching one journal, and again after a real build:

touch journals/feb.ledger.csv
dotnet msbuild Journals.csproj -question -tl:off -v:m; echo "exit=$?"
dotnet build Journals.csproj
dotnet msbuild Journals.csproj -question -tl:off -v:m; echo "exit=$?"
MSBUILD : error : Building target "GenerateJournalClasses" partially, because some output files are out of date with respect to their input files. [~/journals/Journals.csproj]
exit=1
…
exit=0

A response file and the target listing:

printf -- '-nologo\n-v:m\n-t:Archive\n' > archive.rsp
dotnet msbuild tasks.proj @archive.rsp
dotnet msbuild tasks.proj -ts:targets.txt -nologo && cat targets.txt
  Zipping directory "~/tasks/out/journals" to "~/tasks/out/journals.zip".
  Archived to journals.zip, deleted summary.txt
Tour
Archive

Source: MSBuild command-line reference.

Logging

Switch Effect

-binaryLogger[:[LogFile=]file.binlog[;ProjectImports=None|Embed|ZipFile]], -bl

Write a binary log (default msbuild.binlog); -bl:{} / publish-{}.binlog inserts a unique stamp. See Logging and Binary Logs.

-terminalLogger[:auto|on|off], -tl; -terminalLoggerParameters:, -tlp:

(17.8+) The Terminal Logger; auto (default for dotnet since .NET 9) uses it only when output is not redirected.

-consoleLoggerParameters:<p>, -clp:

Summary, NoSummary, ErrorsOnly, WarningsOnly, PerformanceSummary, ShowTimestamp, ShowCommandLine, ShowEventId, ForceNoAlign, DisableConsoleColor, ForceConsoleColor, EnableMPLogging, DisableMPLogging, NoItemAndPropertyList, Verbosity=.

-fileLogger[n], -fl[n]; -fileLoggerParameters[n]:, -flp[n]:

Write text logs (msbuild.log, or LogFile=, Append, Verbosity=, Encoding=); up to ten.

-distributedFileLogger, -dfl

One log file per node.

-logger:<class,assembly;params>, -l:

Attach a custom logger.

-distributedLogger:<central>*<forwarding>, -dl:

A central logger with a forwarding logger in each node.

-noConsoleLogger, -noconlog

Disable the console logger.

Source: MSBuild command-line reference: Switches for loggers.

Warnings and errors

Switch Effect

-warnAsError[:codes], -err

Treat all warnings, or the listed codes, as errors.

-warnNotAsError[:codes], -noerr

(17.0+) Exclude codes from a global -warnAsError.

-warnAsMessage[:codes], -noWarn

Downgrade codes to low-importance messages.

 
dotnet msbuild tasks.proj -nologo -v:q -warnAsError:LL1001; echo "exit=$?"
dotnet msbuild tasks.proj -nologo -v:m -warnAsMessage:LL1001 | grep -c "warning LL1001"
~/tasks/tasks.proj(43,5): error LL1001: Ledger warning example
exit=1
0

The project-level equivalents are the MSBuildTreatWarningsAsErrors, MSBuildWarningsAsErrors, MSBuildWarningsAsMessages and MSBuildWarningsNotAsErrors properties (and the compiler’s TreatWarningsAsErrors, WarningsAsErrors, NoWarn, which affect only compiler and NuGet diagnostics).

Source: MSBuild command-line reference.

Other switches

Switch Effect

-interactive[:bool]

Allow tasks to interact with the user (credential prompts during restore). dotnet commands take --interactive.

-check

Enable BuildCheck analyzers (.NET 9 / MSBuild 17.12+, experimental). It appears in -help and on the .NET 9 SDK what’s-new page but not in the MSBuild command-line reference (BuildCheck).

Gaps in the official reference

On 2026-10-23 the MSBuild command-line reference page contained its switch table twice; the second copy adds -multiThreaded/-mt. Neither copy lists -check, -question, -profileEvaluation, -getResultOutputFile, -featureAvailability or -terminalLoggerParameters, all of which dotnet msbuild -help prints for MSBuild 18.9. Treat msbuild -help as the list for the version you run.

Source: MSBuild command-line reference: Switches, .NET CLI: dotnet msbuild.

Common mistakes

  • Forgetting -restore with dotnet msbuild — NETSDK1004 on a fresh clone.

  • A -p: meant for one project applied to a whole solution — global properties flow to every project.

  • Comma instead of semicolon between property values or targets.

  • Shell quoting of ; and $ — quote the whole switch in Unix shells: '-p:DefineConstants=A;B'.

  • Relying on the console output in scripts — use -getProperty/-getItem or a binary log.

References