MSBuild

The Microsoft Build Engine is a platform for building applications. This engine, which is also known as MSBuild, provides an XML schema for a project file that controls how the build platform processes and builds software. Visual Studio uses MSBuild, but it doesn't depend on Visual Studio. By invoking msbuild.exe on your project or solution file, you can orchestrate and build products in environments where Visual Studio isn't installed.

Visual Studio uses MSBuild to load and build managed projects. The project files in Visual Studio (.csproj,.vbproj, vcxproj, and others) contain MSBuild XML code that executes when you build a project by using the IDE. Visual Studio projects import all the necessary settings and build processes to do typical development work, but you can extend or modify them from within Visual Studio or by using an XML editor.

The following examples illustrate when you might run builds by using an MSBuild command line instead of the Visual Studio IDE.

• Visual Studio isn't installed.

• You want to use the 64-bit version of MSBuild. This version of MSBuild is usually unnecessary, but it allows MSBuild to access more memory.

• You want to run a build in multiple processes. However, you can use the IDE to achieve the same result on projects in C++.

• You want to modify the build system. For example, you might want to enable the following actions:

  • Preprocess files before they reach the compiler.

  • Copy the build outputs to a different place.

  • Create compressed files from build outputs.

  • Do a post-processing step. For example, you might want to stamp an assembly with a different version.

You can write code in the Visual Studio IDE but run builds by using MSBuild. As another alternative, you can build code in the IDE on a development computer but use an MSBuild command line to build code that's integrated from multiple developers.

This topic provides an overview of MSBuild:

• The basic elements of an MSBuild project file.

• How to use MSBuild to build projects.

• The advanced features of MSBuild.

• How Visual Studio uses MSBuild to build projects.

For an introductory tutorial, see Walkthrough: Using MSBuild.

Project File

MSBuild uses an XML-based project file format that is straightforward and extensible. The MSBuild project file format lets developers describe the items that are to be built, and also how they are to be built for different operating systems and configurations. In addition, the project file format lets developers author re-usable build rules that can be factored into separate files so that builds can be performed consistently across different projects in the product.

The following sections describe some of the basic elements of the MSBuild project file format. For a tutorial about how to create a basic project file, see Walkthrough: Creating an MSBuild Project File from Scratch.

Properties

Properties represent key/value pairs that can be used to configure builds. Properties are declared by creating an element that has the name of the property as a child of a PropertyGroup element. For example, the following code creates a property named BuildDir that has a value of Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Properties can be referenced throughout the project file by using the syntax $(PropertyName). For example, the property in the example would be referenced by using $(BuildDir). For more information about properties, see MSBuild Properties.

Items

Items are inputs into the build system, and typically represent files. Items are grouped into item types, based on user-defined item names. These item types can be used as parameters for tasks, which use the individual items to perform the steps of the build process.

Items are declared in the project file by creating an element that has the name of the item type as a child of an ItemGroup element. For example, the following code creates an item type named Compile, which includes two files.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Item types can be referenced throughout the project file by using the syntax @(ItemType). For example, the item type in the example would be referenced by using @(Compile).

Items can be declared by using wildcard characters and may contain additional metadata for more advanced build scenarios. For more information about items, see MSBuild Items.

Tasks

Tasks are units of executable code that MSBuild projects use to perform build operations. For example, a task might compile input files or run an external tool. Tasks can be reused, and they can be shared by different developers in different projects.

The execution logic of a task is written in managed code and mapped to MSBuild by using the UsingTask element. You can write your own task by authoring a managed type that implements the ITask interface. For more information about how to write tasks, see Task Writing.

MSBuild includes common tasks that you can modify to suit your requirements, for example, Copy, which copies files, MakeDir, which creates directories, and Csc, which compiles Visual C# source code files. For a list of available tasks together with usage information, see MSBuild Task Reference.

