Team Foundation Build Quick Start

12/24/2010

Contents

Preparing for Team Build

In this section, we’re going to look at the preparations that you’ll need to make to set up the necessary infrastructure before you start automating your build processes using Team Build. Assuming that you’ve already set up your Team Foundation Server, the first step is to set up at least one build controller and agent to execute your builds. A build controller or build agent is simply a machine that has the Team Build service installed on it and is configured as a build controller, one or more build agents, or both.

Team Build Deployment Topologies

The ability to have multiple build controllers per Team Project Collection and multiple build agents per build controller provides a lot of flexibility, but it also raises questions about when and why you’d want to do this.

Reasons for wanting to have multiple build controllers include:

Build agent pooling Build controllers are a grouping of build agents so that you can use multiple build controllers to segregate your build agents into pools. You may want to do this to dedicate certain agents for certain types of builds [for example, release builds or continuous integration (CI) builds] or to group build agents by physical location for performance.
Using different custom workflow activities or extensions Build controllers specify a version control path from where custom workflow activities and extensions are downloaded. Having multiple controllers allows you to have a controller use a different set of custom workflow activities or extensions. For example, you might have a controller dedicated to testing new versions of custom workflow activities or extensions before you roll them out for production builds.

Reasons for wanting to have multiple build agents include:

Redundancy Having more than one build agent will allow developers to continue to process builds in the event of a build agent failure.
Ability to scale out Multiple build agents will allow builds to be processed concurrently.
Distributed builds By customizing the build process template (which is discussed in Chapters 15 and 16), you could enable a single build to be distributed across multiple build agents to reduce build time.
Mutually exclusive dependencies Different versions of the software that you’re building may have dependencies on different versions of third-party software that can’t be installed side by side on your build agents. Having multiple build agents enables you to have different versions installed on different build agents. Later in this chapter, we discuss agent tags, which can be used to identify which agents have which dependencies installed.

The other topological consideration is whether you should install build controllers and build agents on the same machine. This is a very valid topology and is especially useful in smaller environments (for example, the build controller has only a single agent) because it requires only one machine. If your build controller is going to manage multiple build agents, then it is recommended to be on its own machine.

What Makes a Good Build Machine?

You should take the following factors into account when selecting and configuring hardware to run Team Build (these factors apply to both build controllers and agents):

Build machines should be kept as simple as possible. Even minor changes on a build machine can affect the outcome of a build, and if the configuration of a build machine is complex, then it increases the chance of discrepancies if a build agent needs to be rebuilt, when adding additional build machines, or when reproducing an old build.
Builds usually have to read a large amount of data (the source files) from the Team Foundation Server and write a large amount of data (the build outputs) to the drop folder. Because of this, the build agent should have fast network access to both of these locations. In Chapter 14, we look at how to configure Team Build to use the Team Foundation Proxy to improve performance when the build agent has limited bandwidth to the Team Foundation Server.
Builds are typically I/O-bound rather than CPU-bound (although there can be exceptions to this), so investing in fast disk and network infrastructure will have a large impact on the performance of your builds.
Build machines should only be build machines—nothing else. Running other services on the build machine results in Team Build having to compete with them for resources. In particular, avoid disk-intensive services such as the Indexing Service and antivirus software. Many corporate environments require antivirus software; in this case, you should disable scanning for the build agent’s working folders to improve performance and reduce the chance that locking issues will cause spurious build failures.
The build agent needs sufficient disk space to store a copy of the source code and build outputs for each build definition. You should also allow additional disk space for any temporary files produced during the build process.
The TEMP directory should be located on the same logical drive as the Team Build working directory. The get process is more efficient in this configuration because it can perform move rather than copy operations.
Team Build 2008 and later have the ability to take advantage of the parallel build functionality introduced in MSBuild 3.5 so multiple processors can improve the performance of your builds.

There might be circumstances where Team Build needs to be installed on developers’ workstations. This can be particularly useful when developing, testing, and debugging build customizations or to allow developers to run full end-to-end builds on their local machines.

Installing Team Build on the Team Foundation Server

Although it’s technically possible to install a build controller, a build agent, or both on the same machine as the Team Foundation Server, this is not recommended for a number of reasons:

Compiling software is particularly resource-intensive, and this could be detrimental to the performance of the Team Foundation Server.
Build scripts and unit tests might be written by people who aren’t Team Foundation Server administrators, and having these running on the Team Foundation Server could compromise its security, integrity, and stability.
Build scripts and the projects being compiled often require third-party software or libraries to be installed on the build agent, and installing these on the Team Foundation Server could also compromise its security, integrity, and stability.

Setting Up a Build Controller

