Team Foundation Build Quick Start

Working with Build Queues and History

Congratulations—you’ve now created your first build definition. Once you have a build definition, you can use Team Build clients such as Visual Studio or the TfsBuild.exe command line to queue builds and work with the build queues and history.

Visual Studio

Developers spend the majority of their time in Visual Studio, so it is logical to be able to work with builds from there. Team Explorer is the entry point to Team Foundation Server functionality within Visual Studio, and Team Build is no exception to this. The Builds node within a Team Project allows build administrators and developers to queue builds and view and manage build queues and individual builds.

Queuing a Build

To queue a build, you right-click the Builds node in Team Explorer and choose Queue New Build to open the Queue Build dialog shown in Figure 13-19. Alternatively, you can right-click a specific build definition and choose Queue New Build, which opens the same dialog but will automatically select that build definition.

The What Do You Want To Build? drop-down list will default to Latest Sources, but developers can change this to Latest Sources With Shelveset to queue a private build against a shelveset containing the changes they’d like to validate. This is discussed in more detail in the section entitled “Queuing a Private Build,” later in this chapter.

The Build Controller and Drop Folder For This Build will default to the values selected when you created the new build definition, but developers can override these if desired.

The Position setting indicates where this build will be in the queue if queued on the selected build controller. This is refreshed whenever a different build controller is selected, but there can be a small delay while the position is calculated. You can also change the priority that the build is queued with. As you might expect, the higher the priority, the higher in the queue it will be placed.

On the Parameters tab, shown in Figure 13-20, the developer can override the parameters specified in the build definition for this build process template. Chapter 14 discusses the parameters available for the templates that ship with Team Build, and Chapter 16 discusses how you can define parameters and custom parameter user interfaces for your custom build process templates.

If developers always have to override certain parameters, they could create specific build definitions specifying these parameters so they can just queue these build definitions instead.

Clicking Queue will then queue the build on the selected build controller and open the Build Explorer window so you can monitor the progress of your build.

Queuing a Private Build

Private builds (also known as buddy builds) allow developers to run a build based on the contents of a shelveset and, optionally, check in the shelveset after a successful build. This can be used to detect compilation errors and test failures before changes are checked in and can affect other developers.

In Team Build 2008, private builds were done by running MSBuild on the TFSBuild.proj in the developer’s local workspace. This approach was simple, but it suffered from a number of drawbacks:

• Private builds could be done only from the command prompt.

• The developer’s workspace could be out of date, and as such, the build and test results would be inconsistent with the results of building and testing against the latest source code.

• Developers’ workstations needed all the prerequisites of the end-to-end build process installed on them.

• Configuration differences between the developer’s workstation and the build machines would reduce confidence in the changes actually building successfully when checked in.

• The desktop build process and the end-to-end build process had significant differences that would further reduce confidence in the changes building successfully.

• The build outputs weren’t dropped in the same way as the end-to-end build process and couldn’t be easily shared with others.

Team Build 2010 takes a different approach and allows developers to shelve their changes and queue an end-to-end build against this shelveset and optionally check the changes in automatically if the build completes successfully.

Private builds are queued against a build controller, just like triggered and manual builds are, and as such, they use the same hardware, software, configuration, and build process as a triggered or manual build. This increases a developer’s confidence that the changes will build and test successfully when checked in.

In some circumstances, it can be seen as a negative that private builds no longer support building on the developer’s workstation, but this can be enabled by installing a Team Build controller and agent and choosing that controller when queuing the build. You should be aware of the drawbacks discussed previously of using a developer’s workstation for validating changes before check-in.

To enable a build definition to drop the build outputs for private builds, you must configure a Private Drop Location. If you do not do this, then the build will still validate that the shelveset compiles and passes tests, but the build outputs will not be dropped.

To set the Private Drop Location, edit the build definition, and in the Advanced category of the Process tab, enter a UNC path in the Private Drop Location parameter, as shown in Figure 13-21.

