Team Foundation Build Quick Start

  • 12/24/2010
Contents

Creating a Build Definition

Now that the necessary infrastructure is in place, you can create your first build definition. Build definitions define the information required to execute a build, such as what should be built, what triggers a build, and how long these builds should be retained.

To create a new build definition, perform the following steps:

  1. Open Visual Studio 2010.

  2. Open Team Explorer.

  3. Expand a Team Project.

  4. Right-click Builds, and click New Build Definition.

  5. Enter the desired information on each of the tabs, as described in the remainder of this section.

  6. Click Save.

General

The General tab shown in Figure 13-5 allows you to name the build definition and optionally describe it. The description is displayed when a developer queues the build, so this can be useful to communicate additional information about what the build definition is for.

You can also temporarily disable the build definition from here as well, which can be used to prevent developers from queuing builds for obsolete or archived build definitions without having to delete the build definition. If using gated check-ins (as discussed in the section entitled “Gated Check-in,” later in this chapter) and if the build definition is disabled, then developers will be able to check in without running a validation build.

TIP

Be aware that the build definition name is often used from the command line and as a part of the build agent’s working directory path, so you should minimize the length of the name (to avoid exceeding maximum path lengths) and avoid unnecessary special characters, including spaces.

Figure 13-5

Figure 13-5 Build Definition: General

Trigger

Team Build 2005 only provided the ability for builds to be triggered manually, either from within Team Explorer, using the TfsBuild.exe start command, from Team Foundation Server Web Access, or using the Team Build API. These methods of starting builds provided build administrators and developers with a large amount of flexibility in how they started builds, but common requirements, such as scheduled builds and continuous integration, required additional programming, scripting, or third-party solutions to implement.

These are now implemented in Team Build 2010 by allowing build administrators to specify what triggers a build in the build definition. The triggers implemented are:

  • Manual

  • Continuous integration

  • Rolling builds

  • Gated check-in

  • Scheduled

These triggers are configured on the Trigger tab of the Build Definition window, shown in Figure 13-6.

Figure 13-6

Figure 13-6 Build Definition: Trigger

Manual

The simplest (and default) trigger is that builds need to be started manually. This trigger provides exactly the same experience that was available in Team Build 2005, with the exception that in Team Build 2008 and later, builds can be queued rather than failing if a build is already in progress.

Continuous Integration

Continuous integration (CI) is a set of practices from the agile community that provides early warning of bugs and broken code. By building and testing each changeset that has been checked in, any issues can be identified and resolved quickly, minimizing the disruption caused to other developers.

When Team Build 2005 was released, many saw the lack of a CI capability as a huge oversight, especially given its popularity at the time. Microsoft rectified this oversight in Team Build 2008 by adding a CI trigger that removes the need to rely on third-party CI solutions.

The CI trigger causes each check-in to the build definition’s workspace to queue a new build, as shown in Figure 13-7.

Figure 13-7

Figure 13-7 Changeset to queued build mapping for CI rolling builds

For long-running builds or workspaces that have a large number of check-ins, the CI trigger may result in unacceptably long build queues. The Rolling Builds trigger minimizes this issue by accumulating any check-ins to the build definition’s workspace until the currently running build completes; once the build completes, a single build will be queued to build the changesets.

Figure 13-8

Figure 13-8 Changeset to queued build mapping for rolling builds

Even this trigger may result in build queues being dominated by a few build definitions. To add a lag between the builds to allow builds from other build definitions to be executed, you can enable the Build No More Than Every X Minutes option of this trigger, shown in Figure 13-9, to ensure that the builds are not executed back to back.

Figure 13-9

Figure 13-9 Build Definition: Trigger (with lag)

Gated Check-in

Team Build 2010 introduces a new trigger called Gated Check-in. This trigger behaves similarly to the CI trigger, except that it intercepts the developer’s changes before they’re checked into version control, builds them, and then, if they build successfully, checks them in on the developer’s behalf.

TIP

If you think of CI as something that detects bad changes that have made it into version control, then think of Gated Check-in as a mechanism to stop them getting in there in the first place.

Whenever a developer checks changes into a file or folder that is part of the workspace of a build definition that uses the gated check-in trigger, they will be presented with the dialog shown in Figure 13-10.

Figure 13-10

Figure 13-10 Gated Check-in dialog

This dialog informs the developer that their changes need to pass a validation build before they’re checked in. At this point, the developer’s changes have been automatically shelved, and they can choose whether they want to preserve their changes locally or not.

If they’ve been granted the Override Check-in Validation By Build permission, they also have the option of bypassing the validation build and checking their changes in directly. See the section entitled “Team Build Security,” later in this chapter, for more information about this and other Team Build permissions.

Once a gated check-in build completes, the developer will be alerted via the Build Notifications tray to either reconcile their workspace (if the build succeeds) or unshelve their changes (if the build fails). You can also explicitly perform these actions when the build completes by right-clicking the build in the Build Explorer or from the build’s Build Details window.

If you did not keep pending changes, then reconciling your workspace is unnecessary, although you should perform a get to bring your workspace up to date. If you did keep your pending changes, then the Reconcile Workspace dialog (shown in Figure 13-11) can be used to undo any redundant pending changes and bring these files up to date with the changeset that was checked in.

Figure 13-11

Figure 13-11 Reconcile Workspace dialog

Schedule

The Schedule trigger allows builds to be scheduled to run on specific days at a certain time rather than having to use third-party scheduling applications. By default, scheduled builds will be skipped if no changes have been checked in since the previous build. However, this behavior can be overridden by selecting the Build Even If Nothing Has Changed Since The Previous Build check box.

NOTE

