Thomas Ardal

This article gives a short introduction to the MSBuild tool.
Thanks to Joe Wass for correcting my bad english

MSBuild Basics

.NET 2.0 introduced a new tool called MSBuild. MSBuild is primarily used to build .NET applications, but can be used for other types of applications as well. From Windows Vista, MSBuild is distributed with Windows itself, making it a strong platform for implementing scripted application on non-developer PCs as well.

Before .NET 2.0, application were built by one or more of these strategies:

• Using the build menu from inside Visual Studio
• Using the devenv.exe process from the command line with some extra parameters
• Using a third-party tool like NAnt (which MSBuild is based on)

The drawback with the first two strategies was that it was hard to script. The drawback with the third solution was that two build environments had to be held in sync and maintained. .NET 2.0 Visual Studio projects are now implemented in the MSBuild language, but MSBuild has no dependencies on Visual Studio itself. MSBuild can in theory be implemented in files with any extension but a number of formats seem to be the supported standard from Microsoft: csproj, vbproj, vcproj, vjsproj, proj, .targets. The first four are different types of project files for Visual Studio, while the last two are new extensions which are either written by hand or with a tool knowing the MSBuild syntax. A few tools exist for this purpose. My personal opinion is that building in xml editor in Visual Studio is quite good for this purpose. A repeating question among MSBuild developers is if you should extend the files generated by visual studio with new stuff or whether you should write your own containing your home-made MSBuild scripts. My personal opinion is to let Visual Studio generate its own projects (example: csproj files) and create your home-made scripts in a .proj file with the same name as the project. I usually start the .proj file by implementing the three targets: Clean, Build and Rebuild, which basically just calls the similar targets in the .csproj file. This way you avoid updating an auto-generated file which you don’t have control over.

An MSBuild file is implemented in XML. The root element of an MSBuild XML file will always be a project containing target elements. It is possible to run multiple targets in a MSBuild file. When the MSBuild script is started from the command line, it takes a build file as parameter as well as the names of the targets, which should be executed.

A target is implemented as a sequential list of tasks. The tasks are executed in the order in which they are specified beneath the target element. Both targets and tasks can be dependant on each other.

This is an example of a very simple build file to build a .NET project:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="Build">
    <Message Text="Building msbuildintro" />
    <MSBuild Projects="msbuildintro.csproj" Targets="Build" />
  </Target>
</Project>

The example defines a project with the MSBuild namespace. Using the namespace helps you develop the build file in Visual Studio using Intellisense. The build file contains a single target named Build. This target contains two tasks: Message and MSBuild. Message outputs a message to the console and is used primarily for debug purposes. MSBuild runs a configurable number of targets on another build file. Because the .csproj file is also implemented in MSBuild we are able to call targets in the build file from the example build file. In this case we call the target Build in the .csproj file. All projects generated by Visual Studio automatically implements the Clean, Build and Rebuild targets. These targets are actually executed when you select the similar commands in the Build menu from within Visual Studio.

Properties

To be able to parameterise a build script, MSBuild has implemented properties. A property is a simple key/value type, which can be used from multiple locations in the scripts. Let’s look at an example using properties:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MyReleaseOutput>.\release</MyReleaseOutput>
  </PropertyGroup>
  <Target Name="Build">
    <Message Text="Building msbuildintro" />
    <MSBuild Projects="msbuildintro.csproj" Targets="Build" />
  </Target>
  <Target Name="Release" DependsOnTargets="Build">
    <MakeDir Directories="$(MyReleaseOutput)" />
    <Copy SourceFiles=".\bin\debug\msbuildintro.exe" DestinationFolder="$(MyReleaseOutput)"  />
  </Target>
</Project>

The example defines a property defined in a property group. Properties can be defined both outside and inside scope of a target. When a property is defined like in this example, the value of the property is assigned before executing the actual targets. In the example I define a property called MyReleaseOutput and add the value .\release. In this example I have added two targets as well: Build and Release. The Build target is similar to the one specified in the previous example, while the Release target is new. The Release target introduces a new attribute called DependsOnTargets, which is the way to define dependencies between targets in MSBuild. In this case we tell MSBuild to run the Build target before running the Release targets. If you run the Build target manually before running the Release target, the Build target is run only once.

