How to: Create and Manage Build Agents

Before you create a new build definition, you must first set up a computer to be designated as a build agent. For more information, see How to: Set up and Install Team Foundation Build. After Team Foundation Build and the required components have been installed on one or more computers, you can use the Visual Studio Team System user interface to create new build agents or to manage existing build agents. Each build agent can only be associated with one port. In most cases this means that each build computer hosts a single build agent. However, you can also specify an interactive port that you can use by running tfsbuildservice.exe from the command-line. The interactive port allows you to run tests that involve opening and closing Windows Forms. For more information, see TfsBuildService.exe.config File Settings in Team Foundation Server Components and How to: Configure an Interactive Port for Team Foundation Build.

Required Permissions

To perform this procedure, you must have the Administer a build permission set to Allow. For more information, see Team Foundation Server Permissions.

Creating a New Build Agent

Use the Manage Build Agents dialog box to designate a computer as a build agent.

To create a new build agent

  1. Select the team project with which you want to associate the build agent in Team Explorer.

  2. Click Manage Build Agents on the Build menu.

    The Manage Build Agents dialog box appears.

  3. Click New.

    The Build Agent Properties dialog box appears.

  4. Type a name for the build agent in the Display Name text box.

    The Manage Build Agents dialog box displays the name.

  5. Type an optional description in the Description text box.

    For example, "This build agent is dedicated to rolling builds."

  6. In the Computer name text box, enter the computer name for a computer on which Team Foundation Build is installed.

  7. In the Communications port text box, enter the port number Team Foundation uses for communicating with Team Foundation Build.

    The default value is 9191. For more information about the ports used by Team Foundation, see Team Foundation Server Security Architecture.

  8. Check the Require secure channel (HTTPS) if you want to set up your build agent to require HTTPS and Secure Sockets Layer (SSL).

    For more information about the steps required for using HTTPS, see How to: Set up a Build Agent to Require HTTPS and Secure Sockets Layer (SSL).

  9. In the Working directory text box, enter a value for the working directory on the build agent.

    The default value is $(Temp)\$(BuildDefinitionPath). The BuildDefinitionPath property expands to <Team Project>\<Build Definition Name>. You can also use BuildDefinitionId that expands to an integer identifier unique to the build definition. BuildDefinitionId is normally used to create a shorter path.

    Note

    Click the Default button to revert the Communications and Working directory text box values to their default values.

    Enabled is the default setting for the Agent status. Other values are displayed to reflect the agent status, as appropriate.

Editing and Removing Build Agents

You can also use the Manage Build Agents dialog box for editing and removing build agents that have already been designated.

To remove a build agent

  1. Select the team project that contains the build agent you want to remove in Team Explorer.

  2. Click Manage Build Agents on the Build menu.

    The Manage Build Agents dialog box appears.

  3. Select the build agent you want to remove in the Build agents list, and then click Remove.

    The build agent is removed from the list.

To edit a build agent

  1. Select the team project that contains the build agent you want to edit in Team Explorer.

  2. Click Manage Build Agents on the Build menu.

    The Manage Build Agents dialog Box appears.

  3. Select the build agent you want to edit in the Build Agents list, and then click Edit.

    The Build Agent Properties dialog box appears.

  4. On the Build Agent Properties dialog box, you can edit any of the entries, and then click OK to save them.

  5. To disable a build agent, from the Agent status drop-down menu, select Disabled.

    When the build agent status is set to Disabled, any builds that are queued will stay in the queue in an active state until the build agent is set to Enabled again.

See Also

Tasks

Walkthrough: Creating a Build Definition in Team Foundation Build

How to: Establish Permissions for Team Foundation Build Agent

How to: Set up and Install Team Foundation Build

Walkthrough: Customizing Team Foundation Build with a Custom Task

Concepts

Team Foundation Build Overview

Other Resources

Working with Build Definitions in Team Foundation Build