You can download the template from the MSDN Code Gallery: ParallelTemplate.xaml

Once you’ve downloaded the template, you’ll need to add it to your version control repository before you can use it with your build definitions. Just follow these steps to get started:

1. Open Visual Studio 2010 and connect to your Team Project Collection
2. Open Source Control Explorer and navigate to the location of your build process templates (e.g. $/Project/BuildProcessTemplates).
3. Copy the ParallelTemplate.xaml file to the folder on your local disk that this version control folder is mapped to. In Source Control Explorer, you’ll see a link to this folder labeled Local Path. Clicking the link will open Windows Explorer on that folder.
4. Right click on an empty area of the contents pane and select Add Items to Folder…
   
   
5. The Add To Source Control dialog will open. It will automatically hide any files that are already checked in, so you should only see the ParallelTemplate.xaml file that you just copied to this folder.
   
   
6. Click Next and you’ll be asked to confirm the operation – click Finish to pend the add.
   
   
7. Right click on the file and select Check In Pending Changes… Enter an appropriate check-in comment and commit the add.
   
   
8. Next, create a new Build Definition, or edit an existing one. Select the Process page of the Build Definition Editor and click the Show Details button to see the details of the currently selected build process template. You’ll need to click New… to select the XAML file you just checked into version control.
   
   
   
   Click the Select an existing XAML file radio button and click Browse… to browse for the ParallelTemplate.xaml file you just checked in.
9. The build process parameters for the Parallel Template are the same as the ones for the Default Template, so no other changes are required to your existing build definition.

Things to keep in mind when using this build process template:

• Builds are parallelized by platform/configuration so, if you’re only building one platform/configuration, your build won’t be distributed across multiple Build Agents.
• You’ll need more than one Build Agent available for this build process to parallelize your build. Keep in mind that you can configure multiple Build Agents on a single physical machine – appropriate if the machine has multiple processor cores. Note that you may want to configure each Build Agent to use a working directory on a separate physical disk, if multiple local disks are available.

We haven't replaced MSBuild with Windows Workflow (WF). We still very much rely on MSBuild as the core build engine, which is it's core competency. You'll find that there are lots of tasks that are still most easily and effectively automated with MSBuild. In fact, for the next release of Visual Studio, we're working with the MSBuild team to replace solution (.sln) files with MSBuild project files.

We introduced WF as a way of providing a higher level orchestration layer on top of the core build engine (which is MSBuild in the build process templates we include in the box). It makes it possible to do things like distribute a process across multiple machines and to tie the process into other workflow-based processes.

So, when should you automate with MSBuild and when should you automated with WF? Here's my general guidance on that subject:

• If the task requires knowledge of specific build inputs or outputs, use MSBuild
• If the task is something you need to happen when you build in Visual Studio, use MSBuild
• If the task is something you only need to happen when you build on the build server, use WF unless it requires knowledge of specifi build inputs/outputs

When using MSBuild, remember that you can customize your project files directly (by unloading them and then editing them in Visual Studio), or you can create custom .targets files and import them into your individual projects. The latter approach is useful for functionality that's common to multiple projects to avoid maintaining multiple copies.

When using WF, remember that you can write code activities for low-level tasks but that you can also compose higher-level tasks using straight XAML. We're actually working on a version of the default build process template that shipped with TFS 2010 that gives you a simpler, less granular view of the overall process by using a set of composed XAML activities.

To let you detect these errors at compile time, ASP.NET MVC projects now include an MvcBuildViews property, which is disabled by default. To enable this property, open the project file and set the MvcBuildViews property to true, as shown in this example from the ASP.NET MVC Release Notes:

<PropertyGroup>
  <MvcBuildViews>true</MvcBuildViews>
</PropertyGroup>

Note that enabling this feature will add some overhead to your build process.

Unfortunately, this feature won’t work out of the box with TFS Build 2010 because of the way the post-build processing is done. If you look at the .csproj file for your ASP.NET MVC project, you’ll see an overridden AfterBuild target that invokes the AspNetCompiler task on your web application project’s sources. The problem here is two-fold:

1. The AfterBuild target shouldn’t be overridden directly since that’s reserved for end-user post-build processing.
2. The PhysicalPath attribute passed to the AspNetCompiler task needs to be updated to a value that will work both locally and on the build server.

Fortunately, both of these issues are easily resolved. In the example below, I’ve introduced a new BuildViews target that will only execute if the MvcBuildViews property is set to true. It also takes advantage of a new feature in MSBuild 4.0 that simplifies the task of injecting a custom target into the dependency chain. The AfterTargets attribute tells MSBuild to execute this target after the Build target has finished. For the PhysicalPath attribute on the AspNetCompiler task, I’ve used WebProjectOutputDir which is defined in Microsoft.WebApplication.targets as a location that resolves correctly for builds in both Visual Studio and TFS.