The release target introduces two new tasks as well: MakeDir which (well you guessed it) creates a new directory and Copy, which copies on or more files from A to B. MakeDir contains a single attribute, defining the path of the new directory.
In this example that path is the value of the MyReleaseOutput property. Notice the use of the $(propertyname) syntax here. $() is used to reference properties in MSBuild. The copy task in our example points out a single file and the destination folder where this file should be copied to, when executing the Release target. The $(MyReleaseOutput) used is again replaced by the value of this property.

Items

The example above copied a single file from one directory to another. This can certainly be useful in many situations but sometimes this is simply not flexible enough. This is were items comes in. An item gives the possibility of creating dynamic lists of, for instance, file names. Let’s start by looking at an example:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MyReleaseOutput>.\release</MyReleaseOutput>
  </PropertyGroup>
  <ItemGroup>
    <MyReleaseFiles Include=".\bin\debug\*.*" />
  </ItemGroup>
  <Target Name="Build">
    <Message Text="Building msbuildintro" />
    <MSBuild Projects="msbuildintro.csproj" Targets="Build" />
  </Target>
  <Target Name="Release" DependsOnTargets="Build">
    <MakeDir Directories="$(MyReleaseOutput)" />
    <Copy SourceFiles="@(MyReleaseFiles)" DestinationFolder="$(MyReleaseOutput)"  />
  </Target>
</Project>

We start by defining an ItemGroup outer scope of a target. This means that the content is calculated before actually running any targets. In this example I define an ItemGroup containing a single item called MyReleaseFiles. The item contains a single attribute called Include, which acts as a filter for the generated file list: in this case, all files beneath the bin\debug directory. I use this item in the copy task beneath the Release target to indicate which files should be copied when doing a release.

The Include filter decides which file to include. We also have the possibility to specify an Exclude filter. The following example shows how:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MyReleaseOutput>.\release</MyReleaseOutput>
  </PropertyGroup>
  <ItemGroup>
    <MyReleaseFiles Include=".\bin\debug\*.*" Exclude=".\bin\debug\*vshost.exe" />
  </ItemGroup>
  <Target Name="Build">
    <Message Text="Building msbuildintro" />
    <MSBuild Projects="msbuildintro.csproj" Targets="Build" />
  </Target>
  <Target Name="Release" DependsOnTargets="Build">
    <MakeDir Directories="$(MyReleaseOutput)" />
    <Copy SourceFiles="@(MyReleaseFiles)" DestinationFolder="$(MyReleaseOutput)"  />
  </Target>
</Project>

I added an Exlude attribute to my MyReleaseFiles item. The exclude in this examples excludes all files beneath the bin\debug directory which end in vshost.exe. An item containing both Include and Exclude will be generated by taking all the files specified in the Include and subtracting the files specified in the Exlude.

The last two examples of using items are actually not that useful because the content for the MyReleaseFiles item is generated before running the actual targets. On a new checkout or after a clean, no files exist in the bin\debug directory meaning that the generated file list will therefore be completely empty. Bummer! Let us fix the example. We define a new item inside the scope of a target instead:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MyReleaseOutput>.\release</MyReleaseOutput>
  </PropertyGroup>
  <Target Name="Build">
    <Message Text="Building msbuildintro" />
    <MSBuild Projects="msbuildintro.csproj" Targets="Build" />
  </Target>
  <Target Name="Release" DependsOnTargets="Build">
    <MakeDir Directories="$(MyReleaseOutput)" />
    <CreateItem Include=".\bin\debug\*.*" Exclude=".\bin\debug\*vshost.exe">
      <Output TaskParameter="Include" ItemName="MyReleaseFiles"/>
    </CreateItem>
    <Copy SourceFiles="@(MyReleaseFiles)" DestinationFolder="$(MyReleaseOutput)"  />
  </Target>
</Project>

I moved the MyReleaseOutput item inside the Release target. This is done using the CreateItem task. The CreateItem task creates a new item on the fly which means that the content is generated at the point in time when the CreateItem task is executed. Notice that the CreateItem task contains an Output element. The Output element is used in a lot of different places in MSBuild where a target is able to output some data. In this case is use the ItemName attribute to define the name from the previous example.

Anyone still reading? If you have read this far, you derserve a little prize:

Conditions