The Team Build installation process is quite simple, but it is recommended that you document the process that you use to set up your first build controller and agent so that the process can be repeated if you add additional build controllers or agents to your environment in the future.

Installing Prerequisites

Before installing a build controller, you will need a domain account for the Team Build service to run if you choose not to use the NT AUTHORITY\NETWORK SERVICE account. This account doesn’t need to be, and shouldn’t be, that of an administrator on either the build server or the Team Foundation Server, but it does need to be added to the Project Collection Build Service Accounts group of the Team Project Collection for which it will execute builds. See the section entitled “Team Build Security,” later in this chapter, for more information about securing Team Build.

Installing a Build Controller

The installation process for build controllers is as follows:

Insert the installation media.
Run setup.exe from either the TFS-x86 or TFS-x64 directory (for 32-bit or 64-bit machines, respectively).
Click Next on the Welcome To The Microsoft Team Foundation Server 2010 Installation Wizard page.
Accept the license terms and click Next.
Select Team Foundation Build Service on the Select Features To Install page and click Install.
Make sure that the Launch Team Foundation Server Configuration Tool check box is selected on the last page of the wizard, and then click Configure.
Select the Configure Team Foundation Build Service wizard and click Start Wizard.
Click Next on the Welcome To The Build Service Configuration Wizard page.
Select the Team Project Collection to which you want to connect the build controller and click Next.
On the Build Services page, choose how many build agents that you want to run on the build controller machine (this can be none if it’s a dedicated controller machine), choose the Create New Build Controller option, and click Next.
On the Settings page, enter the account details for your Team Build service account and click Next.
On the Review page, review the settings that you’ve entered, and then click Next.
On the Readiness Checks page, resolve any errors and then click Configure.
On the Complete page, click Finish.

Configuring a Build Controller After Installation.

Once a build controller has been installed, you can configure it either from Visual Studio on any computer (as described here) or from the Team Foundation Server Administration Console on the build controller itself.

Open Visual Studio 2010.
Open Team Explorer.
Expand a Team Project.
Right-click Builds, and click Manage Build Controllers. This will open the Manage Build Controllers dialog shown in Figure 13-2.

Figure 13-2 Manage Build Controllers dialog
Select the build controller that you want to configure and click Properties to open the Build Controller Properties dialog shown in Figure 13-3.

The Display Name and Description fields are used to describe the build controller.

The Computer Name field is the host name of the build controller. This will be used by Team Build to communicate with the build controller so the Computer Name should be resolvable from the Team Foundation Server.

The Version Control Path To Custom Assemblies is a server path to a folder containing any custom workflow activities or extensions. The build controller and its agents will download any custom assemblies from the location as required. Creating custom activities is discussed in detail in Chapters 15 and 16.

Figure 13-3 Build Controller Properties dialog

Setting Up a Build Agent

The build agent installation process is quite similar to the build controller installation process, but because the majority of the build process is run on the build agent, the prerequisites are more complex.

Installing Prerequisites

Before installing a build agent, the following prerequisites need to be met:

You will need a domain account for the Team Build service to run if you choose not to use the NT AUTHORITY\NETWORK SERVICE account. This account can, and usually is, the same account used to run the build controller.
You will need any other software or libraries required by your build process or the software you’re building. This would include any utilities or MSBuild tasks called by your build process (such as the MSBuild Extension Pack), as well as any global assembly cache (GAC) references required by the projects you’re building (such as the Microsoft Office primary interop assemblies).
You will need the appropriate version of Visual Studio to use any of the features listed in Table 13-1 as part of your build process.

Table 13-1 Team Build Prerequisites

Feature	Required Software
Code Analysis	Visual Studio Premium
Code Coverage	Visual Studio Premium
Coded UI Tests	Visual Studio Premium
Database Projects	Visual Studio Premium
Lab Management	Visual Studio Lab Management
Layer Diagram and Dependency Validation	Visual Studio Ultimate
Load Testing	Visual Studio Ultimate
MSBuild Project Types	.NET Framework SDK
Non-MSBuild Project Types (for example, Deployment Projects)	Any edition of Visual Studio able to build the specific project type
Test Impact Analysis	Visual Studio Premium
Third-Party Build Dependencies	The corresponding third-party software
Third-Party GAC References	The corresponding third-party software
Unit Testing	Visual Studio Professional
Visual C++ Projects	Visual Studio Professional
Web Testing	Visual Studio Ultimate

Installing a Build Agent

The installation process for a build agent is as follows:

