msbuildshellex Wiki & Documentation Rss Feed

Updated Wiki: Home

ThomasArdal — Wed, 05 Nov 2008 07:10:46 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Project Description

News

November 5, 2008

Which new features would you like to see in MSBuildShellExtension? Comment this page or create a new discussion/issue.

May 9, 2008
As you propably noticed, I haven't had a lot of time updating this site or the project recently. This is caused by:

1. I use MSBuildShellExtension each day, and it works pretty good already.
2. I'm working on a lot of other ideas.
3. I do a lot of UI code at my job, so it isn't really that fun coding UI in my sparetime.
4. The weather is GREAT in Denmark right now!

So if any of you guys wan't to help extending MSBuildShellExtension in the future, please send me a mail.

March 1, 2008 - MSBuildShellExtension 1.1.2
A new bugfix release has seen the light of day. Actually this small update contains more than meets the eye. Among other new features, .NET 3.5 is now supported!

November 25, 2007 - Msbuildshellextension 1.1.1
The 1.1.1 release is out. This release contains some bugfixes on the 1.1.0 release as well as some minor changes.

November 14, 2007 - Msbuildshellextension 1.1.0
The 1.1.0 is out of beta! Remember to uninstall your existing version of MSBuildShellExtension before installing, due to the change of installer technology. Happy building!

November 07, 2007 - Msbuildshellextension 1.1.0 Beta1
The 1.1.0 release of MSBuildShellExtension will arrive shortly. Until then, download and try the beta! Please report any bugs at http://www.codeplex.com/msbuildshellex. Happy testing!

Updated Wiki: MSBuild Tutorial

ThomasArdal — Fri, 03 Oct 2008 10:19:22 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

This page gives a short introduction to the MSBuild tool. The tutorial is protected under copyright law and may not be published without permission from the MSBuildShellExtension coordinators at the CodePlex site.

Thanks to Joe Wass for correcting my bad english :o)

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

.NET 2.0 contains 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>

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.

Links

The MSBuild documentation is actually quite good and a must for all serious MSBuild developers: http://msdn2.microsoft.com/en-us/library/wea2sca5(VS.80).aspx

A lot of different tools for handling MSBuild files exist. I haven't been able to find a tool that makes it possible to run build scripts from within Visual Studio. You could start by installing the MSBuildShellExtension tool from: MSBuildShellExtension.

Besides the build in tasks in MSBuild, there is a great community project, implementing a lot of nice tasks not implemented by Microsoft. Targets for search and replace, zipping, sending out mails, modifying subversion etc., can be found here: http://msbuildtasks.tigris.org/

Updated Wiki: MSBuild Tutorial

ThomasArdal — Wed, 23 Jul 2008 11:59:52 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

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)

<?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>

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>

Items

<?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>

<?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>

<?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>

Conditions

<?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>

Frequently Used Tasks

Custom MSBuild Tasks

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;
    }
  }
}

<?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>

Generic Targets

<?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>

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

<?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>

Updated Wiki: MSBuild Tutorial

ThomasArdal — Wed, 23 Jul 2008 11:59:25 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

This page gives a short introduction to the MSBuild tool. The tutorial is protected under copyright law and may not be published without permission from the MSBuildShellExtension coordinators at the CodePlex site.
Thanks to Joe Wass for correcting my bad english :o)

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

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)

<?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>

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>

Items

<?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>

<?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>

<?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>

Conditions

<?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>

Frequently Used Tasks

Custom MSBuild Tasks

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;
    }
  }
}

<?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>

Generic Targets

<?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>

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

<?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>

Updated Wiki: MSBuild Tutorial

ThomasArdal — Wed, 23 Jul 2008 11:56:19 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

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)

<?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>

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>

Items

<?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>

<?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>

<?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>

Conditions

<?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>

Frequently Used Tasks

Custom MSBuild Tasks

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;
    }
  }
}

<?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>

Generic Targets

<?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>

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

<?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>

UPDATED WIKI: Home

ThomasArdal — Fri, 09 May 2008 18:05:33 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Project Description

News

May 9, 2008
As you propably noticed, I haven't had a lot of time updating this site or the project recently. This is caused by:

1. I use MSBuildShellExtension each day, and it works pretty good already.
2. I'm working on a lot of other ideas.
3. I do a lot of UI code at my job, so it isn't really that fun coding UI in my sparetime.
4. The weather is GREAT in Denmark right now!

So if any of you guys wan't to help extending MSBuildShellExtension in the future, please send me a mail.

