MSBuild Team Blog : How To

7 Steps to MSBuild

msbuild — Tue, 05 Dec 2006 04:10:00 GMT

Brennan has a great post about all things MSBuild, and covers good breadth on both concepts, as well as the many things you may want to drive with MSBuild (unit testing, web deployment projects, etc). Check it out!

[ Author : Faisal Mohamood ]

/p property values are immutable - (sort of)....

msbuild — Thu, 05 Oct 2006 18:55:00 GMT

Hello there - sorry for the long absence, but we're back and hopefully I'll keep this going again.

So there was a recent forum post about how property values that are specified from the command line are immutable - i.e. it is not straightforward to change them from within the project file. Well, this is mostly true, but there are exceptions.

Let's take an example:

If I've got a property in my project file defined like this,

<Configuration>Debug</Configuration>

</PropertyGroup>

then, calling msbuild with /p:Configuration=Release will override this value (or alternatively set the value if it is not defined) for all projects that are being built. Properties that we pass in with a /p switch on the command line are known as "Global Properties" and so it will flow down to all projects that are being built - so if you were building a solution file, all projects will get the overridden value of this property.

Now, let's say that you have this defined in your project file:

<AppPath Condition=" '$(AppPath)' == '' ">bin\debug\</AppPath>

<AppPath Condition=" !HasTrailingSlash('$(AppPath)') ">$(AppPath)\</AppPath>

</PropertyGroup>

What I am doing here is that I am defining a default value for AppPath property if AppPath is not defined. Additionally, I want to set it up so that if someone has specified an AppPath property, then if it does not already have a trailing slash, I'd like to add it. Looks reasonable, correct?

Actually this will not work as you expect - and is something to watch out for. What happens when you specify something with a /p:AppPath=blah\ is that all in-project property definitions for AppPath are ignored (or essentially overridden), and so none of the in-project property definitions take effect - even the ones with the condition. This makes sense if you think about it because otherwise what exactly are we supposed to override? Would that be the first definition of the property? Or should we override only those values of the property that are checking against an empty value? There isn't a clear answer. We override all property definitions and what is passed in is the effective value.

Fortunately, there is a way around this if it causes you grief - but it isn't declarative like PropertyGroup. You have to use the CreateProperty task inside a target where you intend to process the property, like so:

</CreateProperty>

Alternatively (and perhaps as a better approach), you can use a property name like AppPath as the public property you expect to override from th command line, but filter it out into a different property inside your targets that you then use for doing the actual work - like this:

<_validatedAppPath>$(AppPath)</_validatedAppPath>

<_validatedAppPath Condition=" '$(_validatedAppPath)' == '' ">bin\debug\</_validatedAppPath>

<_validatedAppPath Condition=" !HasTrailingSlash('$(_validatedAppPath)') ">$(_validatedAppPath)\</_validatedAppPath>

</PropertyGroup>

In this case, you validate the /p value and store it in an internal property that is validated, and never directly overridden from the command line.

Hope this helps, and clears some confusion on "strange behavior" if you ever encountered it.

[ Author: Faisal Mohamood ]

How To: Remove the Up-To-Date Check From the AssemblyInfoTask

msbuild — Tue, 28 Mar 2006 23:57:00 GMT

Every couple of weeks I get mail from someone who is using the AssemblyInfoTask on a build machine under source control. The question typically goes like this:

I added the .targets file to my project, and it works fine on my dev machine, but doesn't do anything when I'm running it in the build lab. What's wrong? Help!

The reason it "doesn't do anything" is because the default Microsoft.VersionNumber.Targets file includes MSBuild attributes that instruct the build engine to check timestamps on input and output files. These were added because it doesn't make much sense to increment the version number on an assembly if nothing is gettting re-built. This can happen if MSBuild does an incremental build on the project.

In the build lab, however, all of the input files (.cs files, generally) and the output file (assemblyinfo.cs) wind up with the same timestamps when they are synchronized from the soruce code control server.