One limitation of the scheduling functionality is that you can’t schedule a build to be run multiple times a day. If you need this capability, you can either create a new build definition for each time you’d like the build to be run or use a scheduler (such as the built-in Windows Scheduler) to call the TfsBuild.exe command-line client to queue builds.

Workspace

The Workspace tab shown in Figure 13-12 allows you to define which version control folders Team Build will get to execute the build. You can specify multiple folders to get by adding additional working folder mappings with a status of Active, or you can prevent Team Build from getting a folder by changing the status of the mapping from Active to Cloak, as demonstrated in Figure 13-13, which shows that the HelloWorld folder will download but not the HelloWorld/HelloWorld.Tests folder.

TIP

If you create a build definition while you have a solution open, then the build definition’s workspace mappings will default to the workspace mappings for the workspace containing the solution.

Figure 13-12

Figure 13-12 Build Definition: Workspace tab

Figure 13-13

Figure 13-13 Build Definition: Workspace tab (multiple working folders)

By default, any other mapping that you add will be mapped to a local folder with the same name as the source control folder. You can override the default by changing the value in the Build Agent Folder column.

If one of the developers already has a workspace that contains the necessary working folder mappings, you can click Copy Existing Workspace to copy the mappings from that workspace into the build definition.

TIP

The default working folder mapping on the Workspace tab will download all of the files in the Team Project (or, if you have a solution open when you create the build definition, the workspace containing that solution). If these contain a large number of files and folders that aren’t needed by a build definition, you can significantly improve its performance by mapping only the required folders or by cloaking folders that aren’t required.

Build Defaults

The Build Defaults tab, shown in Figure 13-14, allows you to specify the default build controller that the build will be queued on and, optionally, where the build outputs will be dropped when the build completes. These are defaults and can be overridden by the developer when they queue the build.

Figure 13-14

Figure 13-14 Build Definition: Build Defaults tab

Process

Build definitions are linked to a Build Process Template that defines the build workflow that will be used. In fact these Build Process Templates are implemented using Workflow Foundation workflows. Chapters 15 and 16 discuss in detail how to customize existing Build Process Templates, as well as how to create your own.

A default Build Process Template will be selected when you create your build definition, but by clicking Show Details, you can select a different Build Process Template, as shown in Figure 13-15.

Figure 13-15

Figure 13-15 Build Definition: Process tab

In addition to selecting the Build Process Template, this tab is where you specify the Build Process Parameters. Each Build Process Template defines its own Build Process Parameters, so if you select a different Build Process Template, then you will see different Build Process Parameters selected.

In this section, we’ll cover the minimum Build Process Parameters for the Default Template that are needed to get your new build definition working. Chapter 14 will cover all of the Build Process Parameters for the Default Template and the Upgrade Template; and Chapter 16, “Process Template Customization”, will cover how to customize Build Process Templates and define your own Build Process Parameters.

The only Build Process Parameter that we need to provide to get our first build definition working is Projects To Build. To provide this parameter, select Items To Build and click the ellipsis to open the Items To Build dialog. Now click Add, browse to the solution or project that you want to build, and then repeat this for each additional solution or project that you want to build. If the solutions or projects have a build order dependency, then you can use the Move Up and Move Down buttons to arrange them in the order they need to be built.

TIP

When you create a new build definition, if you have a solution open that’s in a version-controlled folder, then the path to that solution will be automatically placed into the Projects To Build build process parameter.

If you don’t specify any configurations, then each solution’s default configuration will be built, the Configurations tab shown in Figure 13-16 allows you to specify configurations and platforms to be built for the selected solutions. If you specify multiple entries, then the solutions will be built multiple times (once per entry) and the build outputs placed in separate subfolders of the drop folder. In this example, the solution will be built four times, and the build outputs will be placed in the subfolders Release, Debug, Release\x86, and Debug\x86.

Figure 13-16

Figure 13-16 Configurations tab

TIP

If the configuration or platform that you would like to build isn’t listed, you can type the name of it into the appropriate combo box.

Retention Policy

In Team Build 2005, build administrators often ran out of disk space in their drop folder. The reason for this is that Team Build 2005 did not provide a solution to automatically remove builds that were no longer required.

Enterprising build administrators worked around this by either scripting the TfsBuild.exe delete command or by using third-party solutions (such as the Build Clean-up service, written by Mitch Denny).

Team Build 2008 and later solve this problem by introducing retention policies that allow you to specify which builds should be retained based on criteria in the build definition. The current version of this functionality is limited to retaining builds based on the type of build (Manual And Triggered or Private), the outcome of the build (that is, successful, partially succeeded, stopped, and failed) and the number of builds (for example, retain the last two successful builds). If your requirements are more complex, such as wanting to retain builds based on number of days or on build quality, then you will still need to implement your own solution.

The Retention Policy tab, shown in Figure 13-17, allows you to configure how many builds will be retained for each build outcome.

Figure 13-17

Figure 13-17 Build Definition: Retention Policy tab

TIP

It’s easy to think that you wouldn’t want to retain any failed builds, but when builds are removed by the retention policy, everything associated with them, including the build log, is removed. If you don’t retain at least one failed build, it might be very difficult to determine the cause of a build failure so that it can be resolved.

When a build is removed by the retention policy, the following items are also removed by default:

  • Build details

  • Drop folder, including the build logs and binaries

  • Test results

  • Version control label

  • Symbols

NOTE

Although the build details are removed, they are still available for reporting in the TFSWarehouse database and OLAP cube if the warehouse was updated between when the build completed and when it was deleted.

In the What To Delete column, you can override this default for a particular build type and outcome using the Build Delete Options dialog shown in Figure 13-18.

Figure 13-18

Figure 13-18 Build Delete Options dialog

Even if retention policies are enabled for a build definition, individual builds can still be explicitly retained or deleted as discussed in the next section.

Save to your account

This chapter is from the book