5 Things Every .NET Developer Should Know About MSBuild

MSBuild (Microsoft Build Engine) is the magical orchestrator which jumps into action every time you hit F5 in Visual Studio. Its super powers range from compiling your project into executables, to transforming web config files. Therefore, in order to take advantage of the many features msbuild provides, let’s review the basics.

MSBuild Overview

Msbuild is the underlying technology used by Visual Studio to build and compile projects and solutions. It comes packaged with the dotnet framework so it’s very likely that you already have it on your machine.

msbuild location

Msbuild acts as an interpreter which reads an xml file (*.csproj,*.sln,*.msbuild) and executes the instructions inside. It is available on the command line, in visual studio and TFS.

MS Build overview for msbuild

1. Characteristics of a build file

Firstly, A build file is nothing but a simple XML document. Each build file must have the Project root node with an xmlns (XML Namespace) pointing to http://schemas.microsoft.com/developer/msbuild/2003 .

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  
</Project>

The PropertyGroup node is usually declared next in a build file. PropertyGroups are containers for properties. Properties allow you to declare variables that can be used later in the file.The example below shows a variable called Name with the value Sam declared in a property group.

<PropertyGroup>
    <Name>Sam</Name>
  </PropertyGroup>

ItemGroups are containers for files and they behave like an array. Items are like properties but they allow you to access metadata on that object. The Example below shows a property PicsPath defined which lists all the .jpg pictures in a folder. The item group defined below then lists those files.

<PropertyGroup>
    <PicsPath>c:\temp\pics\*.jpg</PicsPath>
  </PropertyGroup>
 <ItemGroup>
    <Pics Include="$(PicsPath)" />
  </ItemGroup>

A Target is a container for instructions. Each target has to have an associated task (function to invoke). Each Task is a .NET object which implements the interface ITask. An example of a task is to display a message to the console.

<Target Name="HelloWorld">
   <Message Text="Hello $(Name)" />
 </Target>

 

2. Hello World with MSBuild

Next is the basic Hello World example. The example below shows the creation of a simple build file which displays “Hello Sam”. A property name is declared with the value Sam. Next, the HelloWorld target is created with a message task.

Hello World Example for msbuild

Output

We can run the build file by running the following inside the Developer Command Prompt for VS 2017.

c:\Dev\Msbuild>msbuild HelloWorld.msbuild

Build output for msbuild

3. Referencing Declared Properties

Another important tip, is how to reference declared properties. A property is a scalar variable which consists of a key value pair. Properties are always created inside of PropertyGroups. After you declare a property you can reference that variable in properties,itemgroups, targets etc by using the dollar parenthesis notation.

Syntax :$(PROPERTYNAME)
Example : $(name)


<PropertyGroup>
<Name>Homer</Name>
<FullName>$(Name) Simpson</FullName>
</PropertyGroup>

In the example above, we declare a name Homer and reference that property in the FullName property by using $(Name).

4. Reference Declared Items

In addition,we can reference items and their associated data using the following notation

Syntax :
@(ITEMS->'%(METADATA)')
@(Pics->'%(ModifiedTime)')

5. Using a response file to pass in command line arguments to msbuild

Furthermore, MSBuild allows the use of numerous command line arguments. Some of the most common ones are below

  • /target:HelloWorld : Run the target HelloWorld when the build is run
  • /v:minimal : Set the logging to minimal
  • /p:Name=Lisa : Inject the value Lisa into the variable Name.

While it’s super convenient to be able to specify command arguments, it’s error prone and tedious. Response files allow you to place all your command arguments in the file and then just pass the name of the response file to msbuild. Here is an example

/target:HelloWorld,GoodbyeWorld
/v:diagnostic

The contents above would be saved in a file called helloworld.rsp.

c:\Dev\Msbuild>msbuild HelloWorld.msbuild @helloworld.rsp

Summary

In conclusion, MSBuild is a great tool for build automation. Understanding how MSBuild works gives us the ability to be creative in build automation and continuous delivery.