March 1, 2008 - MSBuildShellExtension 1.1.2
A new bugfix release has seen the light of day. Actually this small update contains more than meets the eye. Among other new features, .NET 3.5 is now supported!

November 25, 2007 - Msbuildshellextension 1.1.1
The 1.1.1 release is out. This release contains some bugfixes on the 1.1.0 release as well as some minor changes.

November 14, 2007 - Msbuildshellextension 1.1.0
The 1.1.0 is out of beta! Remember to uninstall your existing version of MSBuildShellExtension before installing, due to the change of installer technology. Happy building!

November 07, 2007 - Msbuildshellextension 1.1.0 Beta1
The 1.1.0 release of MSBuildShellExtension will arrive shortly. Until then, download and try the beta! Please report any bugs at http://www.codeplex.com/msbuildshellex. Happy testing!

UPDATED WIKI: Home

ThomasArdal — Thu, 06 Mar 2008 19:20:29 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Project Description

News

March 1, 2008 - MSBuildShellExtension 1.1.2
A new bugfix release has seen the light of day. Actually this small update contains more than meets the eye. Among other new features, .NET 3.5 is now supported!

November 25, 2007 - Msbuildshellextension 1.1.1
The 1.1.1 release is out. This release contains some bugfixes on the 1.1.0 release as well as some minor changes.

November 14, 2007 - Msbuildshellextension 1.1.0
The 1.1.0 is out of beta! Remember to uninstall your existing version of MSBuildShellExtension before installing, due to the change of installer technology. Happy building!

November 07, 2007 - Msbuildshellextension 1.1.0 Beta1
The 1.1.0 release of MSBuildShellExtension will arrive shortly. Until then, download and try the beta! Please report any bugs at http://www.codeplex.com/msbuildshellex. Happy testing!

October 19, 2007 - Msbuild Profiler
Remember to checkout my new project MSBuild Profiler. MSBuild Profiler is a performance measurement and optimizer tool for MSBuild scripts. MSBuild Profiler

UPDATED WIKI: Home

ThomasArdal — Thu, 06 Mar 2008 19:19:01 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Project Description

MSBuildShellExtension lets you build .NET projects without ever opening Visual Studio or the command prompt. MSBuild targets can be executed from your favourite file system tool like Windows Explorer or Total Commander. The possibility to extend MSBuildShellExtension with your own targets and editors, makes it a very flexible and useful tool for all .NET developers.

News
March 1, 2008 - MSBuildShellExtension 1.1.2
A new bugfix release has seen the light of day. Actually this small update contains more than meets the eye. Among other new features, .NET 3.5 is now supported!

November 25, 2007 - Msbuildshellextension 1.1.1
The 1.1.1 release is out. This release contains some bugfixes on the 1.1.0 release as well as some minor changes.

November 14, 2007 - Msbuildshellextension 1.1.0
The 1.1.0 is out of beta! Remember to uninstall your existing version of MSBuildShellExtension before installing, due to the change of installer technology. Happy building!

November 07, 2007 - Msbuildshellextension 1.1.0 Beta1
The 1.1.0 release of MSBuildShellExtension will arrive shortly. Until then, download and try the beta! Please report any bugs at http://www.codeplex.com/msbuildshellex. Happy testing!

October 19, 2007 - Msbuild Profiler
Remember to checkout my new project MSBuild Profiler. MSBuild Profiler is a performance measurement and optimizer tool for MSBuild scripts. MSBuild Profiler

UPDATED WIKI: Home

ThomasArdal — Thu, 06 Mar 2008 19:18:11 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Project Description

MSBuildShellExtension lets you build .NET projects without ever opening Visual Studio or the command prompt. MSBuild targets can be executed from your favourite file system tool like Windows Explorer or Total Commander. The possibility to extend MSBuildShellExtension with your own targets and editors, makes it a very flexible and useful tool for all .NET developers.

News
March 1, 2008 - MSBuildShellExtension 1.1.2
A new bugfix release has seen the light of day. Actually this small update contains more than meets the eye. Among other new features, .NET 3.5 is now supported!

November 25, 2007 - Msbuildshellextension 1.1.1
The 1.1.1 release is out. This release contains some bugfixes on the 1.1.0 release as well as some minor changes.

November 14, 2007 - Msbuildshellextension 1.1.0
The 1.1.0 is out of beta! Remember to uninstall your existing version of MSBuildShellExtension before installing, due to the change of installer technology. Happy building!

