he 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 article provides brief overviews of:
Basic MSBuild Project Elements
- 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.
- Walkthrough Sample application / Logger.
MSBuild introduces a new XML-based project file format that is simple to understand, easy to extend, and fully supported (see Figure 1
). The MSBuild project file format lets developers describe what items need to be built as well as how they need to be built with different platforms and configurations. In addition, developers can author reusable build rules that can be factored into separate files, which can help make builds perform consistently across different projects.
|Figure 1. Project Files in Solution Explorer: In this figure, you can see the MSBuild project (.proj) files for the sample MSBuildLogger project.|
You declare items 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:
<Compile Include = "testfile1.cs"/>
<Compile Include = " testfile2.cs"/>
That code fragment is typical of a build file: Individual items represent inputs to the build system. Items are grouped into item collections in elements with a collection name that you define (e.g. "Compile" in the preceding code). You can then use these item collections as parameters for tasks
, which use the individual items contained in the collection to perform the steps of the build process.
|Figure 2. Various MSBuild Project Items: The circled code in the figure shows several MSBuild project items.|
You reference item collections throughout the project file using the syntax @(ItemCollectionName)
. You can create items using wildcards, and items may contain additional metadata for more advanced build scenarios (see Figure 2
An MSBuild file can also hold properties, which represent key/value pairs that you can use to configure builds. You declare a property by creating an element with the property name as a child of a PropertyGroup
element (see Figure 3
). For example, the following code creates a property named BuildDir
with a value of TestBuildDir
|Figure 3. MSBuild Properties: The circled code in the figure shows a property named "appname" with a value of "TestBuildApp."|
You can reference properties throughout the project file using the syntax $(PropertyName)
There are several differences in the way MSBuild treats properties and items. Items are stored in collections where each item had the same element name, while property names are unique. Properties contain a single scalar value. You cannot remove items from item collections, but properties can have their values changed after they are defined. Items can contain metadata and can use the %(ItemMetadata)
notation, while properties cannot.
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. Tasks can be stored, shared, and reused by different developers in different projects.
You can write your own task by authoring a managed type that implements the ITask interface. You can then map the custom task to MSBuild with the Using
task element. 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
|Figure 4. Executing a Task: This circled code executes the CSC task, passing the attributes as parameters to create an executable.|
To execute a task in an MSBuild project file, create an element with the name of the task as a child of a Target
element. Tasks usually accept parameters, which you specify as attributes of the element. You can use MSBuild item collections and properties 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. Figure 4
shows the CSC task creating an executable that uses attributes to pass several values.
Targets group tasks together in a specific order and expose sections of the project file as entry points into the build process. It's generally best to group targets into logical sections to allow for expansion and increase readability. By separating the build steps into many targets you can call the grouped steps from other targets without having to copy that section of code into each target.
You declare targets in the project file with the Target
element. For example, the following code creates a target named Compile
<Csc Sources="@(Compile)" />