MSBuild Overview
The Microsoft Build Engine (MSBuild) is the new build platform for Microsoft and Visual Studio. MSBuild is completely transparent with regards to how it processes and builds software, enabling developers to orchestrate and build products in build lab environments where Visual Studio is not installed. This topic provides brief overviews of:
The basic elements of an MSBuild project file.
How MSBuild is used to build projects.
The advanced features of MSBuild.
How Visual Studio uses MSBuild to build projects.
Project File
MSBuild introduces a new XML-based project file format that is simple to understand, easy to extend, and fully supported by Microsoft. The MSBuild project file format enables developers to fully describe what items need to be built as well as how they need to be built with different platforms and configurations. In addition, the project file format enables developers to author re-usable build rules that can be factored into separate files so that builds can be performed consistently across different projects within their product. The following sections describe some of the basic elements of the MSBuild project file format.
Items
Items represent inputs into the build system and are grouped into item collections based on their user-defined collection names. These item collections can be used as parameters for tasks, which use the individual items contained in the collection to perform the steps of the build process.
Items are declared in the project file by creating an element with the name of the item collection as a child of an ItemGroup element. For example, the following code creates an item collection named Compile, which includes two files.
<ItemGroup>
<Compile Include = "file1.cs"/>
<Compile Include = "file2.cs"/>
</ItemGroup>
You reference item collections throughout the project file with the syntax @(ItemCollectionName). For example, you reference the item collection in the example above with @(Compile).
Items can be declared using wildcards and may contain additional metadata for more advanced build scenarios. For more information on items, see MSBuild Items.
Properties
Properties represent key/value pairs that can be used to configure builds. Items and properties differ in the following ways:
Items are stored in collections, while properties contain a single scalar value.
Items cannot be removed from item collections, while properties can have their values changed after they are defined.
Items can contain metadata and can use the %(ItemMetadata) notation, while properties cannot.
Properties are declared by creating an element with the name of the property as a child of a PropertyGroup element. For example, the following code creates a property named BuildDir with a value of Build.
<PropertyGroup>
<BuildDir>Build</BuildDir>
</PropertyGroup>
You reference properties throughout the project file with the syntax $(PropertyName). For example, you reference the property in the example above with $(BuildDir). For more information on properties, see MSBuild Properties.
Tasks
Tasks are reusable units of executable code used by MSBuild projects to perform build operations. For example, a task might compile input files or run an external tool. Once created, tasks can be shared and reused by different developers in different projects.
The execution logic of a task is written in managed code and mapped to MSBuild with the UsingTask element. You can write your own task by authoring a managed type that implements the ITask interface. For more information on writing tasks, see How to: Write a Task.
MSBuild ships with many common tasks such as Copy, which copies files, MakeDir, which creates directories, and Csc, which compiles Visual C# source code files. For a complete list of available tasks and usage information, see MSBuild Task Reference.
You execute a task in an MSBuild project file by creating an element with the name of the task as a child of a Target element. Tasks usually accept parameters, which are passed as attributes of the element. MSBuild item collections and properties can be used as parameters. For example, the following code calls the MakeDir task and passes it the value of the BuildDir property declared in the previous example.
<Target Name="MakeBuildDirectory">
<MakeDir
Directories="$(BuildDir)" />
</Target>
For more information on 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 allow for expansion and increase readability. Breaking the build steps into many targets allows you to call one piece of the build process from other targets without having to copy that section of code into each 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 run that target from every necessary entry point.
Targets are declared in the project file with the Target element. For example, the following code creates a target named Compile, which then calls the Csc task with the item collection declared in the previous example.
<Target Name="Compile">
<Csc Sources="@(Compile)" />
</Target>
In more advanced scenarios targets can describe relationships between each other and perform dependency analysis, which allows whole sections of the build process to be skipped if that target is up-to-date. For more information on targets, see MSBuild Targets.
Building with MSBuild
You run MSBuild from the command line by passing a project file to MSBuild.exe with the appropriate command line options. Command line options allow you to set properties, execute specific targets, and specify loggers. 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 on MSBuild command line options, see MSBuild Command Line Reference.
.gif "Security note") Security Note: |
|---|
Before you build a downloaded project, determine the trustworthiness of the code. MSBuild project files have the ability to execute tasks that can damage your system. |
Advanced concepts
MSBuild can be used for more advanced operations during builds, such as logging errors, warnings, and messages to the console or other loggers, performing dependency analysis on targets, and batching tasks and targets on item metadata. For more information on these advanced concepts, see MSBuild Advanced Concepts.
Visual Studio Integration
Visual Studio uses the MSBuild project file format to store build information about managed projects. Project settings added and changed through Visual Studio are reflected in the .*proj file that is generated for each project. Visual Studio uses a hosted instance of MSBuild to build managed projects, meaning that a managed project can be built in Visual Studio and from the command line (even without Visual Studio installed), with identical results. For more information on how Visual Studio uses MSBuild, see MSBuild Advanced Concepts.
See Also
Concepts
Overview of Logging in MSBuild
Visual Studio Integration (MSBuild)
MSBuild Project File Schema Reference