<Target Name="BuildViews" Condition="'$(MvcBuildViews)'=='true'" AfterTargets="Build">
  <Message Importance="normal" Text="Precompiling views" />
  <AspNetCompiler VirtualPath="temp" PhysicalPath="$(WebProjectOutputDir)" />
</Target>

Note that after adding this custom target at an appropriate location in your web application’s project (.csproj) file (I’d recommend placing it just above the AfterBuild target, you’ll want to comment out the AfterBuild target.

Now, if you have an error in one of your views, it will show up as a compile-time error in Visual Studio and in your TFS builds. If you don’t want to take the performance hit of the additional compilation step, you can conditionally set the MvcBuildViews property to true for a specific configuration only (e.g. Release).

The key is the second invocation (the first invokes the “clean” target) of the MSBuild activity which builds a particular solution/project. You’ll need to modify this invocation as follows:

<mtbwa:MSBuild 
  CommandLineArguments="[String.Format(&quot;/p:SkipInvalidConfigurations=true;
    TeamBuildOutDir=&quot;&quot;{0}&quot;&quot; {1}&quot;, 
      BinariesDirectory, MSBuildArguments)]"
  Configuration="[platformConfiguration.Configuration]" 
  DisplayName="Run MSBuild for Project" 
  GenerateVSPropsFile="[True]" 
  LogFileDropLocation="[logFileDropLocation]" 
  OutDir="[outputDirectory]" 
  Platform="[platformConfiguration.Platform]" 
  Project="[localProject]" 
  RunCodeAnalysis="[RunCodeAnalysis]" 
  TargetsNotLogged="[New String() {
    &quot;GetNativeManifest&quot;, 
    &quot;GetCopyToOutputDirectoryItems&quot;, 
    &quot;GetTargetPath&quot;}]" 
  ToolPlatform="[MSBuildPlatform]" 
  Verbosity="[Verbosity]" />

Note that I’ve changed the CommandLineArguments attribute by setting a TeamBuildOutDir property and removing the OutDir property. This will set a global property named TeamBuildOutDir to the output directory that TFS Build would have redirected all of your build outputs to originally. You can then use that property to selectively copy your build outputs in a manner of your own choosing. For example, if you wanted to simply organize your outputs by solution and project, you could configure each project’s OutputPath as follows:

<OutputPath Condition="'$(TeamBuildOutDir)'=='' ">
  bin\$(Configuration)\
</OutputPath>
<OutputPath Condition="'$(TeamBuildOutDir)'!='' ">
  $(TeamBuildOutDir)$(SolutionName)\$(ProjectName)\$(Configuration)
</OutputPath>

There are, of course, any number of ways you could implement this depending on your own requirements. For instance, I have a build definition that builds all of the samples for the TFS SDK and copies ZIP files (with the sources) for each solution and VSIX files (for solutions that generate them) to the drop location. If you generate an installer, you may only want to copy that to the drop location.

Note that, if you’re running automated unit tests during your build without a Test Metadata (.vsmdi) file, you’ll also need to customize the SearchPathRoot attribute on the invocation of the MSTest activity to get it to find your unit test assemblies.

