Create and Work with Build Agents

  • Article

To use Team Foundation Build, your team must have at least one build agent. A build agent does the processor-intensive work of your build, which includes getting files from version control, provisioning the workspace, compiling the code, running tests, and merging files back into version control. Each build agent is dedicated to and controlled by a single build controller.

Before You Start

  • You should learn about the role that build agents play in a build system, in addition to different ways to use them. For more information, see Understanding a Team Foundation Build System.

  • A build agent is hosted on a build machine. Therefore, you must configure a build machine before you can create and work with a build agent. Each build machine can host one or more build agents. For more information, see Configure a Build Machine.

In this topic

  • Required Permissions

  • Create a Build Agent

  • Modify a Build Agent

  • Build Agent Properties Dialog Box

    • More about the Working Directory Property

  • Use Your Build Agent to Run Tests

  • Install Additional Software

    • Install Software Required to Compile Code

    • Install Software Required to Perform Other Tasks

  • Assign Tags to a Build Agent

  • Remove a Build Agent

Required Permissions

To perform this procedure, you must be a member of the Administrators group on the build machine, and your Manage build resources permission must be set to Allow. For more information, see Team Foundation Server Permissions.

Create a Build Agent

To create a build agent

  1. Log on to the build machine on which you want to create the build agent.

  2. Click Start, click All Programs, click Microsoft Team Foundation Server 2010, and then click Team Foundation Administration Console.

    The Team Foundation Administration Console appears.

  3. In the tree pane, expand the name of the server, and then click the Team Foundation Build node.

    Information about the build machine appears in the content pane.

    If the message Build Service configured for… does not appear, see Configure a Build Machine.

  4. Click New Agent.

    The Build Agent Properties dialog box appears. For more information, see Build Agent Properties later in this topic.

  5. When you finish modifying the properties of the agent, click OK.

  6. If the Start link appears immediately under the name of the build agent, click it.

Modify a Build Agent

You can modify a build agent from either a client machine or directly on the build machine that hosts the build agent.

To modify a build agent from a client machine

  1. In Visual Studio, open the Build menu, and then click Manage Build Controllers.

    The Manage Build Controllers dialog box appears.

  2. Click the build agent that you want to modify, and then click Properties.

    The Build Agent Properties dialog box appears.

To modify a build agent on the build machine

  1. Log on to the build machine that runs the build agent that you want to modify.

  2. Click Start, click All Programs, click Microsoft Team Foundation Server 2010, and then click Team Foundation Administration Console.

    The Team Foundation Administration Console appears.

  3. In the tree pane, expand the name of the server, and then click the Team Foundation Build node.

  4. Immediately under the name of the build agent that you want to modify, click Properties.

    The Build Agent Properties dialog box appears.

Build Agent Properties Dialog Box

In the Build Agent Properties dialog box, you can view or change the display name and the description, in addition to other properties that affect how the build agent functions.

Display Name, Description

Provide a name and a description that can help team members easily identify and get important information about the build agent.

Controller

Specify the build controller that you want to control this build agent. The build controller can run on the same build machine as this build agent or on a different build machine.

Computer Name

This box displays the name of the build machine that hosts this build agent.

Working Directory

Use this box to specify the path to the working directory. For more information, see More about the Working Directory Property.

Build Agent service is enabled

Select this check box to enable this build agent to function, or clear it if you want to disable it and prevent builds from being assigned to it.

Tip

It is a good idea to disable a build agent whenever you are performing maintenance on the build machine.

More about the Working Directory Property

The build agent uses the working directory for operations where the agent must read from or write to files. For example, source files are copied to subdirectories in this folder, and binaries are created and stored in other subdirectories in this folder.

Working Directory Tokens

