Brennan’s Blog

I have spent a good deal of time with MSBuild scripts the past couple of years as I have worked on various projects. As I have attempted to make these scripts bend to my wishes I have gradually improved the sample MSBuild script I carry along to each new project. In this series I will cover various ways to use MSBuild and include some tips on what you can do to make your scripts work better for you. But first, what is MSBuild?

The MSBuild utility was introduced with .NET 2.0 and is available with the runtime even if Visual Studio is not installed. It allows for build automation of most Visual Studio project types. Previously, a utility called NAnt was used as a build tool for .NET 1.1 which is modeled after Ant, a tool to build Java projects. The introduction of MSBuild as an official utility was very welcome among the development community as it provides close integration with the existing project and solution files created by Visual Studio. This close integration cuts down on the amount of detail necessary for the build scripts.

In some ways MSBuild is quite similar to the NAnt and Ant predecessors, such that the scripts are XML files representing Targets of execution with various Tasks within those Targets. And between Targets a dependency tree can be created to ensure certain Targets are completed before the called Target. That is all quite similar to NAnt and Ant. However, the way properties and lists are defined is quite different.

Properties are defined in the PropertyGroup element. You can simply add an arbitrary element and enclose the assigned value within that element. Viola! You have a property. What you will notice in Visual Studio is the first element inside the PropertyGroup is marked with a warning. This is simply due to the fact that Visual Studio does have schema support for the MSBuild format to provide Intellisense support and your new custom element is not recognized. You can safely ignore those warnings on property declarations. Below is an example of a PropertyGroup.

  <PropertyGroup>
    <ApplicationName>My Application</ApplicationName>
    <ApplicationVersion>1.2.8</ApplicationVersion>
    <ApplicationDirectory>ConsoleApplication</ApplicationDirectory>
 </PropertyGroup>

Defining lists is done within an ItemGroup element. You will want to use a list with a Task occasionally, such as copying a group of files to another folder. Below is an example of an ItemGroup.

<ItemGroup>
  <ZipFiles Include="$(ApplicationDirectory)\\bin\\$(Configuration)\\**\\*.*" Exclude="*.zip">
  </ZipFiles>
</ItemGroup>

See how the wildcard, **\*.*, is used. That defines all files below the defined directory. And the use of the properties is done with the dollar sign wrapped with parentheses.

To introduce some control in your MSBuild scripts you can set up conditionals on any element. Below is an example of how conditionals are used in nearly every MSBuild script.

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

What the above code block is doing is defaulting the values for the Configuration and Platform properties. These values are established because another PropertyGroup typically follows which then defines another set of properties based on the Configuration and Platform properties.

The last major piece to the MSBuild structure is the Tasks. The most common Tasks I use are MakeDir, RemoveDir, Copy and MSBuild. See below for an example.

<Target Name="Merge">
    <MakeDir Directories="$(PackagesFolder)" Condition="!Exists('$(PackagesFolder)')" />
    <Copy SourceFiles="$(ZipFilename)" DestinationFolder="$(PackagesFolder)" />
    <MSBuild Projects="$(ApplicationDirectory)\\MyApplication.csproj" Targets="Clean"></MSBuild>
</Target>

Since the general purpose of an build script is to generate and manage a large set of files, it is important to better understand the ItemGroup.

More Information:

• MSBuild Overview
• MSBuild Targets
• MSBuild Tasks

Next in this series, Item Groups.