How to: Customize Build Numbers

Article
12/06/2010

You can customize Team Foundation Build by creating your own custom tasks that run during a build. This topic explains the steps that you must follow to customize a Team Foundation Build build definition with a task that generates build numbers.

Prerequisites

Before you create the task to customize build numbers, you must have the following:

Access to the TFSBuild.proj file of the build definition you want to customize.

The TFSBuild.proj file can be associated with more than one build definition. To determine the source control location of the TFSBuild.proj file, select the build definition in the Builds folder in Team Explorer, right-click it, and then click Edit. The TFSBuild.proj file's source control location is displayed on the Project File pane of the Build Definition dialog. By default, the TFSBuild.proj file is located in the folder $/MyTeamProject/TeamBuildTypes/MyBuildName in Team Foundation version control. MyTeamProject is the name of your team project and is the root node of all your team project sources. MyBuildName is the name that you gave to the first build definition that is associated with the TFSBuild.proj file. For more information about how to create Team Foundation Build build types, see How to: Create a Build Definition.

Important Note:

When you customize the TFSBuild.proj file, you customize each build definition associated with it.
A local workspace that contains your team project files and the build files on your local computer.

For more information, see How to: Create a Mapped Workspace and How to: Get the Source for Your Team Project.
Required Permissions.

To perform this task, you must have the Administer a build and Administer workspaces permission set to Allow. You must also have the Check in and Check out permissions set to Allow. For more information, see Team Foundation Server Permissions.

Important Note:
When you customize the TFSBuild.proj file, you customize each build definition associated with it.

Writing the Build Number Task

To write your task, you can either implement the ITask interface directly, or derive your class from a helper class Task. ITask is defined in the Microsoft.Build.Framework.dll assembly and Task is defined in the Microsoft.Build.Utilitites.dll assembly.

To customize the build number that is generated by Team Foundation Build, you must insert your task into the BuildNumberOverrideTarget target. BuildNumberOverrideTarget requires an output property called BuildNumber. The Output attribute indicates that the property is the output of your custom task. For more information about Team Foundation Build targets, see Customizable Team Foundation Build Targets.

To write your custom task

Create a Visual C# class library called MyTask that contains your custom task.

For more information, see Component Classes.
On the Project menu, click Add Reference, and select Microsoft.Build.Framework and Microsoft.Build.Utilities from the Add Reference dialog box.

Insert the following code to the class.cs file.

This example inherits from the Task helper class and uses the DateTime properties UtcNow and Ticks to generate the build number.

using System;
using Microsoft.Build.Utilities;
using Microsoft.Build.Framework;

namespace BuildNumberGenerator
{
    public class BuildNumberGenerator:Task
    {
        public override bool Execute()
        {            
            m_buildNumber = DateTime.UtcNow.Ticks.ToString();
            return true;
        }
        private string m_buildNumber;

        [Output]
        public string BuildNumber
        {
            get { return m_buildNumber; }
        }
    }
}

Build your class library to produce MyTask.dll.

Copy the built DLL to the local workspace folder that also contains the TFSBuild.proj file of your build definition.

Important Note:
You must have mapped the source control location of the TFSBuild.proj file to your local workspace before this directory structure exists on the client computer. For more information, see How to: Get the Source for Your Team Project.

If your TFSBuild.proj file was stored in the default folder in source control, the local copy of the file is located in <root>:\Local Workspace\TeamBuildTypes\MyBuildName on the client computer. Local Workspace is the local folder to which your team project is mapped, MyTeamProject is the name of your team project and MyBuildName is the name that you gave to the first build definition that is associated with this TFSBuild.proj file.

Adding the DLL File to Source Control

After you have created the DLL that contains your custom task, you must add it to Team Foundation version control. You can use the tf add and tf checkin commands to add and check in the DLL to the same location as the TFSBuild.proj file of your build definition. For more information, see Add Command and Checkin Command.

To add and check in your assembly

Click Start, point to All Programs, Microsoft Visual Studio 9.0, Visual Studio Tools, and then click Visual Studio 2008 Command Prompt. Open the local workspace you have mapped for the team project that contains the build type you want to customize.

For example, type the following at the command prompt.

> cd c:\MyTeamProject

Where MyTeamProject is the name of your team project.
Move to the location where the TFSBuild.proj file is stored.

For example, type the following at the command prompt.

c:\MyTeamProject>cd TeamBuildTypes\MyBuildName

Where MyBuildName is the name of the build definition.
To add the file to Team Foundation version control, type the following command.

c:\MyTeamProject\TeamBuildTypes\MyBuildName> tf add MyTask.dll
To check in your file to Team Foundation version control, type the following command.

c:\MyTeamProject\TeamBuildTypes\MyBuildName> tf checkin MyTask.dll

You can also use the Team Explorer to add your DLL to Team Foundation version control. For more information, see How to: Add a Project or Solution to Version Control.

Registering the Task

After you have created your task, you must register it by specifying your task in a UsingTask element in the TFSBuild.proj file. The UsingTask element maps the task to the assembly that contains the task's implementation. For more information, see UsingTask Element (MSBuild).

To register the task by modifying the TFSBuild.proj file

Start Visual Studio.
Check out the TFSBuild.proj file that you want to modify from Team Foundation version control and open it in the Visual Studio XML-editor.

Add the UsingTask element to the TFSBuild.proj file immediately after the import statement.

<UsingTask 
    TaskName="BuildNumberGenerator.BuildNumberGenerator" 
    AssemblyFile="MyTask.dll"/>

To insert your task into the BuildNumberOverrideTarget target, add the following XML, enlosed within the <Target></Target> tags, to the end of the TFSBuild.proj file.

</ItemGroup>
  <Target Name = "BuildNumberOverrideTarget" >
    <BuildNumberGenerator> 
    <Output TaskParameter="BuildNumber" PropertyName="BuildNumber"/> 
    </BuildNumberGenerator> 
  </Target>
</Project>

Click File, click Save to save your changes, and then close TFSBuild.proj.

Note

You will receive XML-schema warnings after you make these changes to the TFSBuild.proj file. You can safely ignore those warnings.
Check TFSBuild.proj back in to source control.
After you have modified the TFSBuild.proj file and saved the changes in Team Foundation version control, run the build definition.

For more information, see How to: Queue or Start a Build Definition.

You can view the custom build number in the Build Explorer. For more information, see How to: Monitor Build Progress.

Share via