Although you can specify a literal path for the Working Directory property (for example, c:\temp\build\), a more flexible approach is to use tokens to specify the path. You can use two kinds of tokens:

  • Environment variables: Environment variables contain information about the environment for the system and the user who is logged on.

    For example, you have configured Team Foundation Build Service to run under an account that is called BuildSvcAcct. You specify $(HomeDrive)\Builds as the working directory for a build agent on a build machine that is running Windows Server 2008. As a result, the build agent will typically use, as its working directory, a physical directory that approximates the following location: C:\Builds.

    Tip

    To list the environment variables on your build machine, open a command prompt, and type set.

  • Team Foundation Build variables: You can use the following variables in a build agent working directory:

    • $(BuildAgentId): An automatically generated integer that uniquely identifies a build agent within a team project collection.

    • $(BuildAgentName): The Display Name of the build agent.

    • $(BuildDefinitionId): An automatically generated integer that uniquely identifies a build definition within a team project collection.

    • $(BuildDefinitionPath): The team project name and the build definition name, separated by a backslash.

Working Directory Example

For example, you have a build agent that is named BuildBot3. You have defined two builds that are called NightlyBuild and WeeklyBuild in a team project that is called CoolApp. In the Working Directory box, you specify the following value: $(SystemDrive)\TeamBuilds\$(BuildAgentName)\$(BuildDefinitionPath). As a result, the BuildBot3 build agent creates and uses the following two working directories:

C:\TeamBuilds\BuildBot3\CoolApp\NightlyBuild

C:\ TeamBuilds\BuildBot3\CoolApp\WeeklyBuild

Make Sure Working Directory is Not Too Long

The working directory that you specify must not cause the build agent to produce any physical paths that are longer than 259 characters. Otherwise, your builds will fail and log this error: TF10128: The pathPhysicalPath contains more than the allowed 259 characters. Type or select a shorter path. This error may surprise you because you may not ordinarily notice the physical paths that the build agent creates.

To solve this problem, you can specify a working directory that results in a shorter physical path. For example you could specify the following directory: $(HOMEDRIVE)\bld\$(BuildAgentID)\$(BuildDefinitionID), which would result in a working directory that approximates the following path: c:\bld\3\2\.

Subdirectories Created in the Working Directory

The build agent creates and works in the following subdirectories under this path.

Subdirectory

Used to Store Files…

Sources

Read by the build agent, such as source files. You specify the files that it downloads in the Workspace settings for each build definition. For more information, see Work with Build Workspaces.

Binaries

Compiled by the build agent, such as compiled application files.

TestResults

Produced by whatever tests the build agent ran.

Use Your Build Agent to Run Tests

You can design a build process that runs one or more automated test runs. As the following table shows, some kinds of tests and test operations require a build agent that meets special requirements.

Type of test activity

Visual Studio 2010 must be installed on build machine

Other requirements and information

Code Coverage

Yes

None

Coded UI Tests

Yes

The build machine must be running as an interactive process. For more information about how to set up this kind of build machine, see Configure a Build Machine.

For more information about these kinds of tests, see Testing the User Interface with Automated UI Tests.

Database Test Data Generation

No

None

Database Unit Tests

Yes

None

Generic Tests

No

None

For more information, see Creating an Automated Test That Runs an Executable Using Generic Tests.

Load Tests

Yes

None

For more information, see Setting Up Your Test Run Sequence Using Ordered Tests.

Unit Tests

No

None

Ordered Tests

No

None

Test Impact Analysis

No

None

Web Tests

Yes

None

For more information about how to define a build process that runs tests, see Use Your Build System to Work with Tests.

Install Additional Software

For your build agent to perform certain tasks, you may need to install additional software on the build machine.

Install Software Required to Compile Code

For a build agent to build many of the most typical projects, no additional software is required. For example, without any additional software installed, a build agent can compile a basic Visual C# WPF application.

However, you must install additional software to compile other types of projects. For example, you must install Visual Studio to compile a Setup Project.

To ensure that the build agent can compile your projects

  1. Install whatever version and edition of Visual Studio your team uses on the build machine on which the build agent is running.

  2. Install any other software and components that are installed in your developer environment and that are required to build your application.

Install Software Required to Perform Other Tasks

For a build agent to perform various other tasks, additional software might need to be installed on the build machine. The following table identifies some common build agent tasks and the software that is required to perform those tasks.

For the build agent to…

The following software must be installed on the build agent computer…

