MSBuild@1 - MSBuild v1 task

Use this task to build with MSBuild.

Syntax

# MSBuild v1
# Build with MSBuild.
- task: MSBuild@1
  inputs:
    solution: '**/*.sln' # string. Required. Project. Default: **/*.sln.
    #msbuildLocationMethod: 'version' # 'version' | 'location'. MSBuild. Default: version.
    #msbuildVersion: 'latest' # 'latest' | '17.0' | '16.0' | '15.0' | '14.0' | '12.0' | '4.0'. Optional. Use when msbuildLocationMethod = version. MSBuild Version. Default: latest.
    #msbuildArchitecture: 'x86' # 'x86' | 'x64'. Optional. Use when msbuildLocationMethod = version. MSBuild Architecture. Default: x86.
    #msbuildLocation: # string. Optional. Use when msbuildLocationMethod = location. Path to MSBuild. 
    #platform: # string. Platform. 
    #configuration: # string. Configuration. 
    #msbuildArguments: # string. MSBuild Arguments. 
    #clean: false # boolean. Clean. Default: false.
  # Advanced
    #maximumCpuCount: false # boolean. Build in Parallel. Default: false.
    #restoreNugetPackages: false # boolean. Restore NuGet Packages. Default: false.
    #logProjectEvents: false # boolean. Record Project Details. Default: false.
    #createLogFile: false # boolean. Create Log File. Default: false.
    #logFileVerbosity: 'normal' # 'quiet' | 'minimal' | 'normal' | 'detailed' | 'diagnostic'. Optional. Use when createLogFile = true. Log File Verbosity. Default: normal.

Inputs

solution - Project
string. Required. Default value: **/*.sln.

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.

msbuildLocationMethod - MSBuild
string. Allowed values: version, location (Specify Location). Default value: version.

msbuildVersion - MSBuild Version
string. Optional. Use when msbuildLocationMethod = version. Allowed values: latest, 17.0 (MSBuild 17.0), 16.0 (MSBuild 16.0), 15.0 (MSBuild 15.0), 14.0 (MSBuild 14.0), 12.0 (MSBuild 12.0), 4.0 (MSBuild 4.0). Default value: latest.

If the preferred version cannot be found, the latest version found is used instead. On an macOS agent, xbuild (Mono) is used if version is lower than 15.0.

msbuildArchitecture - MSBuild Architecture
string. Optional. Use when msbuildLocationMethod = version. Allowed values: x86 (MSBuild x86), x64 (MSBuild x64). Default value: x86.

Supplies the MSBuild architecture (x86, x64) to run.

msbuildLocation - Path to MSBuild
string. Optional. Use when msbuildLocationMethod = location.

Supplies the path to MSBuild.

platform - Platform
string.

Tip

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

configuration - Configuration
string.

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.

msbuildArguments - MSBuild Arguments
string.

Specifies additional arguments passed to MSBuild (on Windows) and xbuild (on macOS).

clean - Clean
boolean. Default value: false.

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 the 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. For more information, see repo options

maximumCpuCount - Build in Parallel
boolean. Default value: false.

If your MSBuild target configuration is compatible with building in parallel, you can 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.

restoreNugetPackages - Restore NuGet Packages
boolean. Default value: false.

This option is deprecated. To restore NuGet packages, add a NuGet task before the build.

logProjectEvents - Record Project Details
boolean. Default value: false.

Optionally records timeline details for each project (Windows only).

createLogFile - Create Log File
boolean. Default value: false.

Optionally creates a log file (Windows only).

logFileVerbosity - Log File Verbosity
string. Optional. Use when createLogFile = true. Allowed values: quiet, minimal, normal, detailed, diagnostic. Default value: normal.

Specifies log file verbosity.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

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 have variables defined for your configurations and platforms. To specify multiple values, separate them with commas. For example:

   • For a .NET app, you could specify BuildConfiguration with debug and release values, and you could specify BuildPlatform with any CPU value.
   • For a C++ app, you could specify BuildConfiguration with debug and release values, and you could specify BuildPlatform with any x86 and x64 values.

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 TFS 2008. These files contain tasks, and targets are supported only using XAML builds.

Troubleshooting

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

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

• Possible causes
• Troubleshooting suggestions

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
• Try to reproduce the error locally
• What else can I do?

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:

• Configure verbose logs
• View and download logs

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:

• Worker diagnostic logs
• Agent diagnostic logs
• Other logs (Environment and capabilities)

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.

Tip

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

Learn more about Microsoft hosted agents.

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

• Self-hosted Windows agents
• Self-hosted Linux agents
• Self-hosted macOS agents

What else can I do?

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.

Requirements

Requirement	Description
Pipeline types	YAML, Classic build
Runs on	Agent, DeploymentGroup
Demands	Self-hosted agents must have capabilities that match the following demands to run jobs that use this task: msbuild
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	1.95.0 or greater
Task category	Build

See also

• Visual Studio Build task