Besides the CreateItem task in a previous example, our build scripts have been very static until now. This can be sufficient for a lot of projects but sometimes you need slightly more flexible build scripts. A feature for fulfilling this in MSBuild is called Conditions. A condition in MSBuild is not that different to a condition in other software languages. It is a possibile, for instance, to make more flexible structures to avoid running targets and/or tasks when certain conditions are met. You can define conditions on all targets and almost all tasks. Lets check out another example:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MyReleaseOutput>.\release</MyReleaseOutput>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
  </PropertyGroup>
  <Target Name="Build">
    <Message Text="Building msbuildintro $(Configuration)" />
    <MSBuild Projects="msbuildintro.csproj" Targets="Build" />
  </Target>
  <Target Name="Release" DependsOnTargets="Build" Condition="$(Configuration) == 'Release'">
    <MakeDir Directories="$(MyReleaseOutput)" />
    <CreateItem Include=".\bin\$(Configuration)\*.*" Exclude=".\bin\$(Configuration)\*vshost.exe">
      <Output TaskParameter="Include" ItemName="MyReleaseFiles" />
    </CreateItem>
    <Copy SourceFiles="@(MyReleaseFiles)" DestinationFolder="$(MyReleaseOutput)" />
  </Target>
</Project>

I added a lot of new stuff here. But of course you are already quite an MSBuild expert, so I think you will manage. First of all, I have added a new property named Configuration. This property contains a condition attribute, which determines the value of the property at runtime. If the Configuration property has not been set upfront, the value of the attribute is set to Debug. Properties can be set upfront by using a special syntax on the command line:

Msbuild.exe build.proj /p:Configuration=Debug /t:release

More new stuff. I changed all references to the debug, with the value of the new Configuration property. This means that I am now able to run the script in both Debug and Release mode.

The last new addition is the condition attribute on the release target. This condition examines if the value of the Configuration property is Release and only allows execution of the Release target if this condition is true.

Frequently Used Tasks

CallTarget – Executes another target inside the current build file. Used where a target needs to call another target at a specific place inside the target itself. If the target were just dependant on the other target being executed, we would use the DependsOnTargets attribute instead.

Copy – We already saw this task in action. Copies one or more files from A to B.

CreateItem – Create dynamic items.

CreateProperty – Create dynamic properties.

Delete – Deletes on or more files.

Exec – Executes an external process. This is typically used to executed external tools, which did not implement MSBuild targets themself.

MakeDir – Creates one or more directories.

Message – Outputs a message to the console.

MSBuild – Executes one or more targets in an external MSBuild file.

RemoveDir – Removes one or more directories.

And there are a lot more.

Custom MSBuild Tasks

It is possible to write your own MSBuild tasks. This can be extremely useful if you want to integrate some of your own tools with MSBuild or if you need to do stuff which is not yet supported by MSBuild. The following example shows how to write a simple addition task:

using System;
using Microsoft.Build.Utilities;
using Microsoft.Build.Framework;
namespace MyTasks
{
  public class AddTask : Task
  {
    private int number1;
    [Required]
    public int Number1
    {
      get { return number1; }
      set { number1 = value; }
    }
    private int number2;
    [Required]
    public int Number2
    {
      get { return number2; }
      set { number2 = value; }
    }
    private int sum;
    [Output]
    public int Sum
    {
      get { return sum; }
      set { sum = value; }
    }
    public override bool Execute()
    {
      try
      {
        sum = number1 + number2;
      }
      catch (ArithmeticException e)
      {
        Console.WriteLine("Error occured during addition: {0}", e.Message);
        return false;
      }
      return true;
    }
  }
}

I start by defining the AddTask class which extends the Task class from the MSBuild API. By extending this task, I don’t need to worry about implementing conditions etc.
I defined two properties which act as input variables to the addition task: Number1 and Number2. Both properties are marked with the Required attribute which tells the script to fail if they are not specified. An output property is added as well. The value of this property will be available within the build script. Let’s see how to use this new and fancy task:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <UsingTask TaskName="MyTasks.AddTask" AssemblyFile=".\AddTask.dll"/>
  <Target Name="Addition">
    <AddTask Number1="10" Number2="12">
      <Output TaskParameter="Sum" PropertyName="CalculatedSum" />
    </AddTask>
    <Message Text="10 + 12 = $(CalculatedSum)" />
  </Target>
