Create and Work with Build Agents

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.

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.

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.

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.

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.

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