To resolve this, simply remove the Inputs and Outputs attributes from the <Target> tag in the Microsoft.VersionNumber.Targets file. It should wind up looking like this:

[ Author: Neil Enns ]

How To: Bypass Post-Build Steps in a Build Lab Environment

msbuild — Sat, 11 Mar 2006 02:06:00 GMT

(Can you tell I'm going through my folder of interesting MSBuild questions today?)

Here's another good question that came across our internal discussion alias last week:

Is there a quick and easy way to bypass the PostBuild steps in a project file that was created with VS.NET 2005? I am trying to set up a master build project that will be compiling a large number of other projects, some that contain PostBuild steps that are not appropriate for our master build. Is there something I can define that will then cause the PostBuild steps to be skipped?

I actually didn't know the answer to this one off the top of my head, but since the entire build process is available for the world to see, it didn't take much to figure it out. I cracked open the Microsoft.Common.Targets file in Visual Studio and looked at how the PostBuildStep is set up. Here's an excerpt from the file:

Notice how the condition is set up. In the build lab, you can simply pass /p:PostBuildEvent="" on the command line to disable all the post build events in the included projects.

[ Author: Neil Enns ]

How To: Distribute Your Custom Task and .Targets file

msbuild — Thu, 09 Mar 2006 22:38:00 GMT

We've had variations of the same question on how to distribute tasks come through both internal and external channels in the last couple of weeks. Here's one example:

If we have a product that is installing custom MSBuild tasks, are there any type of guidelines on where they should be installed, do they need to be registered, etc.?

The good news is you don't have to register anything at all. You just need to figure out what the best directory is to install your goo. Typically there's two pieces of goo that need to be installed: the assembly with the task(s) in it, and the .targets file that includes a <UsingTask>, assorted properties, and perhaps even a target override.

It turns out that you'll probably want your installer to offer the user the choice of two installation points: one for installing your new MSBuild magic on a developer's machine, and another for installing it in some sort of build-lab environment. Here's a little table with the suggested installation locations:

	Developer Machine	Build Lab
Assembly	Global Assembly Cache	Location of user's choosing
.Targets File	$(MSBuildExtensionsPath)	Location of user's choosing

This requires your setup to actually have two different .targets files, since the <UsingTask> will be different depending on where the task assembly is installed.

To see all this in action I suggest downloading the AssemblyInfoTask sources. It includes a setup project that gives the user of installing the assembly into either the GAC or to their local application data folder. This could be extended to allow installation to GAC or a folder of the user's choosing.

[ Author: Neil Enns ]

How To: Exclude Multiple Files From a Wildcard

msbuild — Thu, 09 Mar 2006 01:56:00 GMT

We got the following question on our internal conversion discussion alias today:

Is there a way to exclude two or more items from an ItemGroup using the “exclude” attribute without using a wildcard?

It turns out the way to do this wasn't clear from our existing MSDN Documentation. Brett, our documentation writer, has a fix in the queue for the next MSDN refresh, but in the mean time here is the answer from Dan:

</ItemGroup>

[ Author: Neil Enns ]

How To: Add Custom Process at Specific Points During Build (Method #2)

msbuild — Fri, 10 Feb 2006 22:20:00 GMT

Back in November I wrote about a quick-and-dirty way to add custom build process into the standard Visual Studio build by overriding pre-defined targets that exist in Microsoft.Common.Targets. While this method works fine for internal build processes it can be brittle if you’re trying to deploy your build process to other teams or customers. In particular, if someone else decides to go and override the same target after you’ve done so, your customization will disappear. To handle this situation we’ve provided a second way of inserting your custom build process into the Visual Studio build: overriding properties that are used in TargetDependsOn attributes. The easiest way to understand how to do this is to look at a short snippet from Microsoft.Common.Targets:

Notice how the Build target has a DependsOnTargets that points to the BuildDependsOn property. That means before the Build target can run, all the targets listed in BuildDependsOn have to run first:

BeforeBuild;

CoreBuild;

AfterBuild

</BuildDependsOn>

</PropertyGroup>

If you want to add something to the build process that runs after everything else in the build, you’d simply create your own target and then add it to BuildDependsOn like this:

$(BuildDependsOn);

MyCustomTarget

</BuildDependsOn>

</PropertyGroup>

</Target>

Notice how we’ve included the original value of BuildDependsOn in our new definition of the property. Using this pattern means that anyone who overrides the existing meaning of BuildDependsOn will include all the existing content of the property, without overwriting customizations others have made. You can use a similar approach to get your custom target to run before everything in BuildDependsOn.

Here’s a list of the most commonly used *DependsOn properties:

Property	Description
BuildDependsOn	This is the property to use if you want to insert custom process before or after the entire build process. As you might guess, this is frequently used.
CleanDependsOn	This is the property to override if you want to clean up output from your custom build process.
CompileDependsOn	This is a very useful property as it provides a place to insert custom process before or after the compliation step. This is frequently overriden.

In addition to the three common properties there are many other properties that are almost never used. For completeness, here’s what they are and why you might use them:

Property	Description
CompileLicxFilesDependsOn	Targets in this property run before .licx files get compiled.
CoreBuildDependsOn	This is the heavy-duty part of the build process and pretty much drives the whole build.
CoreCleanDependsOn	This is really provided for design pattern completeness. There’s no real reason to use this instead of CleanDependsOn.
CoreCompileDependsOn	Interestingly this is one of only two *DependsOn properties that are defined in the language-specific targets files instead of Microsoft.Common.Targets. This is rarely used; instead, override CompileDependsOn.
CreateManifestResourceNamesDependsOn	Run before the manifest resource name is created from .resx files. Rarely overridden.
CreateSatelliteAssembliesDependsOn	Primarily used as a way to force intermediate satellite assemblies to be computed before the final satellite assemblies are regenerated.
GetRedistListsDependsOn	While this is in the Common.Targets file and can technically be used to insert custom process around the collection of redistributable assemblies, this is really there to ensure framework path resolution happens before the lists are gathered. I doubt anyone will ever need to override this.
PostBuildEventDependsOn	This runs before the PostBuildEvent target is executed. This is rarely overridden since PostBuildEvent largely exists to support the legacy build extension methods offered in Visual Studio 2003 and earlier. Instead of overriding this you should consider using BuildDependsOn.
PreBuildEventDependsOn	This runs before the PreBuildEvent target is executed. This is rarely overridden since PreBuildEvent largely exists to support the legacy build extension methods offered in Visual Studio 2003 and earlier. Instead of overriding this you should consider using BuildDependsOn.
PrepareForBuildDependsOn	This takes care of getting all the build pre-requisites done before the actual build process starts. You can think of targets in this property as being almost like initialization routines for the whole build.
PrepareForRunDependsOn	This is a good place to insert build process that needs to get content into place before the application is executed from within Visual Studio. Having said that, it’s rarely overridden.
PrepareResourceNamesDependsOn	Prepares the names of the resource files before they get passed to the complication step of the build.
PrepareResourcesDependsOn	Prepares the resources before they get passed to the compliation step of the build.
PublishBuildDependsOn	The list of targets that must run before the project is published. Rarely, if ever, used. Instead, use PublishOnlyDependsOn.
PublishDependsOn	Runs before the project is published using ClickOnce deployment outside of the IDE. It causes a build to happen before publish takes place. If you need to do work before the project is published you should override PublishOnlyDependsOn instead, since PublishDependsOn includes a call to PublishOnlyDependsOn.
PublishOnlyDependsOn	Run after the IDE has completed a build and then needs to do a publish (as opposed to a command-line build where build followed by publish might happen all in one build command). If you need to do work before or after the project is published this is the property to use.
RebuildDependsOn	This drives the rebuild target, and handles clean and then re-building the project. If you want to do something before or after rebuild this is the property to override.
ResGenDependsOn	This is used to drive the resource generation step of the build process. If you need to do something before or after resource generation, this is the property to override.
ResolveAssemblyReferencesDependsOn	This has a similar story to GetRedistListsDependsOn. It’s unlikely anyone will ever need to override this.
ResolveReferencesDependsOn	This is the workhorse for resolving assembly references, one of the most complicated parts of the build process. If you want to do special work to handle assembly resolution, or do work immediately following the resolution of all the assembly references, this is the property to use. Having said that, it’s rarely overridden.
RunDependsOn	Targets in this property will get executed before the compiled application is run.
UnmanagedRegistrationDependsOn	Targets in this property are run before the main assembly is registered for COM interop.
UnmanagedUnregistrationDependsOn	This runs before the main assembly is registered for COM interop purposes.
BuiltProjectOutputGroupDependsOn DebugSymbolsProjectOutputGroupDependsOn DocumentationProjectOutputGroupDependsOn SatelliteDllsProjectOutputGroupDependsOn SourceFilesProjectOutputGroupDependsOn ContentFilesProjectOutputGroupDependsOn	Targets in these properties are run before output groups are computed for the IDE.

[ Author: Neil Enns ]

How To: Use the AssemblyInfoTask With ASP.NET Web Deployment Projects

msbuild — Thu, 26 Jan 2006 22:06:00 GMT

About once a week we get a question from someone who wants to know how to set the assembly version information on ASP.NET projects. I spoke with Bradley, a development lead over in the ASP.NET team who worked on the Web Deployment Projects, and it turns there are two ways you can do this.

If the only thing you're interested in doing is setting the version number on the web deployment project you can do that directly through UI properties on the deployment project instead of editing MSBuild files and downloading another task. For more information look at their walkthrough documentation.

If you want to set the version number as part of a larger build process that includes desktop assemblies and other class libraries you can use the AssemblyInfoTask and custom MSBuild XML. To make this work you need to add an assemblyinfo.cs (or .vb) to a folder called app_code under your top level directory. Once that file is there you can use the AssemblyInfoTask as you normally would to set the version number, and then use the Web Deployment Project to do the compliation of the assembly for the web.

[ Author: Neil Enns ]

How To: Obtain Initial Property Values in a Logger

msbuild — Wed, 25 Jan 2006 20:43:00 GMT

We got a question on our MSBuild Feedback alias today that went something like this:

How do I obtain all the initial property values in the project file in my custom logger?

It's not immediately obvious from our object model, but you can do this. In the ProjectStarted event the ProjectStartedEventArgs contains a Properties member. You can iterate over this with a foreach to look at all the values of the properties in the project file.

Thanks to Dan for the question, and to Jay for the answer.

[ Author: Neil Enns ]

How To: Implementing Custom Tasks - Part I

msbuild — Sun, 22 Jan 2006 02:01:00 GMT

While MSBuild is all about build customization,we never really blogged about what is involved in implementing custom tasks. Partly, I suppose that's because implementing a custom task is as easy as falling off a log most of the time: 1) Subclass Microsoft.Build.Utilities.Task abstract class 2) Implement the Execute method

But there's a lot more to tasks than just that. In this series of posts, I hope to cover all there is to know about MSBuild tasks - both at a conceptual level as well as on variations such as ToolTask, AppDomainIsolatedTask, etc. In this post I'd like to set the context for discussing some of those topics.

A task, in principle is nothing more than an implementation of the GoF Command Object Pattern i.e. an object that knows how to perform an action encapsulated via an Execute method. While it is possible to utilize tasks programmatically via code, the primary motivation was to provide a way of performing self standing units of work within build targets.

In the crudest form, a task is a type that implements the Microsoft.Build.Framework.ITask interface from the Microsoft.Build.Framework assembly. Here's a simple implementation of a task that can set environment variables.

using Microsoft.Build.Framework;

namespace SimpleTask
{
    public class SetEnvironmentVariable : ITask
    {
        private IBuildEngine engine;
        public IBuildEngine BuildEngine
        {
            get { return engine; }
            set { engine = value; }
        }

        private ITaskHost host;
        public ITaskHost HostObject
        {
            get { return host; }
            set { host = value; }
        }

        private string name;

        [Required]
        public string Name
        {
            get { return name; }
            set { name = value; }
        }

private string varValue;

        [Required]
        public string Value
        {
            get { return varValue; }
            set { varValue = value; }
        }

        public bool Execute()
        {
            System.Environment.SetEnvironmentVariable(name, varValue);
            string message = string.Format("Environment Variable {0} set to {1}", name, varValue);
            BuildMessageEventArgs args = new BuildMessageEventArgs(
                message, string.Empty, "SetEnvironmentVariable", MessageImportance.Normal);
            engine.LogMessageEvent(args);

            return true;
        }
    }
}

In addition to the Execute method that performs the actual work, at the minimum all tasks must expose two properties - BuildEngine of type IBuildEngine, and HostObject of type ITaskHost. For the purposes of most tasks, the implementation I have shown here will suffice.

IBuildEngine itself is used by the task to report messages, warnings and errors to the MSBuild engine. ITaskHost is an interface that is used to represent host objects that can form a basis for richer communication between tasks and an environment that hosts MSBuild (such as Visual Studio). ITaskHost is extremely useful in cases where you are hosting the build engine yourself. I will cover the details of this beast in a later post.

.NET properties on a task type allow you define parameters on the task in order to communicate with the task via the project file. So, in the case of the SetEnvironmentVariable task, I have defined Name and Value properties as inputs into the task. My use of the Required attribute on these two properties ensures that the invocation of the tasks will not be possible without specifying those two parameters. In this context, it makes sense because the task cannot perform its function without having those to values specified to it.

Finally, returning true from the Execute method indicates success to the MSBuild engine. I have ignored the possibility of the task failing in this case to keep it simple - look for more details on this subject alone in a subsequent post.

Here's how the task is invoked from a project file:

That's all there is to defining and using custom tasks. Of course, it is way simpler to derive from the abstract class Microsoft.Build.Utilities.Task that is included in the Microsoft.Build.Utilities assembly, and that's what you should be using most of the time unless you require a richer interaction with the MSBuild engine.

In the next post, I will dig into more details on interacting with tasks via the project file. We will examine the types of objects that can be passed in and out of tasks, caveats to watch out for, etc.

[ Author: Faisal Mohamood ]

How To: Use the AssemblyInfoTask With Source Code Control

msbuild — Fri, 06 Jan 2006 01:48:00 GMT

Several people have written our feedback alias with problems using the AssemblyInfoTask when the projects are under source code control. When the files are checked in the AssemblyInfo files are read-only, and the task fails with an error that the file can't be updated.

The best way to handle this is to check the AssemblyInfo files out before running the AssemblyInfoTask. After the build completes you can then either revert the files, or check them back in with the updated version numbers.

To check the files out and then check them back in using Team Foundation Server add the following lines to your TFSProj file after the <Imports> line for Microsoft.VersionNumber.targets:

Thanks to Gautam from the Team Build team for this tip!

[ Author: Neil Enns ]

How To: Retrieve the AssemblyVersion using AssemblyInfoTask

msbuild — Wed, 04 Jan 2006 22:38:00 GMT

We got a great question at msbuild@microsoft.com last week:

What is the preferred method to retrieve the version of the assembly that was just built via MSBuild? Post build, we would like to automatically create and copy the assembly(ies) to version folder.

If you are using the AssemblyInfoTask and its associated Microsoft.VersionNumber.Targets file this is really easy. Here's what you do:

Now that I look at this, perhaps "really easy" isn't the right way to describe it :) In fact, I had to have Faisal show me how to do the recursive copy, and Kieran help me figure out that a CreateItem was needed.

The $(MaxAssemblyVersion) property holds the version number for the build. This is used with the MakeDir task to create the directory. The CreateItem task is used to collect all the files from the output directory into an item group so it can then be copied recursively using the Copy task. Note the use of the RecursiveDir metadata, as described in Faisal's post on recursive copy to ensure all the files are copied as a full directory tree into the archive directory.

The condition on AfterBuild prevents the directory from being created if the MaxAssemblyVersion wasn't set during the build. This happens when none of the files changed, and nothing was re-built. Instead of depending on the $(MaxAssemblyVersion) property you could also set up the Inputs and Outputs to the target to be very specific about what file updates will trigger a copy to the archive directory.

If you're interesed in where $(MaxAssemblyVersion) comes from, it is set by the Microsoft.VersionNumber.Targets file when the AssemblyInfoTask is run. The snippet from the .targets file looks like this:

This causes the value of the "MaxAssemblyVersion" property on the AssemblyInfo class (the one in .NET code) to get stuck in the MSBuild "MaxAssemblyVersion" property after the task is run. The same thing happens for MaxAssemblyFileVersion.

[ Author: Neil Enns ]

How To: Return Additional Information on Outputs from a Project

msbuild — Thu, 08 Dec 2005 18:43:00 GMT

We got a great question today from an internal team at Microsoft that is working on some custom build process for their specific application:

We have a project whose output is both libraries and header files. What is the best way to return those outputs to the rest of the build process? How can we indicate they are different "types"?

Let's assume the project in question is getting called via an MSBuild task. What we want is to be able to say something like this:

TargetOutputs should contain all of the libraries and headers that were generated. But how do you tell them apart? Kieran replied and pointed out that this is an excellent example of the power of metadata.

When a task in outs.proj actually generates the output (either header or library) it also tacks on special metadata. The metadata can be anything, but in this example the headers have the “type” metadata set to “header” and the libraries have it set to “library”. The code to do this looks something like:

this.taskOutput[0].SetMetadata(“type”, “header”);

where taskOutput is an array of ITaskItem objects. The great thing about this approach is that you can combine it with batching later in your build process. Let’s say later on you want to print out the list of headers that were generated. The line in the MSBuild file would look like this:

The best part is that metadata will follow the outputs through the entire build process, not just at batch time. If the outputs in this scenario get passed in to some other task down the line, that task in its implementation can use the object model to query for the metadata and do interesting things.

[ Author: Neil Enns ]

How To: Specify Long Command Lines to MSBuild

msbuild — Tue, 29 Nov 2005 19:40:00 GMT

Sometimes when using MSBuild.exe the command lines can get pretty darn long and hard to manage. This is particularly true if you're using a custom logger that takes parameters. I also ran into some trouble when I was trying to pass an escaped string to the custom logger via the Visual Studio UI for project properties (the string was getting automatically unescaped by VS. Remind you of a recent blog entry?). The answer to both these problems is to use a response file for the command line parameters.

Response files are super easy. Just create a text file using your favourite text editor and put all your command line parameters in it. Then when you run MSBuild use the following command:

msbuild @parameters.txt

Then MSBuild will read all the command line parameters from the text file, and proceed as usual.

[ Author: Neil Enns ]

How To: Perform Nightly Builds with Team Foundation Server

msbuild — Mon, 28 Nov 2005 19:37:00 GMT

Edit: Ok, after talking with Khushboo and given Niels's comment, it's clear that the article I linked to is woefully out of date. Please ignore this post. If you want to perform nightly builds with Team Foundation Server, tfsbuild.exe is the tool to use.

[ Author: Neil Enns ]