There is a potential down-side, however, in that each build service can only service one particular project collection. In TFS 2005 and 2008, a build agent was configured for a particular Team Project and you could only run one Build Agent per machine (though you could manually configure the same build agent for multiple Team Projects on the same server. Since you can have multiple Team Projects in a single Team Project Collection, the configuration experience has definitely improved in TFS 2010. That said, you may still find yourself needing to provide build services for multiple Project Collections from a single build machine. While I don’t recommend using this as a production configuration, it may be useful if you’re juggling multiple Project Collections on a machine that you’re using for demonstration purposes.

Note: this is not a supported configuration of the TFS Build Service – use it at your own risk.

1. Open a Command Prompt window as Administrator on the build machine.
2. Use the command line interface to the Service Control Manager to setup a second named instance of the Build Service.
   
   E.g. sc.exe create buildMachine-collection2 binpath="C:\Program Files\Microsoft Team Foundation Server 2010\Tools\TfsBuildServiceHost.exe /NamedInstance:buildMachine-collection2" DisplayName="Visual Studio Team Foundation Build Service Host (Collection2)" Note: For TFS 2012, you'll need to use the corresponding path to the executable.
   
   We recommend including the Project Collection name in the display and instance names for this second instance of the Build Service to make it easier to determine which instance you’re managing.
3. Set the TFSBUILDSERVICEHOST environment variable to refer to the new instance of the Build Service you just created by setting its value to the string you passed in the NamedInstance parameter in step 2. Note: For TFS 2012, the environment variable name is TFSBUILDSERVICEHOST.2012.
   
   E.g. set TFSBUILDSERVICEHOST=buildMachine-collection2
4. Start the Team Foundation Administration Console from the same command prompt so that it gets the environment variable you just set.
   
   E.g. "C:\Program Files\Microsoft Team Foundation Server 2010\Tools\tfsmgmt.exe"
5. Ensure that the new Build Service instance has a TFS resource Uri that is distinct from the originally configured Build Service. You can view the Uri in the Uri value under the following registry key:
   
   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\TeamFoundation\Build\tfsbuildservicehost1
   
   If the Uri is the same as the one under the Build\ServiceHost registry key, you’ll need to unregister the new Build Service instance and re-register it. To do so, first you’ll need to create a new Controller or Agent for the new Build Service instance in the Team Foundation Administration console. Next, you’ll need to click Unregister to unregister the Build Service and delete its associated Controller and/or Agents. When you re-register it, it should get a new Id that won’t conflict with the originally configured Build Service instance.
6. Ensure that the new Build Service instance is configured to listen on a different port than the originally configured Build Service. You can do this by opening the Properties dialog for the Build Service and changing the port appropriately.
7. If you’re working in a demo environment and the project collections you’re configuring Build Services for are starting out in the same state, there’s a good chance that, if you configure a Build Controller for each of the two Build Service instances, the Build Controllers will both end up with the same Id due to the way the TFS database auto-increments identity columns. This is only an issue if you use the custom assembly path for both Build Controllers and they use a potentially conflicting set of content in that path. If that’s the case, you can remove one of the Build Controllers from one of the Build Service instances, then recreate it and it should get a different Id.
8. Update default working directory for the agents you create on each Build Service instance. If you don't, there’s a chance that two Build Agents (one under each Build Service instance) will have the same Id and, consequently, the same working directory. Update the working directory in the Agent Properties dialog to include the collection name or some other distinguishing element. E.g. $(SystemDrive)\Builds\$(BuildAgentId)_Coll2\$(BuildDefinitionPath).
9. If you’re using (or plan to use) the new Symbol Server integration features in TFS 2010, you’ll need to setup a separate Symbol Store for each Team Project Collection. Symbol Server does not support concurrent storage access. TFS Build handles this by synchronizing access to the Symbol Stores used within a given Team Project Collection. This synchronization doesn’t work across Collections, however, so you’ll need to maintain separate Symbol Server stores for each Collection – fortunately, this is just a shared directory.
10. Ensure that the drop folders used in the Build Definitions across Project Collections are different. In most cases, this won’t be a problem unless two projects have same name across Project Collections.
11. Before installing TFS hot-fix or service pack, please stop all Build Service instances manually from Service Control Manager and restart them after patch installation is successful.

When you’re done, you’ll have a single machine that is providing Build Services for two separate TFS Team Project Collections. If you want to run builds on both Build Service instances concurrently, you’ll want to take steps to prevent resource contention like moving the working directories for the Agent on one of the instances to a separate hard disk. Even then you may encounter serious performance degradation if two instances of MSTest are invoked at the same time.

Let me reiterate that this is a hack and is not a supported configuration of TFS Build 2010. If you believe you have legitimate need to apply this configuration to a production build environment, contact me and describe your scenario in detail.

How does it look?

• Launch Setup from the TFS 2010 media
• Navigate to the feature selection page of the Wizard
• Select Team Foundation Components and de-select (uncheck) Team Foundation Server and Team Foundation Build Service as shown below:
  
• Click Install

When you’re done, you’ll have the server components installed on your machine without the overhead of an application tier and build service. Now you can build things like custom warehouse adapters.

Before You Begin

To complete this walkthrough, you’ll need the Edit project-level information permission for the Team Project you want to apply the check-in policy to. For more information, see Team Foundation Permissions.

Step 1 – Create and Build a Custom Policy Class

In this initial step, you create a new class library and add a custom policy class by deriving from the PolicyBase base class in the Microsoft.TeamFoundation.VersionControl.Client namespace. By deriving from this base class, your class implements the IPolicyDefinition and IPolicyEvaluation interfaces. The example policy code below applies code formatting standards to each C# and VB.NET source file that's checked in using NArrange.

namespace TeamFoundation.Samples.CheckinPolicies
{
    using System;
    using System.Collections.Generic;
    using System.IO;

    using Microsoft.TeamFoundation.VersionControl.Client;

    using NArrange.Core;

    [Serializable]
    public class ArrangePolicy : PolicyBase, ILogger
    {
        #region Fields

        [NonSerialized]
        IPendingCheckin _pendingCheckin;

        #endregion Fields

        #region Properties

        /// <summary>
        /// Gets a value indicating whether this check-in policy has an editable configuration
        /// </summary>
        /// <value><c>true</c> if this instance can edit; otherwise, <c>false</c>.</value>
        public override bool CanEdit
        {
            get
            {
                return false;
            }
        }

        /// <summary>
        /// Gets the description.
        /// </summary>
        /// <value>The description.</value>
        public override string Description
        {
            get { return "Runs NArrange against any .cs and .vb files in your pending changes"; }
        }

        /// <summary>
        /// Gets the type.
        /// </summary>
        /// <value>The type.</value>
        public override string Type
        {
            get { return "NArrange Policy"; }
        }

        /// <summary>
        /// Gets the type description.
        /// </summary>
        /// <value>The type description.</value>
        public override string TypeDescription
        {
            get { return "This policy prevents users from checking in files that don't comply with your coding style guidelines."; }
        }

        #endregion Properties

        #region Methods

        /// <summary>
        /// Dispose method unsubscribes to the event so we don't get into 
        /// scenarios that can create null ref exceptions
        /// </summary>
        public override void Dispose()
        {
            base.Dispose();
            _pendingCheckin.PendingChanges.CheckedPendingChangesChanged -= PendingChanges_CheckedPendingChangesChanged;
        }

        public override bool Edit(IPolicyEditArgs policyEditArgs)
        {
            // no policy settings to save
            return true;
        }

        /// <summary>
        /// Evaluates the pending changes for policy violations
        /// </summary>
        /// <returns></returns>
        public override PolicyFailure[] Evaluate()
        {
            var failures = new List<policyfailure>();
            const String supportedSourceFileExtensions = ".cs;.vb";

            // get a temporary location to write out the configuration file for NArrange
            var configFilePath = Path.GetTempFileName();

            // get the configuration file from our resources and write it to disk
            using (var writer = new StreamWriter(configFilePath))
            {
                writer.Write(Resources.DefaultConfig);
            }

            // instantiate a new FileArranger - this is the engine for NArrange
            var fileArranger = new FileArranger(configFilePath, this);

            // process each file in the set of pending changes
            foreach (var pendingChange in PendingCheckin.PendingChanges.CheckedPendingChanges)
            {
                // invoke NArrange on C# and VB.NET source files only
                if (supportedSourceFileExtensions.Contains(Path.GetExtension(
                    pendingChange.LocalItem).ToLowerInvariant()))
                {
                    fileArranger.Arrange(pendingChange.LocalItem, pendingChange.LocalItem, true);
                }
            }

            // clean up the temporary copy of the configuration file
            File.Delete(configFilePath);

            return failures.ToArray();
        }

        /// <summary>
        /// Initializes this policy for the specified pending checkin.
        /// </summary>
        /// <param name="pendingCheckin" />The pending checkin.</param>
        public override void Initialize(IPendingCheckin pendingCheckin)
        {
            base.Initialize(pendingCheckin);

            _pendingCheckin = pendingCheckin;
            pendingCheckin.PendingChanges.CheckedPendingChangesChanged += PendingChanges_CheckedPendingChangesChanged;
        }

        /// <summary>
        /// Logs a message.
        /// </summary>
        /// <param name="level" />Log level.</param>
        /// <param name="message" />Log message.</param>
        /// <param name="args" />Message arguments.</param>
        public void LogMessage(LogLevel level, string message, params object[] args)
        {
        }

        /// <summary>
        /// Subscribes to the PendingChanges_CheckedPendingChangesChanged event 
        /// and reevaluates the policy. You should not do this if your policy takes 
        /// a long time to evaluate since this will get fired every time there is a
        /// change to one of the items in the pending changes window.
        /// </summary>
        /// <param name="sender" />The source of the event.</param>
        /// <param name="e" />The <see cref="System.EventArgs" /> instance containing the event data.</param>
        void PendingChanges_CheckedPendingChangesChanged(object sender, EventArgs e)
        {
            if (!Disposed)
            {
                OnPolicyStateChanged(Evaluate());
            }
        }

        #endregion Methods
    }
}

Note that, for this check-in policy, I’ve added a copy of NArrange’s default configuration file (DefaultConfig.xml) as a file resource which I write out to disk when needed to pass to the FileArranger object.

Step 2 – Package the Custom Check-in Policy

The easiest way to package your check-in policy for deployment is to use VSIX Deployment. A VSIX package is a ZIP file that follows the Open Packaging Conventions (OPC) standard. The package contains binaries and supporting files, together with a [Content_Types].xml file and a .vsix manifest file. One VSIX package may contain the output of multiple projects, or even multiple packages that have their own manifests. For more information about the contents of a VSIX package, see Anatomy of a VSIX Package.

For this check-in policy, we’ll add a new VSIX Project to our solution as shown below:

To get the required registry key created, we’ll need to add a pkgdef file to our VSIX package the tells it where to create the key and what value to set as shown below:

[$RootKey$\TeamFoundation\SourceControl\Checkin Policies]
"TeamFoundation.Samples.CheckinPolicies"="$PackageFolder$\TeamFoundation.Samples.CheckinPolicies.dll"

This creates a key for our assembly named after our namespace which will allow Team Explorer to locate our check-in policy. Note that everyone who will be checking in files affected by your check-in policy will need to install it on their machine(s). Luckily, installing VSIX packages is really easy. You just double click on the VSIX file (generated at build time by the VSIX Project) and you’ll see a dialog box like this:

You can edit the .vsixmanifest file in your VSIX Project to customize attributes of your package like the name, description, license, icon, preview image, etc.

Step 3 – Apply the Custom Policy

In this step you add the custom policy to your team project. This ensures that the policy is evaluated each time a developer checks in a file to this team project.

1. In Team Explorer, right-click your team project, point to Team Project Settings and then click Source Control.
2. Click the Check-in Policy tab and then click Add.
3. Select the NArrange Policy and click OK and then OK again.

The policy is now applied each time a developer checks a file into this team project.

Step 4 – Validate the Custom Policy

In this step, you check-in a source file to ensure that the custom policy works correctly.

1. Make a change to a C# or VB.NET source file and then check-in the file.
2. Verify that the source file is organized, formatted and beautified by NArrange.

Additional Resources

You can download the sources for this check-in policy from Code Gallery – CheckinPolicies.zip

1. If you haven’t already, install Visual Studio 2010 SP1.
2. Download and install the Visual Studio 2010 SP1 SDK since you won’t be able to build the sources without it.
3. Download an unzip the ExtendingTeamProjects sample from the TFS SDK on Code Gallery.
4. Open the solution, right click on the TeamProjectExtensionPackage project and select Properties. Select the Debug tab and, under “Start Action,” select Start External Program and specify the full path to Visual Studio 2010 (%ProgramFiles(x86)%\Microsoft Visual Studio 10.0\Common7\IDE\DevEnv.exe). Then, under “Start Options” specify the following command line arguments: /rootsuffix Exp.
5. Build the solution.
6. Start Debugging (F5) the solution – this will start a new instance of Visual Studio.

Project Creation Wizard

You see the Project Creation Wizard when you select File, New, Team Project… from Visual Studio’s main menu. The wizard lets you specify a name and description for your new team project and then asks you to select a process template. Before you can try the sample out, you’ll need to upload the provided sample process template to your project collection by selecting Team, Team Project Collection Settings, Process Template Manager… and clicking Upload to browse for and upload the process template that’s included with the source code. When you start the sample in the Debugger (F5), it will spawn an experimental instance of Visual Studio with our package already installed and ready to go.

For this sample, we have a custom process template that declares a special group ID that includes a task list from a separate XML file. That XML file includes a set of web links arranged in a folder structure. Those links are passed to our Project Creation Wizard plug-in as the new Team Project is getting created. The plug-in also adds a new page to the wizard that lets the user enter additional web links and, optionally, to add a link to the newly created Team Project in Web Access.

This page derives from the TeamProjectWizardPage class which provides some handy methods to manage the state of the navigation buttons at the bottom of the wizard. The LinksProjectComponentCreator takes the links entered by the user, merges them with the links specified in the process template and stores an XML representation of the data in a property on the Team Project.

Team Explorer

Once your new Team Project has been created, you’ll see a new folder in Team Explorer called Links that shows the links that were specified in the sample process template as well as the links you entered when you went through the Project Creation Wizard.

If you connect to another Team Project that doesn’t use the sample process template, you’ll notice that the Links folder does not appear. That’s because our Team Explorer plug-in implements the ITeamExplorerPluginFilter interface which lets us specify whether or not our plug-in should appear for a particular team project. The Team Explorer plug-in implements a context menu for the root Links node with a single command. It shows how to handle invocations of that command as well as how to handle activation of the links in the hierarchy it presents.

Deployment

When you build the solution, you’ll see that it creates a VSIX package which is a ZIP file that follows a particular set of conventions to make it easy to install into Visual Studio. To hand this extension off to a teammate, just give them access to the TeamProjectExtensionPackage.vsix file which you can find in the output directory. When they open that file, they can click Install to install the extension into Visual Studio.

If you have any questions or comments on this sample, please post below or contact me.

One of the common requests we hear is to provide a way of automatically updating the version information in the assemblies produced by a TFS build. Unfortunately, it’s one of those features that never gets quite high enough on our priority list to get implemented. You may have noticed that we haven’t provided a solution to this problem in TFS 2010 Beta 2, but this article is going to show you how to solve this problem yourself and will even give you the sources (see the attached ZIP file) for a working solution that you can start using today.

John Robbins at Wintellect recently blogged on how to how to sync build numbers and assembly file version numbers in sync with MSBuild 4.0 and I think he’s taken a fine approach to the problem. I’m going to show you how to solve the problem with a custom workflow activity and a customized build process template. With this solution, you’ll be able to easily configure parameters in your build definition to control how your files get versioned. Like John’s approach, it does require that you customize the build number format for your build definition so that it includes an element that can be used as a version number. Other than that, it’s a nice, clean approach with no other dependencies.

Tracing Binaries to Builds

TFS already provides a way of automatically incrementing build numbers and, while the default build numbering scheme is date-based, it’s not in a format that’s suitable for using as a version number. The default build numbering scheme uses the following format:

$(BuildDefinitionName)_$(Date:yyyyMMdd)$(Rev:.r)

This format yields build numbers like “DefinitionName_20091112.1” where the last number is an auto-incrementing number for each build of this definition that occurs in a given day. Unfortunately, this doesn’t translate well to a version number. For this exercise, I’m going to use a date-based build and version number that looks like this:

$(BuildDefinitionName)_$(Year:yyyy).$(Month).$(DayOfMonth)$(Rev:.r)

This will yield a build number like “DefinitionName_2009.11.18.1” which has a component that is suitable for use as an assembly version number.

Planning the Activity

Workflow activities can be implemented in code (using the managed language of your choice) or in XAML (using the Windows Workflow designer in Visual Studio or your favorite XML editor). There are advantages and disadvantages for each. Code Activities derive from System.Workflow.Activities.CodeActivity and implement their logic in an overridden Execute method. This method executes synchronously meaning that, while it’s running, your activity (and therefore your build) can’t be cancelled. So, you’ll want to keep the implementation of this method short and sweet avoiding things like web service calls.

XAML activities can be implemented using the Workflow Designer where you can drag and drop activities from the toolbox, set properties, define arguments, etc. visually. For this exercise, we’ll be using a both types:

• ReplaceInFile. This is a code activity whose sole purpose is to replace all occurrences of a regular expression in a text file with a specified string.
• UpdateVersionInfo. This is a XML activity that extracts the version component from the current build number, finds the files matching a specification (e.g. “AssemblyInfo.*”) within a specified directory, then uses the ReplaceInFile activity to update the version information in those files to match the build number. This activity will also use the GetBuildDetail and FindMatchingFiles activities provided with TFS Build.

Developing the Activity

I created a new C# Activity Library project to contain my code and XAML activities. I named it “ActivityPack” so that I could logically add additional activities to it over time.

Once your new project is created, the Workflow Designer will automatically open on the XAML file that’s been added. If you look at the toolbox, you’ll notice that there aren’t any TFS Build activities there. To add them, follow these steps:

1. Right click on the toolbox and select Choose Items…
2. The Choose Toolbox Items dialog box will open. Select the System.Activities Components tab.
3. Click Browse and select Microsoft.TeamFoundation.Build.Workflow.dll from the following location:
   <Program Files (x86)>\Microsoft Visual Studio 10.0\Common7\IDE\PrivateAssemblies
4. Verify that the activities appear in the list and that they are checked, then click OK. The TFS Build activities should now appear in the toolbox.

Before we construct the XAML activity, we’ll need to create the CodeActivity to perform the actual regular expression search and replace. Right click on your project and select Add, New Item… Then, select Workflow from the list of Installed Templates, select Code Activity from the list of item types and specify ReplaceInFile.cs as the Name.

Next, you’ll need to add a reference to the Microsoft.TeamFoundation.Build.Client assembly by browsing to it under <Program Files (x86)>\Microsoft Visual Studio 10.0\Common7\IDE\ReferenceAssemblies\v2.0 and adding it to your using clauses. Then, add the following attribute to your CodeActivity class' declaration:

[BuildActivity(HostEnvironmentOption.Agent)]
public sealed class ReplaceInFile : CodeActivity

This attribute tells TFS that this activity is safe to load into the build controller. I’ll shed some more light on custom build activity deployment a little later. Before moving onto the XAML activity, you’ll need to build your project to get the code activity to show up in the toolbox.

The XAML activity is composed of a number of activities organized into a sequential workflow. Here’s the pseudo-code for the activity:

• Update Version Info <Sequence>
  • Validate Arguments <Sequence>
    • Validate SourcesDirectory <If>
      • String.IsNullOrEmpty(SourcesDirectory) Or (Not Directory.Exists(SourcesDirectory)) <Condition>
      • Throw ArgumentException <Then>
    • Validate FileSpec <If>
      • String.IsNullOrEmpty(FileSpec) <Condition>
      • Throw ArgumentException <Then>
    • Validate RegularExpression <If>
      • String.IsNullOrEmpty(RegularExpression) <Condition>
      • Throw ArgumentException <Then>
  • Get the Build <GetBuildDetail>
    • BuildDetail <Result>
  • Extract Version Info <Assign>
    • VersionInfo <To>
    • New System.Text.RegularExpressions.Regex(RegularExpression).Match(BuildDetail.BuildNumber).Value <Value>
  • Form Qualified Spec <Assign>
    • FileSpecToMatch <To>
    • Path.Combine(SourcesDirectory, "**", FileSpec) <Value>
  • Find Matching Files <FindMatchingFiles>
    • FileSpecToMatch <MatchPattern>
    • MatchingFiles <Result>
  • Handle Matching Files <If>
    • MatchingFiles.Any() <Condition>
    • <Then>
      • Process Matching Files <Sequence>
        • Log Version to Set <WriteBuildMessage>
        • Enumerate Matching Files <ForEach<System.String>>
          • Update Version Info in File <Sequence>
            • Log Update <WriteBuildMessage>
            • Update Version in File <ReplaceInFile>
      • Warn No Matches Found <WriteBuildWarning>

A total of 10 different workflow activities are used including the ReplaceInFile code activity we created earlier and two TFS Build activities (GetBuildDetail and FindMatchingFiles). You could implement this logic entirely in a code activity, but you would be re-implementing functionality that already exists in the activities include with VS/TFS 2010. And, the XAML activity still gets compiled into MSIL when you build your the activity library project, so there’s no separate file that needs to be managed. Lastly, it makes it easier for the Workflow run-time environment to cancel the execution of your activity.

This custom activity includes a set of Arguments. In Workflow, arguments can be in, out, in/out, or properties. If you look along the bottom edge of the Workflow Designer tool window in Visual Studio you’ll see buttons for Variables, Arguments and Imports. Variables are used to define local storage for a particular scope of your workflow. Arguments are used to define the inputs and outputs of your workflow. Imports are used like “using” statements in your code so that you don’t have to type out the full namespace everywhere. The value for these is represented as a VB.NET expression so it can (and often does) include code. Here are the arguments for the UpdateVersionInfo activity:

The SourcesDirectory is the directory to search for source files to update. When we integrate this activity into the build process template, we’ll be able to get this path from the build environment. The FileSpec is the file specification to find beneath the sources directory and it defaults to AssemblyInfo.* so the user won’t have to modify this in most cases. The RegularExpression is the regular expression used to extract a version number from the build number and to find within the files and replace with that version number. The VersionInfo argument is an output that stores the version number used by the activity which could be handy if you want to use it somewhere else in your build process. In the Workflow Designer, you can pass these arguments to activities you’re using by simply referring to them by name.

Testing the Activity

It’s a good idea to setup some unit tests to validate your custom activities outside the context of the build process. To get started, create a new unit test project and add a Workflow Activity to serve as your test workflow.

• Add a new C# Test Project to your solution
• Add a project reference to your Activity Library
• Add references to Microsoft.TeamFoundation.Build.Client and Microsoft.TeamFoundation.Build.Workflow
• Add a new C# Workflow Activity item to that project

Adding a Workflow Activity will create a XAML file in your test project that you can use as your test workflow. In this particular case, I’m using the GetBuildDetail activity which depends on an implementation of the IBuildDetail interface being available in the environment. For testing, I recommend create a mock BuildDetail object. In this case, I’ve created a separate C# Class Library project to contain this mock object and potentially additional ones as the need arises. It only overrides the BuildNumber property so that our custom activity can get a build number to extract version information from. Here’s what the overridden property looks like:

public string BuildNumber
{
    get
    {
        return String.Format("{0}_{1}.{2}.{3}.{4}",
            Environment.MachineName,
            DateTime.Now.Year,
            DateTime.Now.Month,
            DateTime.Now.Day,
            Convert.ToInt16(DateTime.Now.TimeOfDay.TotalMinutes));
    }
    set
    {
        throw new NotImplementedException();
    }
}

The getter provides a reasonable build number for our purposes and lets us exercise our custom activity outside the scope of the actual build process where it’s easier to debug and iterate on your design and implementation.

The actual unit tests need to instantiate our test workflow, set the arguments as appropriate for the test, add an instance of our mock BuildDetail object to the workflow’s extensions and invoke the workflow. The workflow itself is very simple with just the bare minimum necessary to exercise our custom activity. It’s a Sequence activity with a GetBuildDetail activity that will retrieve an IBuildDetail instance from the workflow run-time environment and pass it into our custom UpdateVersionInfo activity. I’ve also defined an Out Argument to receive the version string used by our custom activity so that I can write it out to the console.

The actual unit tests vary depending on what aspect of the activity’s behavior is being validated, but the general form of the tests follows this pattern:

// another way of specifying in arguments to our workflow
var workflow = new TestWorkflow() {
    SourceDir = SourcesDirectory,
    FileSpec = String.Empty
};

// create the workflow run-time environment and add our mock
// BuildDetail object.
var workflowInvoker = new WorkflowInvoker(workflow);
workflowInvoker.Extensions.Add(new BuildDetail());

try
{
    workflowInvoker.Invoke();
}
catch (expectedException)
{
}

The main test in this example uses a typical AssemblyInfo source file for C#, VB.NET and C++ (CLR) and runs the UpdateVersionInfo activity on them to verify that the files are updated as expected.

Integrating the Activity

Build process templates reside in version control and there’s no way to queue a build in TFS using a customized build process template that only exists in your local file system. So, we’ll need a working copy of the default build process template to avoid interfering with any existing build definitions. One way of managing this is to branch the default build process template and do your customizations in the branched version. That way you can create a test build definition that uses the branched build process template without interfering with your other builds. You can also add the branched version to your solution so that you can edit it in the same context as your custom activity. In the provided example, I’ve added it to a Templates folder beneath the unit test project (and set its “Build Action” to “None”).

Once you’ve verified your activity, customized the build process template, and validated its behavior, you can merge it back to the BuildProcessTemplates folder (or whichever folder you’re using to store your build process templates) and your builds can immediately get the benefit of it. Note that, in this case, you’ll need to update the build number format for your build definitions before using the provided activity.

You’ll want to review the build process template you’re integrating with when deciding where to insert your custom activity. In this case, I’ve placed it at the end of the Initialize Workspace sequence so that it happens immediately after the “Get.”

I’ve also added two In Arguments that will be visible in the build definition editor to make it easy for users to customize the behavior of the custom activity. These arguments are file spec (e.g. AssemblyInfo.*) and regular expression (e.g. "\d+\.\d+\.\d+\.\d+"). Both of these arguments have default values so they don’t have to be set but you can override them if appropriate. To expose arguments to the build definition editor, you add an argument just like you would for any XAML workflow. In the screen shot below, you can see the two arguments I’ve added.

The other interesting argument is “Metadata” which is where you can specify a display name, help text and other properties for your arguments that will be used in the build definition editor. If you click on the ellipsis (…) button for the Metadata property, you’ll see the Process Parameter Metadata Editor.

You’ll only need to specify the editor if you’re using a custom type for your argument of if you want to provide a custom user interface for setting a standard type. If you do specify an editor, you’ll need to specify its type using an assembly qualified name and the assembly hosting the editor will need to be in the GAC or in the Visual Studio probing path of each user’s machine.

Once you have customized the build process template and checked it into version control, you can create a test build definition that uses that build process template. Here’s how to create a build definition to use your custom build process template:

• Open Team Explorer
• Right click on the Builds folder and select New Build Definition
• Setup your build definition as desired
• Select the Process tab and click
• Click New to open the New Build Process Template dialog
• Click Select an Existing XAML file, then click Browse
• Browse for the build process template XAML file you checked into version control and click OK

The XAML in your custom build process template will be parsed and you should see your new arguments appear in the build process parameter list as shown below:

Deploying the Activity

Before checking in the branched version of the default build process template that we’ve customized, we’ll need to deploy a build of the custom activity assembly. The first step is to choose a location in version control for your custom activity assemblies. If you have custom MSBuild tasks, you can check those into the same location (or, more likely, a sub-folder beneath that location). After you check-in a build of the assembly to this location, you can modify your build controller’s properties to load custom activities from that location using the Build Controller properties dialog (accessed from Visual Studio’s Build, Manage Build Controllers… command). Select your build controller and click Properties.

You can click the ellipsis (…) button next to the “Version control path to custom assemblies” edit box to browse for the folder in version control that contains your custom assemblies. The Build Controller monitors this location for changes and, when you check-in a new version, it will pick it up automatically, and use it in all subsequent builds that get queued on that Controller. The contents of that folder will be automatically distributed to all build agents participating in builds for that controller.

Conclusion

I hope you’ve found this article to be a useful introduction to build process customization in TFS 2010 and custom workflow activity development. I wanted to provide something that was just complex enough to really illustrate how you would do this in a production environment. You can download the complete sources for the solution here:

Download the complete solution as ActivityPack.zip (updated for TFS 2010 RC) from MSDN Code Gallery.

Note that you’ll need the MSBuild Community Tasks to load and build this solution.