Deploy and Configure Build Agents
To use Team Foundation Build, your team must have at least one build agent to perform the processor-intensive work of your build process.
Each build agent is dedicated to and controlled by a single build controller. Build agents can be hosted on the same build server that hosts their build controller, but this is not required, and in some cases your team’s needs can most efficiently be met by a single build server to host a build controller that controls build agents on multiple build servers.
The build agent executes the steps of your build process that are contained in the AgentScope activity. Typically, these steps include getting files from version control, provisioning the workspace, compiling the code, running tests, and merging files back into version control.
Make sure the build server that hosts your build agents has sufficient storage and processing capabilities to match the size and complexity of the codebase and tests on the team project collection. Typically, you should host no more than one build agent per processor core on the build server. You can also enhance performance by dedicating a single physical hard drive to the working directory of each build agent.
Tip
|
|---|
|
If your team project collection is hosted on Team Foundation Service, and your team’s needs can be met by a single standard build agent, you can use the Hosted Build Controller instead of deploying your own build agent. |
Required permissions
You must be a member of the Windows Administrators group on the build server and a member of the Project Collection Build Administrators group on your team project collection. See Team Foundation Server Permissions.
What do you want to do?
To create or modify a build agent from the build server
-
Log on to the build server that you want to configure.
-
From Windows Start, run Team Foundation Administration Console.
The Team Foundation Administration Console appears.
-
In the tree pane of the Team Foundation Administration Console, expand the name of the server, and then choose the Build Configuration node.
Information about the build server appears in the content pane.
If the message
Configure Installed Features appears, see Deploy a build server. -
On the Build Configuration page:
-
To create a new build agent, choose New Agent.
-
To modify an existing build agent
choose Properties.
The Build Agent Properties dialog box appears.
-
To modify a build agent from Visual Studio
-
In Visual Studio, in Team Explorer:
-
If you are not already connected to a team project in the team project collection, then connect to the team project.
-
Choose
Home, and then choose 
Builds.
-
-
On the Builds page, choose Actions, and then Manage Build Controllers.
The Manage Build Controllers dialog box appears.
-
Select the build agent that you want to modify, and then choose Properties.
The Build Agent Properties dialog box appears.
Display Name, Description: Type a name and a description to help team members easily identify the build agent.
Controller: Select the build controller that you want to control this build agent. The build controller can run on the same build server as this build agent or on a different build server.
See the sections below for details about how to configure your build agent.
It is a best practice to install on the build agent the version of Visual Studio that your team uses on its dev machines. See Installing Visual Studio. You should also install any other software and components that are installed on your dev machines and that are required to build your app. Otherwise, you might have problems, such as some of your code projects failing to compile.
You can specify the working directory, which the build agent uses to 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.
|
Tip
|
|---|
|
You can enhance performance by dedicating a single physical hard drive to the working directory of each build agent. |
Although you can specify a literal path for the Working Directory property (for example, c:\temp\build\), a simpler and more durable 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. The most typical variable you might use is SYSTEMDRIVE, but for some situations you might also use variables such as USERNAME or HOMEPATH.
Tip
To list the environment variables on your build server, 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.
-
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
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 could fail and log this error: TF10128: The path PhysicalPath contains more than the allowed 259 characters. Type or select a shorter path.
To solve this problem, specify a working directory that results in a shorter physical path. For example you could specify $(HOMEDRIVE)\bld\$(BuildAgentID)\$(BuildDefinitionID), which would result in a working directory such as: c:\bld\3\2\.
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. 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. |
You can define a build process that performs one or more automated test runs.
|
Important
|
|---|
|
Many kinds of tests and test operations require that you install on your build agent the same version of Visual Studio that your team uses on its dev machines. See Installing Visual Studio. |
The build agent can run:
-
Code Coverage
-
Coded UI Tests (Requires a build server that is running in interactive mode. See Run your build server in interactive mode and Verifying Code by Using Coded User Interface Tests.)
-
Database Test Data Generation
-
Database Unit Tests
-
Generic Tests
-
Load Tests
-
Unit Tests
-
Ordered Tests
-
Test Impact Analysis
-
Web Tests
As the scale of your build system grows, you might 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 assign tags from the Build Agent properties dialog box, described above. You can then apply the tags to your build definitions.
The following table offers examples of tag names and the build agent capabilities that they could represent.
|
You could apply the following tag … |
To identify a build agent that can… |
|---|---|
|
x86 |
Compile 32-bit applications |
|
x64 |
Compile 64-bit applications |
|
bvt |
Run your BVT tests, which are run by your nightly BVT build. |
|
WindowsStore |
|
|
IIS |
Compile an ASP.NET Web application and then stage and host it on the computer on which the build agent is running. |
|
interactive |
Perform tasks that require an agent on a build server that is running in interactive mode. |
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 server, 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 server.
-
In Visual Studio, open the Manage Build Controllers dialog box, as explained previously in Create or modify a build agent.
-
Select the build agent that you want to remove, and then choose Remove.
|
Tip
|
|---|
|
You can also use the Team Foundation Administration Console to remove the build agent while you are logged on to the build server. |
