By Steve Andrews

Introduction

For many developers, the development process is not complete when the software has been written. There are typically still many build, configuration and deployment tasks to attend to. Yet with the frequency with which these tasks are performed, a lot of them are still performed manually using batch scripts and one-off utilities. During the immediate project these ancillary tasks may seem unimportant, but over the life of a project and the course of multiple projects they become rather significant. This is because they are very tedious and repetitive to write, error-prone, and full of hard-coded variables.

Today there is a better solution: Microsoft Build, or MSBuild. While MSBuild has been part of the .NET Framework since version 2.0, the adoption rate among developers has very low, mainly because many developers are not aware of the power and flexibility that MSBuild contains. This article will cover the various aspects of MSBuild, and teach you how you can utilize it to make project build, configuration, and deployment much easier.

The Basics

MSBuild is Microsoft’s XML-based build automation language. Microsoft has adopted MSBuild internally for a lot of their projects. In fact, most of the managed project files, like .csproj and .vbproj are actually MSBuild project files and as such utilize the MSBuild architecture to build your projects and solutions.

Being an XML-based language, it is important to understand the main structural elements of the underlying schema. The four main structural elements that make up MSBuild are properties, items, targets, and tasks. The basic structure might look like this:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        [properties]
    </PropertyGroup>
    <ItemGroup>
        [items]
    </ItemGroup>
    <Target Name="Default">
        [tasks]
    </Target>
</Project>

Tasks perform the actions of the build process and utilize items and properties. There are many common tasks built-in, too.

Targets are simply task containers. By using the DefaultTargets and InitialTargets tags on the Project node, you can also specify which targets are run by default, and which will be run prior to any other execution. To enable reusability, you can encapsulate custom targets inside a .targets file for parameterized execution, much the same as Visual Studio project files.

Properties are name-value pairs which allow you to define settings to configure the MSBuild project. You can specify any name you wish for a property. The property is referenced using the $(propertyname) syntax. For example, in the following example, the property MyProperty is referenced in the Message task:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <MyProperty>World</MyProperty>
    </PropertyGroup>
    <Target Name="Default">
        <Message Text="Hello $(MyProperty)!" />
    </Target>
</Project>

Items define collections of files and are used as input to tasks, and are referenced using the %(itemname) syntax. For example, in the following example, the Compile items are referenced in the Message task:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <MyProperty>World</MyProperty>
    </PropertyGroup>
    <Target Name="Default">
        <Message Text="Hello $(MyProperty)!" />
    </Target>
</Project>

You can view the core MSBuild schema document, located by default at: %FrameworkDir%/MSBuild/Microsoft.Build.Core.xsd

Setting Up The Environment

While it is possible to create MSBuild projects in a text editor such as Notepad, you would do well to use Visual Studio since Visual Studio can provide color coding and IntelliSense. Before creating your first MSBuild project, there are a couple setup tasks you should perform in Visual Studio.

1. In Visual Studio, go to Tools | Options | Text Editor | File Extension.
2. In the form provided, enter proj for the extension, and select XML Editor from the Editor drop down. Click Add.
3. Go to Tools | External Tools…
4. Click Add.
5. Enter MSBuild Current for the title,
6. Enter C:\WINDOWS\Microsoft.NET\Framework\v3.5\MSBuild.exe for the Command
7. Enter $(ItemPath) /nologo for the Arguments
8. Enter $(ItemDir) for the Initial directory.
9. Check the Use Output window checkbox
10. Your settings should look like this:
11. Click OK.

You are now ready to work with MSBuild project files within Visual Studio. To edit an open project in Visual Studio, you can right-click on the project node in the Solution Explorer tool window, choose Unload Project, right-click again, and choose Edit <project file name>…. When you are finished editing the project file, you can right-click one last time and choose Reload Project.

Your First MSBuild Project

As is common in many introductions lessons, we are going to create a basic Hello World MSBuild project by performing the following steps:

1. Open Visual Studio
2. Create a new XML file and name it Test.proj.
3. In the XML file, paste the following text:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Default">
        <Message Text="Hello World!" />
    </Target>
</Project>

1. Using the MSBuild Current command we created earlier (Tools | MSBuild Current), execute the project file.
2. You should see the following text in the output window:

Project "Test.proj" on node 0 (default targets).
  Hello World!
Done Building Project "Test.proj" (default targets).

Build succeeded.
   0 Warning(s)
   0 Error(s)

Congratulations, you have just executed your first custom MSBuild project.