November 07, 2007 - Msbuildshellextension 1.1.0 Beta1
The 1.1.0 release of MSBuildShellExtension will arrive shortly. Until then, download and try the beta! Please report any bugs at http://www.codeplex.com/msbuildshellex. Happy testing!

October 19, 2007 - Msbuild Profiler
Remember to checkout my new project MSBuild Profiler. MSBuild Profiler is a performance measurement and optimizer tool for MSBuild scripts. MSBuild Profiler

UPDATED WIKI: Home

ThomasArdal — Thu, 06 Mar 2008 19:14:18 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Project Description

MSBuildShellExtension lets you build .NET projects without ever opening Visual Studio or the command prompt. MSBuild targets can be executed from your favourite file system tool like Windows Explorer or Total Commander. The possibility to extend MSBuildShellExtension with your own targets and editors, makes it a very flexible and useful tool for all .NET developers.

News
November 25, 2007 - Msbuildshellextension 1.1.1
The 1.1.1 release is out. This release contains some bugfixes on the 1.1.0 release as well as some minor changes.

November 14, 2007 - Msbuildshellextension 1.1.0
The 1.1.0 is out of beta! Remember to uninstall your existing version of MSBuildShellExtension before installing, due to the change of installer technology. Happy building!

November 07, 2007 - Msbuildshellextension 1.1.0 Beta1
The 1.1.0 release of MSBuildShellExtension will arrive shortly. Until then, download and try the beta! Please report any bugs at http://www.codeplex.com/msbuildshellex. Happy testing!

October 19, 2007 - Msbuild Profiler
Remember to checkout my new project MSBuild Profiler. MSBuild Profiler is a performance measurement and optimizer tool for MSBuild scripts. MSBuild Profiler

UPDATED WIKI: Manual

ThomasArdal — Sat, 01 Mar 2008 09:09:46 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Manual

This short manual tries to explain the basic concepts in MSBuildShellExtension.

Editor

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Editor icon.
Select the New button.
Type a name for the external tool in the Title textbox.
Select the Default checkbox, if this tool should be used as the external tool for opening source files from within the error list window.
Add the path to the external tool in the Target and arguments textbox. The external tool should as a minimum support a command line parameter for specifying the file containing error/warning. You can use the Variables button to insert different types of variables in the Target and arguments textbox.
Select the Add button.
Select the Save button.

Example:

Targets

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Targets icon.
Select the New button.
Type a name for the target in the Title textbox.
Type the name of the target. This is the target name as specified in the MSBuild file.
Select a verbosity for the target in the Verbosity combobox.
Select the configuration for the target in the Configuration combobox.
Unselect the Show error list checkbox, if you don't want to show the error list window when executing builds through MSBuild Shell Extension.
Select the Add button.
Select the Save button.

Example:

Extensions

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Extensions icon.
Select the New button.
Type in the file extension in the File extension textbox. The file extension should not contain a '.' before the extension name.
Select the MSBuild version for this extension.
Select the Targets which should be enabled for the new file extension. Each target selected, results in an additional menuitem at the context menu of the specified file extension.
Select the Add button.
Select the Save button.

Example:

UPDATED WIKI: Manual

ThomasArdal — Sat, 01 Mar 2008 09:08:11 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Manual

This short manual tries to explain the basic concepts in MSBuildShellExtension.

Editor

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Editor icon.
Select the New button.
Type a name for the external tool in the Title textbox.
Select the Default checkbox, if this tool should be used as the external tool for opening source files from within the error list window.
Add the path to the external tool in the Target and arguments textbox. The external tool should as a minimum support a command line parameter for specifying the file containing error/warning. You can use the Variables button to insert different types of variables in the Target and arguments textbox.
Select the Add button.
Select the Save button.

Example:

Targets

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Targets icon.
Select the New button.
Type a name for the target in the Title textbox.
Type the name of the target. This is the target name as specified in the MSBuild file.
Select a verbosity for the target in the Verbosity combobox.
Select the configuration for the target in the Configuration combobox.
Unselect the Show error list checkbox, if you don't want to show the error list window when executing builds through MSBuild Shell Extension.
Select the Add button.
Select the Save button.

Example:

Extensions

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Extensions icon.
Select the New button.
Type in the file extension in the File extension textbox. The file extension should not contain a '.' before the extension name.
Select the Targets which should be enabled for the new file extension. Each target selected, results in an additional menuitem at the context menu of the specified file extension.
Select the Add button.
Select the Save button.

Example:

UPDATED WIKI: Manual

ThomasArdal — Sat, 01 Mar 2008 09:07:28 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Manual

