Deploy and configure a build controller

To use Team Foundation Build, your team must have at least one build controller to perform lightweight tasks and distribute the processor-intensive work of your build process to its pool of build agents.

Each build controller is dedicated to a single team project collection. The build controller performs some lightweight tasks, such as determining the name of the build, creating the label in version control, logging notes, and reporting status from the build. The build controller uses the AgentScope activity to delegate processor-intensive work, such as compiling code or running tests, to the build agents within its pool. These build agents can be hosted either on the same build server, or on a different build server.

Because a build controller does not typically require significant processor time, in many cases you can host it on the same computer as your Team Foundation Server, as shown above, or on a low-powered physical or virtual machine.

However, a build controller can demand a significant amount of memory in certain situations, so you should provide sufficient memory as needed to ensure it functions properly. Or, depending on your team’s needs and resources, you might want to run the build controller on a different computer than your Team Foundation Server.

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 Permission reference for Team Foundation Server.

What do you want to do?

• Create or modify a build controller

• Enable your build processes to leverage supplemental binaries

• Specify the maximum number of concurrently running builds

• Remove a Build Controller

• Use a build controller with a team project collection hosted on Visual Studio Online

Create or modify a build controller

To create or modify a build controller from the build server

1. Log on to the build server.

2. From Windows Start, run Team Foundation Administration Console.

3. In the tree pane of the Team Foundation Administration Console, expand the name of the server, and then choose the Build Configuration node.

   Note

   If the Configure Installed Features message appears, see Deploy a build server.

4. On the Build Configuration page:

   • If a controller is not listed, choose New Controller.

   • If a controller is already listed:

     

     Choose Properties.

   The Build Controller Properties dialog box appears.

To modify a build controller from Visual Studio

1. In Visual Studio, in Team Explorer:

   1. If you are not already connected to a team project in the team project collection, then connect to the team project.

   2. Choose Home, and then choose Builds.

2. On the Builds page, choose Actions, and then Manage Build Controllers.

   The Manage Build Controllers dialog box appears.

   

3. Select the build controller that you want to modify, and then choose Properties.

   The Build Controller Properties dialog box appears.

In the Display Name and Description fields: Type a name and a description that can help team members easily identify the appropriate build controller when they define their build processes.

See the sections below for details about how to configure your build controller.

Enable your build processes to leverage supplemental binaries

You can enable your build process to leverage binaries that you have uploaded to your Team Foundation Server, for example:

• Assemblies that contain your custom workflow activities. See Use and develop custom build process activities.

• Third-party unit test frameworks. See Run tests in your build process.

• Custom MSBuild tasks

To enable your build processes to leverage these kinds of code, upload the binaries to the folder (or any of its descendant folders) that you specify in the Version control path to custom assemblies box. When you set or modify the value in this box, the build server automatically restarts to load the assemblies.

Tip

If your build results include a TF215097 error message, your build process might include a custom activity that is not in this folder or in any of its descendant folders.

Specify the maximum number of concurrently running builds

In most cases, you should leave this value set to Default to number of enabled agents. However, in some cases, you might want to control the depth of the build queue. For example:

• You observe that too many builds show a status of Running even though many of them are stalled as they wait for a build agent to be assigned to them. This situation can confuse the team. To avoid the problem, select Specify the maximum and then specify a value that is lower than the number of build agents that are pooled under the build controller.

• You design a custom build template to enable your builds to leverage more than one build agent at a time, from a pool of 12 build agents under the build controller. The builds that are processed by this build controller are based on a custom build template that concurrently delegates to three build agents. To make the build queue data more useful, you could configure the build controller with Maximum number of concurrently running builds set to Specify the maximum, with a value of 4.

Remove a Build Controller

1. In Visual Studio, open the Manage Build Controllers dialog box, as explained above in Modify a build controller from Visual Studio.

2. Select and then remove each build agent under the build controller, either by choosing Remove, or by choosing Properties and then using the Build Agent Properties dialog box to assign the build agent to another build controller.

3. Select the build controller that you want to remove, and then choose Remove.

Note

You can also use the Team Foundation Administration Console to remove the build controller while you are logged on to the build server. But if you do, you might still need to use Visual Studio, or log on to other build servers first, to remove any remote build agents pooled by the build controller.

Use a build controller with a team project collection hosted on Visual Studio Online

Use the Hosted Build Controller: If your team project collection is hosted on Visual Studio Online, you might be able to skip deploying your own build controller and use the Hosted Build Controller instead. To use the Hosted Build Controller, you simply select it when you define your build process. See Use the Hosted Build Controller.

Use an on-premises build controller: If your build process requires resources outside of the Hosted Build Controller capabilities, then you can connect your on-premises build controller to your hosted team project collection.

Important

You must use the older {org}.visualstudio.com URL, not the newer dev.azure.com/{org} URL.

Next Steps

• Deploy and configure build agents
  Use a build agent to do the processor-intensive work of your build. This includes getting files from version control, provisioning the workspace, compiling the code, and running tests. You can host one or more build agents on a build server.

• Set up drop folders
  You can prepare and then designate one or more drop folders so that your build system can deliver binaries, test results, and log files to your team.

• Scale out your Team Foundation Build system
  As your team and your code base grow, you can expand your build system incrementally, with relative ease.

• Manage your build system
  After you deploy your build server, you can manage it from the Team Foundation Administration Console. You can manage the build controller and build agents from either Team Foundation Administration Console or from Visual Studio.

• Define your build process
  After your build system is in place, you are ready to define your build process, which contains your instructions about which code projects to compile, what actions trigger a build, what tests to run, and any other procedures required by your team.