Insert the installation media.
Run setup.exe from either the TFS-x86 or TFS-x64 directory (for 32-bit or 64-bit machines, respectively).
Click Next on the Welcome To The Microsoft Team Foundation Server 2010 Installation Wizard page.
Accept the license terms and click Next.
Select Team Foundation Build Service on the Select Features To Install page and click Install.
Make sure that the Launch Team Foundation Server Configuration Tool check box is selected on the last page of the wizard, and then click Configure.
Select the Configure Team Foundation Build Service wizard and click Start Wizard.
Click Next on the Welcome To The Build Service Configuration Wizard page.
Select the Team Project Collection to which you want to connect the build controller and click Next.
On the Build Services page, choose how many build agents you want to run on the build agent machine, choose the build controller to which you want to attach them, and click Next.
On the Settings page, enter the account details for your Team Build service account and click Next.
On the Review page, review the settings that you’ve entered and then click Next.
On the Readiness Checks page, resolve any errors and then click Configure.
On the Complete page, click Finish.

Configuring a Build Agent After Installation

A build agent can also be configured either from Visual Studio on any computer (as described here) or from the Team Foundation Server Administration Console on the build agent itself, as follows:

Open Visual Studio 2010.
Open Team Explorer.
Expand a Team Project.
Right-click Builds, and then click Manage Build Controllers.
Select the build agent that you want to configure and click Properties to open the Build Agent Properties dialog box shown in Figure 13-4.

Figure 13-4 Build Agent Properties dialog

The Display Name and Description fields are used to describe the build agent.

The Tags allow you to apply arbitrary strings to the agent that can be used to select agents meeting certain criteria. Build definitions can define the tags that they require their agents to have, and then Team Build will automatically select the appropriate agent. Common uses for tags include specifying what operating system and other software the build agent has installed on it, as well as the bit-ness of the build agent. Chapter 14 discusses how you can configure build definitions to require agents with certain tags.

The Controller field allows you to select the build controller that the build agent is associated with.

The Computer Name field is the host name of the build agent. This will be used by Team Build to communicate with the build agent, so the Computer Name should be resolvable from the build controller.

The Working Directory field allows you to specify which directory on the build agent will be used as the working directory during the build. This default working directory is $(SystemDrive)\Builds\$(BuildAgentId)\$(BuildDefinitionPath). For example, if you have a Team Project called Contoso with a build definition called HelloWorldManual running on build agent 12, then the working directory would be C:\Builds\12\Contoso\HelloWorldManual.

You might want to modify the working directory in these scenarios:

If your build agent has multiple disk partitions, you might want to change the working directory to use one of the additional disk partitions—for example, E:\$(BuildAgentId)\$(BuildDefinitionPath).
If the source code or build outputs have a particularly deep directory structure or particularly long file names, you may want to use a shorter path—for example, E:\$(BuildAgentId)\$(BuildDefinitionId). This is particularly important when building database projects whose naming conventions result in very long file names.

You should usually include $(BuildAgentId) or $(BuildAgentName) and $(BuildDefinitionPath) or $(BuildDefinitionId) in your working directory so that multiple build agents and definitions can exist side by side in the build agent’s working directory. The variables available in the Working Directory field are listed in Table 13-2.

Table 13-2 Working Directory Variables

Variable Name	Description
BuildAgentId	Contains the integer identifier for the Build Agent in the Team Build database.
BuildAgentName	Contains the Build Agent name.
BuildDefinitionId	Contains the integer identifier for the Build Definition in the Team Build database.
BuildDefinitionPath	Contains the Team Project Name and the Build Definition Name; for example, Contoso\HelloWorldManual.
Environment Variables	Each environment variable on the build agent is available as a property. For example, $(Temp) expands to C:\Documents and Settings\TFSBUILD\Local Settings\Temp\ if the Team Build service account is TFSBUILD.

You can toggle whether or not the build agent is enabled using the Build Agent Service Is Enabled check box. When the agent is disabled, builds can still be queued on it, but they won’t be processed until it’s enabled.

Clicking Test Connection will verify connectivity from the Team Foundation Server to the build controller and from the build controller to the build agent. If the build controller detects that the build agent is offline, then it will automatically disable the build agent. Team Build will automatically enable the agent when it comes back online, but you can force this to occur earlier by clicking Test Connection.

Drop Folders

The final piece of infrastructure that needs to be in place before you create a build definition is a drop folder, where the build agent puts the build logs and outputs.

Because a Team Build environment may have multiple build agents, drop folders are typically located on a separate network share that all the build agents use. This means that developers, testers, and other users can access drop folders from a single central location.

The drop folder is typically a share on a file server of some description, but it could just as easily be a Network Attached Storage device or some other shared storage device. There are only a few requirements for the drop folder:

It must be accessible via a UNC path from all of the build agents.
The Team Build service account must have Full Control permission to it. This is required for the build agent to be able to drop the build logs and outputs.
It must have sufficient space available to store the number of builds retained by the retention policies that you define.

Save to your account