This short manual tries to explain the basic concepts in MSBuildShellExtension.

Editor

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Editor icon.
Select the New button.
Type a name for the external tool in the Title textbox.
Select the Default checkbox, if this tool should be used as the external tool for opening source files from within the error list window.
Add the path to the external tool in the Target and arguments textbox. The external tool should as a minimum support a command line parameter for specifying the file containing error/warning. You can use the Variables button to insert different types of variables in the Target and arguments textbox.
Select the Add button.
Select the Save button.

Example:

Targets

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Targets icon.
Select the New button.
Type a name for the target in the Title textbox.
Type the name of the target. This is the target name as specified in the MSBuild file.
Select a verbosity for the target in the Verbosity combobox.
Select the configuration for the target in the Configuration combobox.
Unselect the Show error list checkbox, if you don't want to show the error list window when executing builds through MSBuild Shell Extension.
Select the Add button.
Select the Save button.

Example:

Extensions

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Extensions icon.
Select the New button.
Type in the file extension in the File extension textbox. The file extension should not contain a '.' before the extension name.
Select the Targets which should be enabled for the new file extension. Each target selected, results in an additional menuitem at the context menu of the specified file extension.
Select the Add button.
Select the Save button.

Example:

UPDATED WIKI: MSBuild Tutorial

ThomasArdal — Fri, 08 Feb 2008 13:41:26 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

.NET 2.0 contains a new tool called MSBuild. MSBuild is primarily used to build .NET application, 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 scriptet application on non-developer PCs as well.

Before .NET 2.0, application were build 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 have no dependencies to Visual Studio itself. MSBuild can in theory be implemented in all types of file extension, but a number of formats seems to by 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 is new extensions, which are either written in hand or with a tool knowing the MSBuild syntax. A few tools exists for this purpose. My personally opinion is, that the build 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 you should write your own containing your home-made MSBuild scripts. My personally opinion is to let Visual Studio generate its own projects (example: csproj files) and create you 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. In this way you avoid updating a auto-generated file, which you basically don’t have control over.

An MSBuild file is implemented in XML. The root element of a 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 is executed in the same order, as 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 Intellisence. The build file contains a single targets named Build. This target contains two tasks: Message and MSBuild. Message outputs a message to the console and is primarily used for debug purposes. MSBuild runs a configurable number of targets on another build file. Caused by that fact, that the .csproj file is also implement 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 have implemented properties. A property is a simple key/value type, which can be used from multiple locations in the scripts. Lets 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 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 only run 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 contain 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 yet 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 situation, but other times this is simple not flexible enough. This is were items comes in. An item gives the possibility to create dynamic lists of for instance file names. Lets 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 outside 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 point out which files should be copied when doing a release.

The Include filter decided 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 ends with 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 usefull. This is caused by the fact that the content for the MyReleaseFiles item is generated before running the actual targets. This means, that on a new checkout or after a clean, no files exists in the bin\debug directory. 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, where the CreateItem task is executed. Notice that the CreateItem task contains an Output element. The Output element is used 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 price:

Conditions

Besides the CreateItem task in a previous example, out build scripts have been very static until now. This can be sufficient in a lot of projects. Some times you need a little more flexible build scripts, though. A feature for fulfilling this in MSBuild is called Conditions. A condition in MSBuild is not that different that a condition in other software languages. It is a possibility to make more flexible structures for instance 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 up front, the value of the attribute is set to Debug. Properties can be set up front 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 conditions examines if the value of the Configuration property is Release and only allows execution of the Release target, if this condition turns out true.

Frequently Used Tasks

CallTarget – Executes another target inside the current build file. Used in places, where a target needs to call another target at a specific place inside the target itself. If the target where just dependant of 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 acts as out input variables to the addition task: Number1 and Number2. Both properties are marked with the Required attribute, which tells the script to fail, if these properties 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>

Because my AddTask in an external task not build 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 keeps popping 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 wan't 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 other than simple stuff, 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>

Notice 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 build-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 semi colon. In the PrintMessage task we simple print the message with the Caller property specified inside the Text attribute.

Links

The MSBuild documentation is actually quite good and a must for all serious MSBuild developers: http://msdn2.microsoft.com/en-us/library/wea2sca5(VS.80).aspx

A lot of different tools for handling MSBuild files exists. I haven’t been able to find a tool, making it possible to run build scripts from within Visual Studio. You could start by installing the MSBuildShellExtension tool from: MSBuildShellExtension.