Build ASP.NET Web Application projects

Visual Studio 2010

Build C++ projects

Visual Studio 2010

Assign Tags to a Build Agent

As the scale of your build system grows, you will probably need to define specialized build agents. Whenever a build agent has special capabilities or is intended for a specific kind of usage, you should assign one or more tags to that agent. This way, when a team member creates a build definition that requires a certain kind of build agent, they can specify the tag in their build definition.

You can apply more than one tag to a build agent. For example, you could create a build agent with the tags x86 and Release to indicate an agent that is set up to compile the Release configuration of a 32-bit application.

If you run multiple build agents on the same build machine, they probably will all have the same capabilities. Therefore, you probably will want to apply the same tags to all build agents on that build machine.

Use tags to represent build agent capabilities

The following table offers examples of tag names and the build agent capabilities that they could represent.

You could apply the following tags to the build agent…

To identify a build agent that can …

x86

Compile 32-bit applications

x64

Compile 64-bit applications

IIS

Compile an ASP.NET Web application and then stage and host it on the build computer on which the build agent is running

test, stress

A build agent that is running on a build computer on which Test Professional 2010 has been set up for running load and stress tests.

Use tags to load balance your build process

You can use tags to balance the load of the build processing work that your team must perform. For example, you might have one build definition that is called Check-in Build that validates your check-ins. (For more information, see Define a Gated Check-In Build Process to Validate Changes.) This build definition is run often, and only one instance of it can be run at a time. Therefore, you set up a build machine that has high performance hardware (such as a fast multi-core processor and a fast hard disk drive). You then create a build agent on that machine and assign it the tag check-in. You set up the build definition to run only on a build agent that has the check-in tag.

You have another build definition called Fast Track Build, which you use to process the builds of a top-priority project that one team is working on. You set up another build agent that meets the requirements of this special project. You assign it the tag FastTrack and then set up the build definition to run only on a build agent that has this tag.

To apply a tag to a build agent on a client machine

  1. On the Build menu, click Manage Build Controllers.

    The Manage Build Controllers dialog box appears.

  2. Click the build agent to which you want to apply a tag, and then click Properties.

    The Build Agent Properties dialog box appears.

  3. Use one of the following methods to apply one or more tags:

    • Select one or more tags from the list.

    • Click the Add new tag link. In the Add New Tag dialog box, type the name of the tag that you want to apply.

To apply a tag to a build agent on the build machine

  1. Log on to the build machine that runs the build agent that you want to modify.

  2. Click Start, click All Programs, click Microsoft Team Foundation Server 2010, and then click Team Foundation Administration Console.

    The Team Foundation Administration Console appears.

  3. In the tree pane, expand the name of the server, and then click the Team Foundation Build node.

  4. Immediately under the name of the build agent, click Properties.

    The Build Agent Properties dialog box appears.

  5. Use one of the following methods to apply one or more tags:

    • Select one or more tags from the list.

    • Click the Add new tag link. In the Add New Tag dialog box, type the name of the tag that you want to apply.

Remove a Build Agent

You can remove a build agent either by using a client machine or directly from the build machine that hosts the build agent.

Note   Removing the build agent does not un-install Team Foundation Build Service from the build machine.

To remove a build agent by using a client machine

  1. On the Build menu, click Manage Build Controllers.

    The Manage Build Controllers dialog box appears.

  2. Click the build controller or build agent that you want to remove, and then click Delete.

To remove a build agent from its build machine

  1. Log on to the build machine that runs the build agent that you want to modify.

  2. Click Start, click All Programs, click Microsoft Team Foundation Server 2010, and then click Team Foundation Administration Console.

    The Team Foundation Administration Console appears.

  3. In the tree pane, expand the name of the server, and then click the Team Foundation Build node.

  4. Immediately under the name of the build agent, click Delete.

See Also

Concepts

Define Your Build Process

Change History

Date

History

Reason

August 2011

Made a few minor adjustments to the table in the "Use Your Build Agent to Run Tests" section.

Information enhancement.

May 2011

Added information about how to run tests.

Information enhancement.