MSBuild task

Azure Pipelines | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2015


In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

Use this task to build with MSBuild.



Azure Pipelines: If your team uses Visual Studio 2017 and you want to use the Microsoft-hosted agents, make sure you select as your default pool the Hosted VS2017. See Microsoft-hosted agents.

YAML snippet

# MSBuild
# Build with MSBuild
- task: MSBuild@1
    #solution: '**/*.sln' 
    #msbuildLocationMethod: 'version' # Optional. Options: version, location
    #msbuildVersion: 'latest' # Optional. Options: latest, 16.0, 15.0, 14.0, 12.0, 4.0
    #msbuildArchitecture: 'x86' # Optional. Options: x86, x64
    #msbuildLocation: # Optional
    #platform: # Optional
    #configuration: # Optional
    #msbuildArguments: # Optional
    #clean: false # Optional
    #maximumCpuCount: false # Optional
    #restoreNugetPackages: false # Optional
    #logProjectEvents: false # Optional
    #createLogFile: false # Optional
    #logFileVerbosity: 'normal' # Optional. Options: quiet, minimal, normal, detailed, diagnostic


Argument Description

(Required) If you want to build a single project, click the ... button and select the project.

If you want to build multiple projects, specify search criteria. You can use a single-folder wildcard (*) and recursive wildcards (**). For example, **.*proj searches for all MSBuild project (.*proj) files in all subdirectories.

Make sure the projects you specify are downloaded by this build pipeline. On the Repository tab:

  • If you use TFVC, make sure that the project is a child of one of the mappings on the Repository tab.
  • If you use Git, make sure that the project or project is in your Git repo, in a branch that you're building.

Tip: If you are building a solution, we recommend you use the Visual Studio build task instead of the MSBuild task.

Default value: **/*.sln
Default value: version
MSBuild Version
(Optional) If the preferred version cannot be found, the latest version found will be used instead. On an macOS agent, xbuild (Mono) will be used if version is lower than 15.0
Default value: latest
MSBuild Architecture
(Optional) Optionally supply the architecture (x86, x64) of MSBuild to run
Default value: x86
Path to MSBuild
(Optional) Optionally supply the path to MSBuild

(Optional) Specify the platform you want to build such as Win32, x86, x64 or any cpu.


  • If you are targeting an MSBuild project (.*proj) file instead of a solution, specify AnyCPU (no whitespace).
  • Declare a build variable such as BuildPlatform on the Variables tab (selecting Allow at Queue Time) and reference it here as $(BuildPlatform). This way you can modify the platform when you queue the build and enable building multiple configurations.

(Optional) Specify the configuration you want to build such as debug or release.

Tip: Declare a build variable such as BuildConfiguration on the Variables tab (selecting Allow at Queue Time) and reference it here as $(BuildConfiguration). This way you can modify the platform when you queue the build and enable building multiple configurations.

MSBuild Arguments
(Optional) Additional arguments passed to MSBuild (on Windows) and xbuild (on macOS)

Set to False if you want to make this an incremental build. This setting might reduce your build time, especially if your codebase is large. This option has no practical effect unless you also set Clean repository to False.

Set to True if you want to rebuild all the code in the code projects. This is equivalent to the MSBuild /target:clean argument.

See, repo options

Default value: false
Build in Parallel
(Optional) If your MSBuild target configuration is compatible with building in parallel, you can optionally check this input to pass the /m switch to MSBuild (Windows only). If your target configuration is not compatible with building in parallel, checking this option may cause your build to result in file-in-use errors, or intermittent or inconsistent build failures.
Default value: false
Restore NuGet Packages
(Important) This option is deprecated. Make sure to clear this checkbox and instead use the NuGet Installer build task.
Default value: false
Record Project Details
Optionally record timeline details for each project (Windows only)
Default value: false
Create Log File

Optionally create a log file (Windows only)

Default value: false
Log File Verbosity

Optional log file verbosity

Default value: normal
Control options

Open source

This task is open source on GitHub. Feedback and contributions are welcome.


Should I use the Visual Studio Build task or the MSBuild task?

If you are building a solution, in most cases you should use the Visual Studio Build task. This task automatically:

  • Sets the /p:VisualStudioVersion property for you. This forces MSBuild to use a particular set of targets that increase the likelihood of a successful build.

  • Specifies the MSBuild version argument.

In some cases, you might need to use the MSBuild task. For example, you should use it if you are building code projects apart from a solution.

Where can I learn more about MSBuild?

MSBuild reference

MSBuild command-line reference

How do I build multiple configurations for multiple platforms?

  1. On the Variables tab, make sure you've got variables defined for your configurations and platforms. To specify multiple values, separate them with commas.

    For example, for a .NET app you could specify:

    Name Value
    BuildConfiguration debug, release
    BuildPlatform any cpu

    For example, for a C++ app you could specify:

    Name Value
    BuildConfiguration debug, release
    BuildPlatform x86, x64
  2. On the Options tab, select MultiConfiguration and specify the Multipliers, separated by commas. For example: BuildConfiguration, BuildPlatform

    Select Parallel if you want to distribute the jobs (one for each combination of values) to multiple agents in parallel if they are available.

  3. On the Build tab, select this step and specify the Platform and Configuration arguments. For example:

    • Platform: $(BuildPlatform)
    • Configuration: $(BuildConfiguration)

Can I build TFSBuild.proj files?

You cannot build TFSBuild.proj files. These kinds of files are generated by TFS 2005 and 2008. These files contain tasks and targets are supported only using XAML builds.

Do I need an agent?

You need at least one agent to run your build or release.

I'm having problems. How can I troubleshoot them?

See Troubleshoot Build and Release.

I can't select a default agent pool and I can't queue my build or release. How do I fix this?

See Agent pools.

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.


This section provides troubleshooting tips for common issues that a user might encounter when using the MSBuild task.

Build failed with the following error: An internal failure occurred while running MSBuild

Possible causes

  • Change in the MSBuild version.
  • Issues with a third-party extension.
  • New updates to Visual Studio that can cause missing assemblies on the build agent.
  • Moved or deleted some of the necessary NuGet packages.

Troubleshooting suggestions

Run the pipeline with diagnostics to retrieve detailed logs

One of the available options to diagnose the issue is to take a look at the generated logs. You can view your pipeline logs by selecting the appropriate task and job in your pipeline run summary.

To get the logs of your pipeline execution Get logs to diagnose problems

You can also setup and download a customized verbose log to assist with your troubleshooting:

In addition to the pipeline diagnostic logs, you can also check these other types of logs that contain more information to help you debug and solve the problem:

Try to reproduce the error locally

If you are using a hosted build agent, you might want to try to reproduce the error locally. This will help you to narrow down whether the failure is the result of the build agent or the build task.

Run the same MSBuild command on your local machine using the same arguments. Check out MSBuild command for reference


If you can reproduce the problem on your local machine, then your next step is to investigate the MSBuild issue.

For more information on Microsoft hosted agents

To setup your own self-hosted agent and run the build jobs:

What else can I do?

At the bottom of this page, check out the GitHub issues in the Open and Closed tabs to see if there is a similar issue that has been resolved previously by our team.

Some of the MSBuild errors are caused by a change in Visual Studio so you can search on Visual Studio Developer Community to see if this issue has been reported. We also welcome your questions, suggestions, and feedback.