A task is executed in an MSBuild project file by creating an element that has the name of the task as a child of a Target element. Tasks typically accept parameters, which are passed as attributes of the element. Both MSBuild properties and items can be used as parameters. For example, the following code calls the MakeDir task and passes it the value of the BuildDir property that was declared in the earlier example.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

For more information about tasks, see MSBuild Tasks.

Targets

Targets group tasks together in a particular order and expose sections of the project file as entry points into the build process. Targets are often grouped into logical sections to increase readability and allow for expansion. Breaking the build steps into targets lets you call one piece of the build process from other targets without copying that section of code into every target. For example, if several entry points into the build process require references to be built, you can create a target that builds references and then run that target from every entry point where it is required.

Targets are declared in the project file by using the Target element. For example, the following code creates a target named Compile, which then calls the Csc task that has the item list that was declared in the earlier example.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

In more advanced scenarios, targets can be used to describe relationships between one another and perform dependency analysis so that whole sections of the build process can be skipped if that target is up-to-date. For more information about targets, see MSBuild Targets.

Conditional Elements

Many MSBuild elements are defined conditionally, that is, the Condition attribute appears in the element. The contents of conditional elements are ignored unless the condition evaluates to "true". For example,

<Configuration   Condition=" '$(Configuration)' == '' ">Debug</Configuration>

means "If the Configuration property has not been defined yet, define it and give it the value Debug".

Almost all MSBuild elements can have a Condition attribute. For more information, see MSBuild Conditions.

Case Sensitivity

The MSBuild XML schema follows the rules of XML. Element and attribute names are case-sensitive. However, property, item, and metadata names are not case-sensitive in the MSBuild object model. Consider the following item group.

<ItemGroup>
  <Compile Include="one.cs" />
  <comPile Include="two.cs" />
</ItemGroup>

This creates the item type Compile, or comPile, or any other case variation, and gives it the value "one.cs;two.cs".

Using MSBuild at a Command Prompt

To run MSBuild at a command prompt, pass a project file to MSBuild.exe, together with the appropriate command-line options. Command-line options let you set properties, execute specific targets, and set other options that control the build process. For example, you would use the following command-line syntax to build the file MyProj.proj with the Configuration property set to Debug.

MSBuild.exe MyProj.proj /property:Configuration=Debug

For more information about MSBuild command-line options, see MSBuild Command Line Reference. 

Security Note
Before you download a project, determine the trustworthiness of the code.

Advanced Concepts

MSBuild can also be used to perform other operations, for example, logging errors, warnings, and messages to the console or to other output devices, performing dependency analysis on targets, and batching tasks and targets on item metadata. For more information about these advanced concepts, see MSBuild Advanced Concepts.

Using MSBuild in Visual Studio

Visual Studio uses the MSBuild project file format to store build information about managed projects. Project settings that are added or changed by using the Visual Studio interface are reflected in the .*proj file that is generated for every project. Visual Studio uses a hosted instance of MSBuild to build managed projects. This means that a managed project can be built in Visual Studio, or at a command prompt (even if Visual Studio is not installed), and the results will be identical.

For a tutorial about how to use MSBuild in Visual Studio, see Walkthrough: Using MSBuild.

Multitargeting

By using Visual Studio, you can compile an application to run on any one of several versions of the .NET Framework. For example, you can compile an application to run on the .NET Framework version 2.0, and compile the same application to run on the .NET Framework version 4. The ability to compile to more than one framework is named multitargeting.

These are some of the benefits of multitargeting:

• You can develop applications that target earlier versions of the .NET Framework, for example, versions 2.0, 3.0, and 3.5.

• You can target frameworks other than the .NET Framework, for example, the Silverlight Framework.

• You can target a framework profile, which is a predefined subset of a target framework.

• If any service packs for the .NET Framework version 4 are released, you could target them.

• Multitargeting guarantees that an application uses only the functionality that is available in the target framework.

For more information, see MSBuild Multitargeting.

Related Topics

Reference

• MSBuild Reference
  Links to topics that contain reference information.

• MSBuild Glossary
  Defines common MSBuild terms.