The developer can queue a private build by performing the following steps:

1. Right-click the build definition in Team Explorer and choose Queue New Build.

2. In the What Do You Want To Build? drop-down list, select Latest Sources With Shelveset.

3. Click the ellipsis button and choose the shelveset containing the changes they want to validate. Alternatively, you can create a shelveset based on the pending changes in the workspace by clicking Create.

4. Choose the Check In Changes After Successful Build check box if you want your changes checked into version control if the build completes successfully.

5. Click Queue.

Figure 13-22 shows the Queue Build dialog when queuing a private build of Hello World Main for the shelveset Increase Exclamation.

Private builds need to strike the right balance between speed and completeness to ensure that developers can validate their changes in a reasonable amount of time and still have a high level of confidence that a successful private build will typically mean a successful triggered or manual build.

If private builds take too long or have too much friction, then developers will bypass them and check in without validating their changes (although this can be prevented with the gated check-in trigger discussed in the section entitled “Trigger,” earlier in this chapter). For this reason, it can be beneficial to have a dedicated build definition for private builds that is configured to reduce build times (such as doing incremental gets and builds, running a smaller set of tests, and so on). Chapter 14 discusses the different properties that can be set to modify the default build process provided by Team Build.

Build Explorer

The Build Explorer window, shown in Figure 13-23, is the main way to manage build queues and view the build history. The Build Explorer can be opened by right-clicking the Builds node in Team Explorer and choosing View Builds. You can also double-click a build definition, which will open the Build Explorer and automatically filter it to builds of that build definition.

When first opened, the Build Explorer window will show only queued builds, which can be confusing if you expect to see the completed builds as well (as was the case in Team Build 2005). To see completed builds, you need to click the Completed tab at the top of the window.

The Queued build list can be filtered by selecting the filter criteria from the Build Definition, Status Filter, and Controller Filter lists at the top of the window. The Completed build list can be filtered as well, but by Build Definition, Quality, Date, and to builds requested by you.

Cancelling, Stopping, Postponing, and Reprioritizing Builds

If a build is queued but isn’t running yet, you can right-click it and choose Cancel to remove it from the queue. Similarly, if a build is currently running, you can stop it by right-clicking the build in the Queued tab of the Build Explorer and choosing Stop.

Rather than cancelling a queued build, you can postpone it by right-clicking it and choosing Postpone. This places the build on hold, and it won’t be built until you right-click the build again and clear the Postpone option.

Builds can be reprioritized to change their position in the queue by right-clicking the build, choosing Set Priority, and then choosing the new priority; the queue will then be refreshed to display the new queue order.

Viewing Build Details

Double-clicking a running or completed build in the Build Explorer will open the Build Details window. Note that you can’t open the Build Details window for a queued build.

This window has two main views: the Activity Log view, which shows an activity hierarchy for the build; and the Summary view, which summarizes the build results. As shown in Figure 13-24, both views show the build number, latest result, build quality, build history graph, information about how the build was triggered and by whom, how long the build ran, on which controller it ran, and when it completed. You can also change the build quality, open the build’s drop folder, toggle retain indefinitely, and delete the build.

The build history graph provides an “at a glance” view of the build definition’s history. The current build is indicated with a small triangle, the relative height of the bars indicates how long the build ran, and the color indicates the build’s outcome (green for successful, orange for partially succeeded, and red for failed). Clicking a bar will take you to the build details for that particular build.

While the build is running, you can only see the Activity Log view (and it will automatically refresh until the build completed) but once the build has completed, you will be shown the Summary view by default. You can toggle between the views using the View Summary and View Log hyperlinks at the top of the window.

The Activity Log view (shown in Figure 13-25) shows a tree of the activities being executed and how long the activity took, which provides an easy way of monitoring the progress of the build and allows you to quickly see what step caused the build to fail.