Besides the build in tasks in MSBuild, there is a great community project, implementing a lot of nice tasks not implemented by Microsoft. Targets for search and replace, zipping, sending out mails, modifying subversion etc., can be found here: http://msbuildtasks.tigris.org/

UPDATED WIKI: MSBuild Tutorial

ThomasArdal — Fri, 08 Feb 2008 13:30:18 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

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)

<?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>

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>

Items

<?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>

<?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>

<?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>

Conditions

<?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 up front, the value of the attribute is set to Debug. Properties can be set up front 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 conditions examines if the value of the Configuration property is Release and only allows execution of the Release target, if this condition turns out true.

Frequently Used Tasks

Custom MSBuild Tasks

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;
    }
  }
}

<?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>

Generic Targets

Once in a while a question keeps popping 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 wan't to have the same lines of code spread around our build script, making it longer than necessary and complex to maintain. MSBuild contains 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 other than simple stuff, 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>

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

<?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 build-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 attribute name Caller. Multiple properties can be specified inside this attribute by separating them with semi colon. In the PrintMessage task we simple print the message with the Caller property specified inside the Text attribute.

Links

The MSBuild documentation is actually quite good and a must for all serious MSBuild developers: http://msdn2.microsoft.com/en-us/library/wea2sca5(VS.80).aspx

A lot of different tools for handling MSBuild files exists. I haven’t been able to find a tool, making it possible to run build scripts from within Visual Studio. You could start by installing the MSBuildShellExtension tool from: MSBuildShellExtension.

Besides the build in tasks in MSBuild, there is a great community project, implementing a lot of nice tasks not implemented by Microsoft. Targets for search and replace, zipping, sending out mails, modifying subversion etc., can be found here: http://msbuildtasks.tigris.org/

UPDATED WIKI: MSBuild Tutorial

ThomasArdal — Fri, 08 Feb 2008 13:15:57 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

MSBuild Tutorial

MSBuild Basics
Properties
Items
Conditions
Frequently Used Tasks
Custom MSBuild Tasks
Generic Targets
Links

MSBuild Basics

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)

<?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>

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>

Items

<?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>

<?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>

<?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>

Conditions

<?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 up front, the value of the attribute is set to Debug. Properties can be set up front 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 conditions examines if the value of the Configuration property is Release and only allows execution of the Release target, if this condition turns out true.

Frequently Used Tasks

Custom MSBuild Tasks

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;
    }
  }
}

<?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>

Generic Targets

Once in a while a question keeps popping 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 wan't to have the same lines of code spread around our build script, making it longer than necessary and complex to maintain. MSBuild contains 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 other than simple stuff, 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.

Links

The MSBuild documentation is actually quite good and a must for all serious MSBuild developers: http://msdn2.microsoft.com/en-us/library/wea2sca5(VS.80).aspx

A lot of different tools for handling MSBuild files exists. I haven’t been able to find a tool, making it possible to run build scripts from within Visual Studio. You could start by installing the MSBuildShellExtension tool from: MSBuildShellExtension.

Besides the build in tasks in MSBuild, there is a great community project, implementing a lot of nice tasks not implemented by Microsoft. Targets for search and replace, zipping, sending out mails, modifying subversion etc., can be found here: http://msbuildtasks.tigris.org/

UPDATED WIKI: Screenshots

ThomasArdal — Thu, 08 Nov 2007 18:21:29 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Screenshots

Context menu in the explorer:

During the build, an error component - like the one included in Visual Studio - is shown:

Configuration application:

First page on the configurator makes it possible to define which tool should be used to open files from the error list:

Second page of the configurator makes it possible to define new targets:

Third page of the configurator makes it possible to define new file extensions:

UPDATED WIKI: Manual

ThomasArdal — Thu, 08 Nov 2007 18:17:14 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Manual

This short manual tries to explain the basic concepts in MSBuildShellExtension.

Editor

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Editor icon.
Select the New button.
Type a name for the external tool in the Title textbox.
Select the Default checkbox, if this tool should be used as the external tool for opening source files from within the error list window.
Add the path to the external tool in the Target and arguments textbox. The external tool should as a minimum support a command line parameter for specifying the file containing error/warning. You can use the Variables button to insert different types of variables in the Target and arguments textbox.
Select the Add button.
Select the Save button.

Example:

Targets

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Targets icon.
Select the New button.
Type a name for the target in the Title textbox.
Type the name of the target. This is the target name as specified in the MSBuild file.
Select a verbosity for the target in the Verbosity combobox.
Select the configuration for the target in the Configuration combobox.
Unselect the Show error list checkbox, if you don't want to show the error list window when executing builds through MSBuild Shell Extension.
Select the Add button.
Select the Save button.

