Manage your build system

You’ve configured your build servers, including your build controllers and build agents. You’ve defined build processes to meet your team’s needs. Your team is now running and managing your automated builds to compile and test your app.

Occasionally, you will run into situations in which you need to monitor and manage your build system, such as when you are diagnosing problems or scaling out your build system.

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?

• Check the status, manage, and modify your controllers and agents from Visual Studio

• Check the status, manage, and modify your server, controller, and agents from the administration console

• Start, stop, or restart a build server

• Restart a build controller or build agent

• Enable or disable a controller or agent

• Specify the maximum number of concurrently running builds for a controller

• Register or unregister a build server

• Monitor the health of your build server

• Use event logs to diagnose problems

• Take next steps

Check the status, manage, and modify your controllers and agents from Visual Studio

Sometimes you want to check the status, and manage your build controllers and build agents, for example, when a queued build process is not starting or is failing to make progress. You can do all this directly 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.

Next Steps

• Check the status of your controllers and agents

  • If the State is Available and Status is Enabled, then the component is probably functioning correctly.

  • If the State is Disabled, you can select the component, choose Properties, and then re-enable the component.

  • If the Status is Offline, then the component is disconnected. Log on to the build server and make sure it is registered and can connect to your Team Foundation Server.

• View, modify, enable, or disable a controller or agent
  Select it and choose Properties, and then see Deploy and configure a build controller or Deploy and configure build agents.

• Remove a controller or agent
  See Remove a build controller or Remove a build agent.

• Manage or resolve problems with a build server, controller or agent
  See the sections below for more information.

Check the status, manage, and modify your server, controller, and agents from the administration console

When you want to check or manage your build system components, you sometimes need the additional capabilities that are available when you log on to the build server.

1. Log on to the build server that you want to configure.

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

   The Team Foundation Administration Console appears.

3. In the tree pane, expand the name of the server.

4. Choose the Build Configuration node.

Note

If the message Configure Installed Features appears instead of a view such as the one above, see Deploy a build server.

Next Steps

• Check the status of your controllers and agents

  • If any of the build controllers or build agents are processing a build, you can see messages about this ongoing work in real time from the Team Foundation Administration Console.

    

    For more information about monitoring a running build process, see Run, monitor, and manage builds and Diagnose problems in your build.

  • If a controller or agent is red, then the component is disconnected. Make sure your build server can connect to your Team Foundation Server.

• Work with your build server

  

  • Choose Restart, Stop, or Start to start, stop, or restart the build server.

  • Choose Properties to deploy and configure a build server.

  • Choose Register or Unregister to register or unregister a build server.

  • Choose Events… to use event logs to diagnose problems.

  • Monitor the health of your build server.

• Work with your build controller
  

  • Choose Properties and see Deploy and configure a build controller.

  • Choose Restart to restart the controller.

  • Choose Enable or Disable to enable or disable the controller.

• Work with your build agent
  

  • Choose Properties and see Deploy and configure build agents.

  • Choose Restart to restart the agent.

  • Choose Enable or Disable to enable or disable the agent.

Start, stop, or restart a build server

It is a good idea to stop the build server whenever you are performing maintenance on it. From the Team Foundation Administration Console, choose Stop to take all build controllers and build agents hosted on the build server offline. Choose Start when you are ready to put the controllers and agents back in service.

If the build server fails to respond (for example, if a build process fails to start or make timely progress), choosing Restart might help. When you restart the build server, the Team Foundation Build Service process is closed and re-launched into a state that is nearly as fresh as if you rebooted the computer. If builds are currently being processed by the build controller or any build agents on this build server, those builds are cancelled.

Restart a build controller or build agent

When restarting the build server is too disruptive or unnecessary, you can choose the Restart link of the build controller or the build agent from the Team Foundation Administration Console. When you restart a build controller, it reloads assemblies, and all builds it is processing are aborted. When you restart a build agent, it discards the app domain, reloads assemblies, and the build that it is processing is aborted.

Enable or disable a controller or agent

You can disable a controller or agent to prevent builds from being assigned to it. If you disable a controller or agent that is processing a build, the build completed before the component is disabled.

This capability can help you tune or temporarily modify the way your build system works. For example, you suspect that a build server is running too many build agents because builds are being processed too slowly. You can disable some build agents and assess how this affects performance. You can then later re-enable one or more build agents as necessary.