In Figure 13-26, you can see that the activities preceding compilation succeeded but the compilation itself failed, and you can see exactly what project or configuration caused the build failure. In addition, you can click that project’s MSBuild log file to open it.

The Summary view, shown in Figure 13-27, shows the latest activity on the build, a summary of the build results for each configuration and platform (including compilation warnings and errors, test results, and code coverage data), associated changesets and work items, and impacted tests. If the build fails, the Latest Activity section will link to the build failure work item that is created automatically and show its current status, as well as to whom it’s assigned.

The Associated Changesets and Associated Work Items sections list the changesets and work items that are associated with this build, but not earlier builds of the same build definition. This information is extremely useful for providing traceability and in identifying what change caused a build failure or to guide the testing of specific builds. Clicking the changeset number opens the changeset in the standard Changeset dialog, and clicking the work item number opens the work item in the standard Work Item window.

Changing Build Qualities

Once a build has completed, it often goes through a number of other processes before it is released. For example, a build might be installed in a testing environment, pass testing, and then be released.

To provide the ability to track the status of a build, Team Build allows you to flag builds with a build quality. The first step is to define the list of build qualities with which you’d like to be able to flag builds. You can open the Edit Build Qualities dialog, shown in Figure 13-28, by right-clicking the Builds node of Team Explorer and choosing Manage Build Qualities. Figure 13-28 shows the default list of build qualities provided with Team Build, but these can be customized to meet your requirements.

Once the list of build qualities has been defined, you can assign a build quality to a build by opening the build’s Build Detail window and changing the drop-down list at the top, as shown in Figure 13-29. You can also change the build quality from the Build Explorer by right-clicking the build and choosing Edit Build Quality. Assigning or changing a build’s build quality requires the user to be assigned the Edit Build Quality permission.

Retaining Builds

There are situations where you may want to retain builds that otherwise would be removed by the build definition’s retention policy, such as builds that you are in the process of testing or that you have released to customers.

You can flag a build to be retained indefinitely by opening the build’s Build Details window and clicking Retain Indefinitely at the top. In addition, you can turn this flag on by right-clicking the build in the Completed tab of the Build Explorer window and choosing Retain Indefinitely. If in the future you decide that you no longer want to retain the build, you can repeat this process to turn off the Retain Indefinitely flag.

Deleting Builds

Sometimes you might want to explicitly remove a build even though retention policies haven’t been enabled for the build definition or before the retention policy would have removed the build automatically. One reason you might want to do this could be to recover disk space or to remove extraneous builds from the build history.

You can explicitly remove a build by opening the build’s Build Details window and clicking Delete Build at the top. You can also delete the build by right-clicking the build on the Completed tab of the Build Explorer window and choosing Delete. You will be prompted to choose which build artifacts you want to delete, as shown in Figure 13-30.

Working with Builds from the Command Line

Build administrators (and most developers) are command-line fans at heart, and Team Build provides a command-line client for queuing, stopping, and deleting builds. Even if you’re not overly fond of using the command line, it also provides a simple way to script Team Build commands as part of a larger process.

The command-line client is called TfsBuild.exe and is installed in the %ProgramFiles%\Microsoft Visual Studio 10.0\Common7\IDE directory as part of the Team Foundation Client. The easiest way to run it is from the Visual Studio 2010 command prompt, which includes this directory in its default path.

The first parameter to TfsBuild.exe is the command to execute. The available commands are listed in Table 13-3.

Table 13-3 TfsBuild.exe Commands

Command	Description
Help	Prints general help for the TfsBuild.exe command-line client as well as command-specific help
Start	Starts a new build either synchronously or asynchronously
Stop	Stops one or more running builds
Delete	Deletes one or more completed builds and their artifacts
Destroy	Destroys (purges) previously deleted builds permanently

To print general help and a list of available commands, run TfsBuild.exe help.

To print help for a specific command, run the following code:

TfsBuild.exe help <command>

where <command> is the command in question (for example, TfsBuild.exe help start).