</Project>

TODO: Describe inline tasks (http://msdn.microsoft.com/en-us/library/dd722601.aspx).

Because my AddTask in an external task not built into the MSBuild framework, I use the UsingTask element to reference it. The name of the task as well as the assembly name is specified.

The Addition target uses the AddTask with the two Number properties as attributes. The Output element copies the result of the task to a property called CalculatedSum. This property is accessible in the Message task for output on the console.

You just implemented your first custom MSBuild task. Pretty easy, right?

Generic Targets

Once in a while a question pops up in different forums: How do I parameterize a common part of my script, making it possible to use it from different targets? This is a great question. We don’t want to have the same lines of code spread around our build script, making it longer than necessary and complex to maintain. MSBuild provides the CallTarget task, which executes another target inside the current build file. Unfortunately there is no way to parameterize the CallTarget task, making it unusable for anything other than simple situations where needed tasks are 100% identical.

Let’s look at and example where we have two targets with some identical tasks:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="Target1">
    <Message Text="Hello World from Target1" />
  </Target>
  <Target Name="Target2">
    <Message Text="Hello World from Target2" />
  </Target>
</Project>

In the example we define two targets: Target1 and Target2. You will probably notice that the targets look very similar. The only difference is the text inside the Message task. This is a simple example of the problem and of course changing the text in both message tasks would be fairly simple. But you probably understand the problem here: It would be nice to refactor the targets (let’s call it “Extract Target”), so that the Hello World text will only be specified once. First of all we need to move the common tasks to a new target:

<Target Name="PrintMessage">
  <Message Text="Hello World from X" />
</Target>

Note that the replaced part of the Text with the X. Now we need to call this target, making sure that X will be replaced with the correct string. For this purpose we use another task called MSBuild. The MSBuild task was originally produced to be able to call targets inside other MSBuild scripts. The great thing about the MSBuild task is that it has the capability to receive properties. In order to call our PrintMessage target and print the correct string, we parameterize the target like this:

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="Target1">
    <MSBuild Projects="$(MSBuildProjectFile)" Targets="PrintMessage" Properties="Caller=Target1"/>
  </Target>
  <Target Name="Target2">
    <MSBuild Projects="$(MSBuildProjectFile)" Targets="PrintMessage" Properties="Caller=Target2"/>
  </Target>
  <Target Name="PrintMessage">
    <Message Text="Hello World from $(Caller)" />
  </Target>
</Project>

We use the MSBuild tasks in both Target1 and Target2. The $(MSBuildProjectFile) is a built-in property in MSBuild, which returns the filename of the current build file. What we do here is that we call the PrintMessage task on this. The properties attribute specify a single property named Caller. Multiple properties can be specified inside this attribute by separating them with a semicolon. In the PrintMessage task we simply print the message with the Caller property specified inside the Text attribute.

This is the second and last part of my blog post titled 10 Tips to Optimize Your Time. If you haven’t read part 1, go ahead!

Only plan one visit every weekend if possible

We have a large family.  Both my wife and I are children of divorced parents and therefore have four sets of parents/grandparents.  The thing is, those grandparents want to see their grandson (and us) ALL the time.  Keeping grandparents in restraints has been a major issue for us.  We try to see family on the weekends and always only plan one of the days.  This gives us the other day to concentrate on our son and when he’s tucked in, coding time starts!

Pay someone to do tedious work

This is something that I’m not good at, but I keep trying to find new ways of outsourcing all of those tedious tasks.  Why not pay someone to clean your house?  Don’t wash the car yourself.  The car wash is a great alternative and you can catch up on your e-mail or Twitter while the old, dusty car gets a makeover.  Admittedly, we (maybe it’s I) drink a lot of soda.  Nothing sucks more than putting all of those empty cans in the can recycler.  I’m planning to make a deal with one of the kids on the street, that he will get the bottle deposit if he comes by and empties my shed for empty bottles and cans once in a while.  The point here is that people in the IT business make enough money to pay someone to do all of those tasks that you don’t like.  Just do it!

Buy work you can’t do yourself

It’s amazing what people do for money nowadays.  Before having my son, I would gladly sit down and scan hundreds of old photos, which takes a long time.  These days, I just send them for scanning in Morocco.  Yes this isn’t free, but doing manual work like that is time consuming and boring.  Last year, I started experimenting with buying help on fiverr.com.  The first couple of months weren’t a great success, but after spending a few more fiverrs, I ended up knowing some pretty talented people, willing to do stuff for $5.  I use fiverr for proof reading, graphics, copy-paste work and other tasks, which I can’t do myself or that I don’t bother to learn.

Don’t do stuff which never leaves your machine

Doing websites or code in general, which only lives on your machine, is fun if you want to learn something.  Doing stuff that other people see either through a website or GitHub is more fun.  I never write code that doesn’t end up on the internet somehow.  I have a principle that everything I do should be monetizable somehow.  I always have ads on my blogs and try monetizing everything from .NET assemblies to Chrome plugins.  I don’t even earn 1 % of my day-job paycheck each month, but the feeling of earning enough to cover your expenses on fiverr and hosting is enough to drive me. The point here is, that doing personal stuff quickly becomes a time consumer, cause you don’t get any feedback and you could have used your time on something else.

Buy gifts for your wife/girlfriend

If your better half doesn’t work in IT, he/she probably doesn’t understand that your job can also be your hobby.  My wife has become very understanding over the years.  A technique you can use, if you aren’t as lucky as me, is to buy time consuming gifts for the other part.  The Sex and the City boxset is a great example of how to make your wife happy for several hours.  Do not, and I must stress, DO NOT give her the impression that you want to see the damn thing with her though Make sure to spend time with your other half, but make an arrangement for one or two nights a week, where you can get into the zone without being interrupted.

Happy coding!

A couple of people have asked me how I find time to do all of my hobby projects while having a house, a wife, a son, family and friends all at the same time.  The answers I gave inspired me to write this blog post.  While I’m extremely bad at focusing on a single coding projects, I’ve done a lot to optimize the time I actually have for all my experimental coding.  This the the following blog post is an attempt to explain some of the things I do to find some extra hours.

Minimize the time you talk on the phone

Face it!  Nobody needs to talk to their mom every day.  My wife thinks she does, but when I overhear their conversations, it’s always superficial small talk.  I talk to my parents once a week on a fixed time.  Agreeing on the time of the call makes it possible to plan your night and not feel frustrated when your mom calls you while you’re “in the zone” to tell you about her yoga progress.  Also, turning on the phone’s silent option keeps you from talking to sales people and other annoying disturbances.  If you’re the type of person who needs to talk to your friends all the time, meet up with them once in a while instead of calling them each night.  I chat a lot with my more neardy friends, which works great because I can code on my other screen in my dual screen setup while chatting on the other.

No weekly scheduled events

I never accept weekly scheduled events.  When someone asks me if I want to play badminton with them every Tuesday and Thursday night, I simply say no.  Playing once in a while is fun and you should definitely do it.  However, promising your time two nights a week is a major timer spender. The point here is only do it if you’re really into it!

Don’t watch live TV

A couple of years ago I watched a lot of live TV.  A LOT!  My wife and I watched everything from the news to programs titled, “100 Greatest Hollywood Screw-Ups”.  After we had our son, we canceled the cable TV and now only have something like 2 watchable channels.  This is probably the best decision we’ve made in years.  We still watch movies and shows, but always on DVD or web content.  This means that we can sit down and watch five episodes of a show in one night without being bothered by commercials and other time consuming stuff.

Optimize your shopping

When we lived in an apartment in the city 4 years ago, we discussed what we would have for dinner every day and went to the food store to buy it.  Doing weekly meal planning, gave us something like an hour extra everyday but on Monday when we do all of our shopping for the week.  Shopping for the week doesn’t take much longer than shopping for 1 or 2 days.  Also, I buy must of my stuff online from hardware to clothes.

Do stuff with your kids

I’ve heard a lot of people with kids complaining about too few hours to code.  These people typically wait to do stuff like cleaning and shopping until the kids are asleep and for that reason, they don’t starts coding until 10 in the evening.  While we love to spend time with our son, we also treasure the time when he is tucked in.  People are too afraid to admit this, but we all need time for ourselves.  We do a lot of stuff at home with our son and he also joins one of use shopping each week.  He loves it!

In the next post I reveal the final 5 tips to optimize your time.