To enable or disable a build agent or build controller:

• From the Visual Studio Manage Build Controllers dialog box, select the build controller or build agent that you want to disable or enable, and then choose Properties. Either the Build Controller Properties or Build Agent Properties dialog box appears. Clear or select either the Build Controller service is enabled or the Build Agent service is enabled check box.

• From the Team Foundation Administration Console, locate the build controller or build agent that you want to disable or enable, and then chose its Enable or Disable link.

Register or unregister a build server

From the Team Foundation Administration Console, choose Unregister if you want to take the build server out of your build system. When you choose Unregister, you are asked whether you want to delete any build controllers and build agents that are running on the build server:

• Choose No if you want to temporarily decommission the build server. The controllers and agents on this build server are not deleted from your team project collection and appear with a Status of Offline in the Visual Studio Manage Build Controllers dialog box. You can later choose Register and restore the build controller and build agents.

• Choose Yes if you want to delete all configuration settings for this build from the team project collection. All information about any build controller and any build agents is deleted.

If the message Build Service is not registered appears, you can choose Register to re-commission the build server and enable it to host build controllers and build agents.

Tip

You can also replace an existing build server when you deploy a new build server. For example, you might want to host the same configuration and set of build controllers and build agents on a new, more powerful computer. See Configure Team Foundation Build Service using the Team Foundation Server configuration tool.

Monitor the health of your build server

While logged on to the build server, you can confirm Team Foundation Build Service is running, get information about the resources it is consuming, and confirm the general health of the build server.

1. Run Windows Task Manager (Task Manager on Windows 8).

2. On Windows 8, if the More details link appears, choose it.

3. Choose the Process tab.

4. On versions of Windows other than Windows 8, make sure Show processes from all users is selected.

5. On what version of Windows is your build server running?

   • Windows 8: Locate the Visual Studio Team Foundation Build Service Host process. It should be located in the Background processes section, or if your build server is running in interactive mode, in the Apps section. Observe the CPU, memory, disk, and network resources that the process is consuming.

   • Another Windows version: Locate the TFSBuildServiceHost.exe process. Observe the CPU and memory resources that the process is consuming.

6. Use the other tabs in Task Manager to confirm the general health of the build server. For example, you can choose the Performance tab to confirm the computer has sufficient processor and memory resources. You can then choose Resource Monitor (on Windows 8, Open Resource Monitor).

Use event logs to diagnose problems

Use the Event Viewer to get information that can help you monitor how your build server is operating and to diagnose problems with your build server or your build process.

View recent events

Begin by checking the most recent events. From the Team Foundation Administration Console, choose Events… to open Event Viewer to display the most recent informational, warning, and error messages.

View the operational log

To get more detailed information over a longer period of time, in the Event Viewer, in the tree pane expand Applications and Services Logs, Microsoft, Team Foundation Server, Build-Services, and then choose Operational.

View the analytic log

In most cases you don’t need to read the internal messages exposed by the analytic log. However, this data may be useful when you are working with customer support to resolve an issue.

To enable the analytic log

1. In Event Viewer, choose View, Show Analytic and Debug Logs.

2. In the tree pane, expand Applications and Services Logs, Microsoft, Team Foundation Server, Build-Services, and then choose Analytic.

3. While Analytic is still selected, open its shortcut menu and then choose Enable.

Tip

By default when this log reaches a data limit, the Event Viewer stops gathering data. To modify the limit or change this behavior, select the Analytic node, open it’s shortcut menu, and choose Properties.

Customize and view the data

To save the data in a permanent file that is easy to scan and view, in the tree pane, select one of the nodes described above, open its shortcut menu, and then choose Save All Events…. Use the Save As dialog box to save the data in the format that meets your needs.

Next Steps

• Deploy and work with a build server
  To use Team Foundation Build with an on-premises Team Foundation Server, you must deploy at least one build server. The server can be deployed on a physical computer or a virtual machine.

• Deploy and configure a build controller
  Use a build controller to perform lightweight tasks and distribute the processor-intensive work of your build process to its pool of build agents. You can host one build controller on a build server.

• Deploy and configure build agents
  Use a build agent to do the processor-intensive work of your build, includes getting files from version control, provisioning the workspace, compiling the code, and running tests. You host can 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.