Queuing a Build

The TfsBuild.exe command line provides two variations of the start command. The first has the following syntax, and its parameters are described in Table 13-4:

TfsBuild start /collection:<teamProjectCollectionUrl> /buildDefinition:<definitionSpec>
               [/dropLocation:dl] [/getOption:go] [/priority:p]
               [/customGetVersion:versionSpec] [/requestedFor:userName]
               [/msBuildArguments:args] [/queue] [/shelveset:name [/checkin]] [/silent]

Table 13-4 TfsBuild.exe Start Parameters

Parameter	Description
/collection:<teamProjectCollectionUrl>	The full URL of the Team Project Collection (for example, http://TFSRTM10:8080/tfs/defaultcollection).
/buildDefinition:<definitionSpec>	The full path of the build definition in the format \<TeamProject>\<BuildDefinitionName> (for example, \Contoso\HelloWorldManual).
/dropLocation:<dl>	If specified, overrides the drop location in the build definition.
/getOption:<go>	If specified, states what version of the source code Team Build will get. Table 13-5 lists the available get options.
/priority:<p>	Set to either Low, BelowNormal, Normal, AboveNormal, or High. This parameter will default to Normal if not provided.
/customGetVersion:<versionSpec>	If /getOption:Custom is specified, this parameter must be supplied and specifies the version of the source code that Team Build should get. The available versionspec options are listed in Table 13-6.
/requestedFor:<userName>	By default, the build will be requested for the user that runs the TfsBuild.exe command line, or if you wish, you can pass this parameter to request a build on behalf of another user if you have sufficient permissions.
/msBuildArguments:<args>	Quoted arguments to be passed to MSBuild when executing TFSBuild.proj. For example, to enable optimizations and increase the logging verbosity to diagnostic, you would specify /msBuildArguments:"/p:Optimize=true /v:diag".
/queue	By default, the TfsBuild.exe command line will return an error immediately if the build won’t be processed immediately by a build controller (that is, if it needs to be queued). If the build is processed immediately by a build controller, TfsBuild.exe won’t return until the build has completed. If this parameter is used, TfsBuild.exe will return as soon as the build has been queued on the build controller.
/shelveset:name	Includes a shelveset in the build by unshelving it after the get has completed.
/checkin	Specifies that the shelveset should be checked in if the build completes successfully.
/silent	If specified, suppresses any output from the TfsBuild.exe command line other than the logo information.

Table 13-5 Get Options

Option	Description
LatestOnQueue	Builds the latest version of the source code at the time the build is queued.
LatestOnBuild	Builds the latest version of the source code at the time the build starts (this is the default).
Custom	Builds the version specified by the /customGetVersion parameter.

Table 13-6 Versionspec Options

Name	Prefix	Example	Description
Date/Time	D	D07/22/2010 or D07/22/2010T18:00	Builds the source code at a specific date and time. Any string that can be parsed into a System.DateTime structure by the .NET Framework is supported.
Changeset Version	C	C1133	Builds the source code at a specific changeset number.
Label	L	Lcheckpoint2label	Builds the source code at the version specified by the label.
Latest Version	T	T	Builds the latest version of the source code.
Workspace Version	W	Wmyworkspace; myusername	Builds the version of the source code currently in the specified workspace.

The second variation of the start command provides the same functionality as the first but mimics the syntax of the start command in Team Build 2005:

TfsBuild start <teamProjectCollectionUrl> <teamProject> <definitionName>
               [/dropLocation:dl] [/getOption:go] [/priority:p]
               [/customGetVersion:versionSpec] [/requestedFor:userName]
               [/msBuildArguments:args] [/queue]
               [/shelveset:name [/checkin]] [/silent]

Stopping a Build

You can also stop a running build from the TfsBuild.exe command line by using the stop command.

There are three variations of the stop command, and their parameters are described in Table 13-7:

TfsBuild stop [/noPrompt] [/silent] /collection:<teamProjectCollectionUrl>
              /buildDefinition:<definitionSpec> <buildNumbers> ...

TfsBuild stop [/noPrompt] [/silent] /collection:<teamProjectCollectionUrl>
              <buildUris> ...

TfsBuild stop [/noPrompt] [/silent] <teamProjectCollectionUrl> <teamProject>
              <buildNumbers> ...

Table 13-7 TfsBuild.exe Stop Parameters

Parameter	Description
/noPrompt	If specified, suppresses TfsBuild.exe confirming you want to stop the build
/silent	If specified, suppresses any output from the TfsBuild.exe command line other than the logo information
/collection:<teamProjectCollectionUrl>	The full URL of the Team Project Collection (for example, http://TFSRTM10:8080/tfs/defaultcollection)
/buildDefinition:<definitionSpec>	The full path of the build definition in the format \<TeamProject>\<BuildDefinitionName> (for example, \Contoso\HelloWorldManual)
buildNumbers	Space-separated list of build numbers to be stopped
buildUris	Space-separated list of build Uniform Resource Identifiers (URIs) to be stopped

Deleting a Build

You can also delete a build from the TfsBuild.exe command line by using the delete command.

There are five variations of the delete command, and their parameters are described in Table 13-8:

TfsBuild delete [/noPrompt] [/silent] [/preview] [deleteOptions:do]
                /collection:<teamProjectCollectionUrl> /buildDefinition:<definitionSpec>
                <buildNumbers> ...

TfsBuild delete [/noPrompt] [/silent] [/preview] [deleteOptions:do]
                /collection:<teamProjectCollectionUrl> <buildUris> ...

TfsBuild delete [/noPrompt] [/silent] [/preview] [deleteOptions:do]
                <teamProjectCollectionUrl> <teamProject> <buildNumbers> ...

TfsBuild delete [/noPrompt] [/silent] [/preview] [deleteOptions:do]
                /collection:<teamProjectCollectionUrl>
                /buildDefinition:<definitionSpec>
                /dateRange:<fromDate>~<toDate>

TfsBuild delete [/noPrompt] [/silent] [/preview] [deleteOptions:do]
                /collection:<teamProjectCollectionUrl>
                /dateRange:<fromDate>~<toDate> <teamProject>

Table 13-8 TfsBuild.exe Delete Parameters

Parameter	Description
/noPrompt	If specified, suppresses TfsBuild.exe confirming that you want to delete the build.
/silent	If specified, suppresses any output from the TfsBuild.exe command line other than the logo information.
/preview	Outputs a list of the artifacts that would be deleted without actually deleting them.
/collection:<teamProjectCollectionUrl>	The full URL of the Team Foundation Server (for example, http://TFSRTM10:8080/tfs/defaultcollection).
/buildDefinition:<definitionSpec>	The full path of the build definition in the format \<TeamProject>\<BuildDefinitionName> (for example, \Contoso\HelloWorldManual).
/deleteOptions:<do>	If specified, specifies which build artifacts should be deleted. Table 13-9 lists the available delete options. Multiple delete options can be comma-separated (for example, /deleteOptions:Details,DropLocation). The delete command can be run multiple times on the same builds if different delete options are specified.
/dateRange:<fromDate>~<toDate>	The date range of builds that should be deleted. Dates can be specified in any .NET-parsable date format.
buildNumbers	Space-separated list of build numbers to be deleted.
buildUris	Space-separated list of build URIs to be deleted.

Table 13-9 Delete Options

Option	Description
All	Deletes all the build artifacts listed in this table.
Details	Marks the build as deleted so that it is hidden in the Team Foundation Client. The build will be permanently deleted only if purged.
DropLocation	Deletes the build outputs from the build’s drop location.
Label	Deletes the build’s version control label.
TestResults	Deletes the build’s test results.
Symbols	Deletes the build’s symbols from the symbol store.