Example:

Extensions

Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
Select the Extensions icon.
Select the New button.
Type in the file extension in the File extension textbox. The file extension should not contain a '.' before the extension name.
Select the Targets which should be enabled for the new file extension. Each target selected, results in an additional menuitem at the context menu of the specified file extension.
Select the Add button.
Select the Save button.

Example:

UPDATED WIKI: Manual

ThomasArdal — Thu, 08 Nov 2007 18:15:51 GMT

Menu
Home Screenshots Manual MSBuild Tutorial Donations Search RSS

Manual

This short manual tries to explain the basic concepts in MSBuildShellExtension.

Editor

When double clicking on a file with warning/error in the MSBuildShellExtension error list window, an editor of your choices opens. MSBuildShellExtension comes with two pre-installed templates for Visual Studio 2005 and Notepad. It is possible to extend the tool with more templates. This is done through the MSBuild Shell Extension Configurator:

1. Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
2. Select the Editor icon.
3. Select the New button.
4. Type a name for the external tool in the Title textbox.
5. Select the Default checkbox, if this tool should be used as the external tool for opening source files from within the error list window.
6. Add the path to the external tool in the Target and arguments textbox. The external tool should as a minimum support a command line parameter for specifying the file containing error/warning. You can use the Variables button to insert different types of variables in the Target and arguments textbox.
7. Select the Add button.
8. Select the Save button.

Example:

Targets

MSBuildShellExtension comes with three types of targets (Build, Clean and Rebuild) for each of the default file types. Theese targets can be modified or removed and new targets can be added. This is done through the Targets section in the MSBuild Shell Extension Configurator. New targets are added like this:

1. Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
2. Select the Targets icon.
3. Select the New button.
4. Type a name for the target in the Title textbox.
5. Type the name of the target. This is the target name as specified in the MSBuild file.
6. Select a verbosity for the target in the Verbosity combobox.
7. Select the configuration for the target in the Configuration combobox.
8. Unselect the Show error list checkbox, if you don't want to show the error list window when executing builds through MSBuild Shell Extension.
9. Select the Add button.
10. Select the Save button.

Example:

Extensions

Last, but not least, you are able to extend the shell extension to file extensions of your choise. As default a number of MSBuild extensions are added, but you can add your own file extension like this:

1. Open the Configurator through Start | All Programs | MSBuildShellExtension | Configurator
2. Select the Extensions icon.
3. Select the New button.
4. Type in the file extension in the File extension textbox. The file extension should not contain a '.' before the extension name.
5. Select the Targets which should be enabled for the new file extension. Each target selected, results in an additional menuitem at the context menu of the specified file extension.
6. Select the Add button.
7. Select the Save button.

Example:

msbuildshellex Wiki & Documentation Rss Feed

Updated Wiki: Home

Project Description

News

Updated Wiki: MSBuild Tutorial

MSBuild Tutorial

Table of Contents

MSBuild Basics

Properties

Items

Conditions

Frequently Used Tasks

Custom MSBuild Tasks

Generic Targets

Links

Updated Wiki: MSBuild Tutorial

MSBuild Tutorial

Table of Contents

MSBuild Basics

Properties

Items

Conditions

Frequently Used Tasks

Custom MSBuild Tasks

Generic Targets

Links

Updated Wiki: MSBuild Tutorial

MSBuild Tutorial

Table of Contents

MSBuild Basics

Properties

Items

Conditions

Frequently Used Tasks

Custom MSBuild Tasks

Generic Targets

Links

Updated Wiki: MSBuild Tutorial

MSBuild Tutorial

Table of Contents

MSBuild Basics

Properties

Items

Conditions

Frequently Used Tasks

Custom MSBuild Tasks

Generic Targets

Links

UPDATED WIKI: Home

Project Description

News

UPDATED WIKI: Home

Project Description

News

UPDATED WIKI: Home

Project Description

UPDATED WIKI: Home

Project Description

UPDATED WIKI: Home

Project Description

UPDATED WIKI: Manual

Manual

Editor

Targets

Extensions

UPDATED WIKI: Manual

Manual

Editor

Targets

Extensions

UPDATED WIKI: Manual

Manual

Editor

Targets

Extensions

UPDATED WIKI: MSBuild Tutorial

MSBuild Tutorial

Table of Contents

MSBuild Basics

Properties