Manage your build system

Visual Studio Team Foundation Server 2013

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

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.

Mange Build Controllers dialog box
  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 icon Home, and then choose Builds Icon 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.

Administration Console: Build Server Configuration
  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.

NoteNote

If the message Configure Installed Features 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.View a running build process from the build server

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

  • If a Offline build controller controller or Offline build agent 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

    Build server configuration

    Work with your build controller
    Build controller

    Work with your build agent
    Build 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 Disabled build controller controller or Disabled build agend 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.

    TipTip

    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.

    TipTip

    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.