Chapter 5
Team Foundation Build
What's In This Chapter?
- Getting to know build automation
- Introducing Team Foundation Build
- Looking at what's new in Team Foundation Server 2012
- Understanding the Team Foundation Build architecture
- Working with Builds
- Understanding the Team Build process
This chapter examines the build automation capabilities of Team Foundation Server—what is provided out-of-the-box, how to use it, and how to customize it to suit your organizational requirements. But first, let's take a quick look at build automation in general.
After version control, automating the build is the second most important thing you can do to improve the quality of your software.
Only after the parts of your application come together can you tell if your application works and does what it is supposed to. Assembling the parts of an application is often a complex, time-consuming, and error-prone process. There are so many parts to building the application that without an automated build, the activity usually falls to one or two individuals on the team who know the secret. Without an automated build, even they sometimes get it wrong, with show-stopping consequences that are often discovered very late, making any mistakes expensive to fix.
Imagine having to recall an entire manufacturing run of a DVD because you missed an important file. Worse still, imagine accidentally including the source code for your application in a web distribution, or leaving embarrassing test data in the application when it was deployed to production. All these things make headlines when they happen to organizations that build software, yet they can easily be avoided.
Integration of software components is the difficult part. Teams work on their features in isolation, making various assumptions about how other parts of the system function. Only after the parts are assembled are the assumptions tested. If you integrate early and often, the integrations are tested as soon as possible in the development process—therefore reducing the cost of fixing the inevitable issues.
It should be trivial for everyone involved in the project to run a copy of the latest build. Only then can you tell if your software works and does what it is supposed to. Only then can you tell if you are going to have your product ready on time. A regular, automated build is the heartbeat of your team.
In Visual Studio 2012, a developer is usually able to run his or her application by pressing the infamous F5 key to run the code in debug mode. This assembles the code on the local workstation and executes it. This makes it trivial for the developer to test his or part of the code base. But what it doesn't do is ensure that the code works with all the latest changes committed by other members of the team. In addition, pressing the F5 key simply compiles the code that's ready for manual testing. As part of an automated build, you can also run full a suite of automated tests, giving you a high degree of confidence that no changes that have been introduced have broken something elsewhere.
Pressing the F5 key is easy for a developer. You want your automated build to make it just as easy to run your application—if not easier.
Team Foundation Build
Build automation is so important to the quality of the software development process that Team Foundation Server 2012 provides build services as part of the core platform.
The build services provided by Team Foundation Server offer an enterprise-class, distributed build platform. Utilization of the build services is done inside the development environment in which the code is being created (either in Visual Studio or Eclipse). Information on the build services is tightly integrated with the version control, work item tracking, and the testing features provided by Team Foundation Server.
In addition, data obtained from the build system is fed into the Team Foundation Server data warehouse, thus allowing for the analysis of historical reports and trends. The build services provide notifications on build events using the standard Team Foundation Server eventing mechanisms, which means that e-mail alerts can easily be sent to the team regarding build status. As part of the standard installation in Visual Studio 2012, the Build Notifications tool is installed alongside Visual Studio, which can provide the capability for additional build notifications via the application that runs in the system notification area.
Team Foundation Server provides a number of ways to trigger the build. Builds may be started by a manual request, automatically triggered by a check-in to Team Foundation Server version control, or run on a specified schedule. Team Foundation Server also has a concept called gated check-ins. A gated check-in means that a developer's changes must successfully build on the build server when merged with the latest code from version control before the code is then checked in on behalf of the user, thus preventing “broken” code from ever being checked in.
Team Foundation Build also has a full API in .NET or Java. These are the same APIs used by the Visual Studio and Eclipse integrations as well as the build notification tool. They provide you with deep integration into the build services. Combined with the build events, there is a highly extensible platform to integrate any additional systems that you can imagine.
What's New in Team Foundation Build 2012
The build services offered by Team Foundation Server have been changed significantly since the initial version in Team Foundation Server 2005.
In the first version, Team Foundation Build was based heavily on MSBuild, along with a build server machine called the build agent. All configuration of the build was done by editing files stored in version control.
In the 2008 release, build management was greatly improved with the capability to trigger builds automatically, queue builds, and manage builds. This second version introduced the Build Definition as a Team Foundation Server entity in its own right that contained various configuration data about the build (such as the build name, workspace definition, default build agent, drop location, and build trigger). The file describing how to do the build (the TFSBuild.proj file) was still based on MSBuild.
The 2010 release continued much of the work done in 2008, with some notable changes that include the following:
- Windows Workflow 4.0
- Gated check-ins
- Private builds
- Build notifications
- Build controller
- Properties exposed for common customizations
- Integration with symbol and source server
- Enhanced build deletion options
By the 2010 release Team Build capabilities matured significantly since the original release, therefore this most recent 2012 release was more evolutionary than revolutionary. However, there are a few significant changes worth noting:
- Hosted build services
- Drop to version control
- Batched gated check-in
- Changes to the Build Service protocol
- Updated build report
Hosted Build Services
The hosted Team Foundation Service (http://tfspreview.com) not only provides a hosted Team Foundation Server instance for version control and work item tracking but also provides virtualized hosted build infrastructure. By default, every project collection in the hosted service also has a Hosted Build Controller available that you can use for your builds as shown in Figure 5.1. When a build is queued, the hosted service creates a new virtual machine, attaches it to your project collection, executes the build, and then returns the machine into the pool ready for the next account that wants to perform a build. Because the build virtual machines are created from a fresh image for each invocation, incremental builds are not currently supported. In addition, if your build requires any dependencies are not pre-installed in the standard hosted image then you need to have those checked in to version control and configure those as part of the build.
Drop to Version Control
When building against the hosted service, network shares are not easily accessible over the Internet. Therefore, a new option was created that is only enabled for hosted builds to enable results of the build to be copied to version control as shown in Figure 5.1. Note that when builds are deleted (either by the retention policy settings or by manually deleting the build) and deletion of build drops has been requested, the results of the builds are not only deleted from version control but destroyed. This means that they no longer occupy space within the version control system in Team Foundation Server thereby reducing the amount of space consumed by your project collection.
Batched Gated Check-in
Team Foundation Server 2010 introduced the gated check-in feature. As previously discussed, having a frequent automated build is one of the most important things you can do to improve your software development process. The key is to ensure that the latest code in your repository always compiles and runs and that it passes any associated automated tests. After you have your working build, the team must ensure that it stays good.
For very large teams, keeping your builds clean can be an issue. Imagine that a good developer might check in something that breaks the build once a year. If you have 500 people working on code bases, you quickly get into a situation where the build is breaking twice a day, every day. In these circumstances, configuring a build as a gated check-in may help.
A gated check-in means that the code is submitted as a shelveset rather than it being checked in to version control. The build server then takes the latest code, merges that with the changes contained in your shelveset, and performs the build. If the build is successful, the changes in your shelveset are checked in automatically on your behalf by the build server.
Gated check-ins have proven to be a very popular feature of Team Foundation Server. However, a limitation of them is that to prevent conflicts, only one gated check-in may be executing at a time and large teams who check in frequently may end up with a large queue of builds awaiting validation. The longer a developer needs to wait between submitting a check-in for validation and the check-in being committed into the repository, the less valuable the automated build process is. If this becomes an issue for your team then in Team Foundation Server 2012 you may choose to Merge and build a number of submissions in the queue—specifying a maximum number of build requests to be included in each gated build as shown in Figure 5.2.
When gated builds are batched together, the maximum specified number of check-ins are merged and validated in one build. If there is no backlog of builds then the gated check-in performs just as the feature did in Team Foundation Server 2010. However, if several check-ins are built together and a failure is detected, then the build is requeued with just the individual check-ins to allow the invalid check-in request to be detected. In practice, as the majority of check-ins pass validation, this can be an effective mechanism to avoid a gated check-in backlog.
Changes to the Build Service Protocol
In previous versions of Team Foundation Server, the build agent and controller have been notified by the build agent initiating a TCP connection to the machine hosting the build service and a SOAP notification sent over TCP/IP. This is better than the traditional polling mechanisms used by many third-party build solutions, and it means the minimum load is placed on the network and on the Team Foundation Server Application Tier (AT). The problem with this approach is that there must be an open outbound port rule enabled in the firewalls between the AT and the build machine. In addition, because the build machine must be able to confirm the authorization of the build agent to access it, the build machine and the AT effectively had to be on the same domain or have an appropriate domain trust relationship established.
To work around these issues—and also to allow a build agent to more easily be configured against an AT that is accessed over the Internet—the build service protocol has been reversed. In Team Foundation Server 2012, the build service hosting the build controller and build agent processes establishes an outbound connection to the AT (usually using the standard HTTPS port 443 for an externally hosted instance or HTTP port 8080 for on-premises installations of TFS). The protocol is designed to place minimal network load in a similar mechanism to how so-called “push notification” e-mail delivery to cellular devices is achieved. That is, the build service does not constantly poll version control. Instead, it notifies the AT about the open connection and then sends minimal heartbeat traffic to keep the channel open, which allows inbound responses from the AT to notify the Build Service when it has a build request needing action. The build service maintains the open channel to the AT and has the suitable retry logic to re-establish the connection should it be severed for some reason.
Updated Build Report
The Build report was updated in Team Foundation Server 2012 to provide additional diagnostic capabilities and to more clearly display the relevant build information. The build report also now updates during the build process in the web browser and in Eclipse, just as it always did in Visual Studio 2010.
Team Foundation Build Architecture
As shown in Figure 5.3, several logical components are used as part of the Team Foundation Build services.
When a build is triggered, the Application tier sends a notification to a server called the build controller using a communication channel established by the build service and queues the build. The controller then downloads the build's Windows Workflow-based process and executes it. By default, this is then allocated to the next available build agent in the controller's pool of agents.
The build agent is the machine that actually executes the main portion of the build process as coded in the build's workflow—including calling MSBuild to perform the actual compilation step. It then archives the build results (that is, your executable binaries or your website) to a Windows file share provided as the drop location, and publishes symbols to the symbol server (if configured). Note that if you're utilizing the hosted build service on http://tfspreview.com then the build drop location may be in version control and the symbol server capabilities will not be available.
For an on-premises installation, the build controller and the build agent services are provided by the Visual Studio Team Foundation Build service host installed from the Team Foundation Server installation media. The build controller and build agent are configured using the Team Foundation Server Administration Tool.
The build controller and build agent may live on the same machine as the Team Foundation Server Application tier. However, because a build is typically very CPU and disk I/O intensive, the build agent should at least be located on a separate server to avoid affecting the performance of the main Team Foundation Server application. If you run the build agent on the same machine as Team Foundation Server, this may cause some performance issues if certain intensive diagnostics data collectors are used as part of the build.
The actual details of the build (such as the build name, what to build, when to build it, how to build it, and what to do with the results) are all configured in the build definition. The results of individual builds are called the build details.
Working with Builds
This section examines working with team builds in Visual Studio. Figure 5.4 shows the key windows that you need to use:
- Team Explorer
- Build Explorer
- Build Details
Team Explorer
You should already be familiar with the Team Explorer view (accessed in Visual Studio through View ⇒ Team Explorer). Team Explorer contains a Builds page that provides you with access to all the functionality you need to interact with the build services in Team Foundation Server. The New Build Definition link at the top of the page enables you to create a build definition. There is also an Actions link that provides you with additional functionality such as being able to manage the Build Controller settings, set Build Qualities, and configure security permissions.
Under My Builds you find your most recently executed builds (that is to say builds that you have triggered either manually or by checking into a version control folder that is being monitored by a continuous integration, rolling, or gated trigger. My Favorite Build Definitions displays a summary of the build definitions that you have marked as a personal favorite in Visual Studio, Web Access, or Eclipse. Finally, under All Build Definitions you find all the defined builds for that team project and a search box that enables you to quickly find a particular build definition from that list. Double-clicking one of these or clicking the build in the Favorites opens the Build Explorer for that build definition.
Build Explorer
The Build Explorer view enables you to see all the builds that are currently executing (or awaiting execution) in the Queued tab, and those that have run on the system in the Completed tab.
Queued Builds
From the Queued tab of the Build Explorer, you can pause or change the priority of builds that are currently awaiting execution. You can also cancel paused builds or stop builds that are currently executing.
Completed Builds
From the Completed tab of the Build Explorer, you can view the build details, delete the build details, or set the quality of the build.
The build quality is a text string allocated to particular builds to denote the quality of that particular build (that is, “Released,” “Ready for Test,” and so on). In addition, you may mark the build with Retain Indefinitely to exclude it from any automatic retention policies on the build definition. You also have the option to Reconcile Workspace with the build, which is useful for a gated or private build because it removes any pending changes that you may still have that were checked in on your behalf as part of the build.
Build Details View
When you double-click a build in the Build Explorer, you see a report of the build details, as shown in Figure 5.5.
While the build is queuing, details are given about the build's position in the queue and the mean time that builds have been queued. After the build is executing, summary data about the execution time compared to previous builds is displayed. Clicking the Build Details link shows you more information about the build in progress and is automatically refreshed to show you the current build log data. A small bar chart in the top-left corner displays the currently executing build time against previous builds, which can give you an indication of how long the build might run.
When the build has completed, you see the build summary view showing all the projects, compilations, and tests runs, as well as any unit test results, code coverage, or test impact data. You also see information regarding the changesets included in the build since the last successful build of that build definition, along with any work items associated with those changesets when they were checked in.
In this way, you can start to see how full requirements traceability is obtained in Team Foundation Server, from the requirement being logged as a work item through to the development task to implement the requirement, to the change in source code to implement that task, and then, finally, the build of the software that includes that check-in. All the data is passed into the Team Foundation Server data warehouse to allow historical trend analysis and reporting.
From the build details view, you are able to open the drop folder in Windows Explorer to access the outputs of your build. You may modify the build quality assigned to that build, mark it to be retained indefinitely, or delete the build and associated results. You may also view the logs in the drop location (either in the drop network share or in version control) and perform many other additional activities from under the Actions link.
Creating a Build Definition
A build definition describes how, what, when, and where to perform your build. You create a new team build definition by right-clicking the New Build Definition link at the top of the Builds page in Team Explorer. Alternatively, from Visual Studio you may go to Build ⇒ New Build Definition.
You see a new build definition form inside Visual Studio. The form is split into two parts—a set of areas on the left side that basically function like tabs, and the main area for that section on the right side. You may notice that, when you first open the dialog, a number of the sections on the left side have warnings associated with them; this is completely normal. The purpose of these warnings is to highlight areas that need information before the definition can be saved.
You can save the definition by using the usual mechanisms (File ⇒ Save, or Ctrl+S, etc.) When saved, the definition is stored in Team Foundation Server and appears in the Builds page for all team members. You may mark your build definition as a personal favorite to make it easier to find later by right-clicking the created build definition and selecting Add to Favorites.
General Section
On the Builds page in Build Explorer, click General in the left-hand pane to bring up the General section. Then you must give the build definition a name, and, optionally, a description, as shown in Figure 5.6.
As you can easily search by name in the Builds page in Team Explorer, it may be useful to develop a naming convention for your builds to make them easier to find when filtering. A convention such as “Team: Project (Trigger)” is useful for large team projects. For example, the BizApps team might have two build definitions defined for their Framework, one that is a CI build triggered on every check-in to give quick feedback on the state of the build, and another scheduled build that not only does a full build but packages up the latest version and generate documentation, making it easy to consume by other teams. They might call these builds “BizApps: Framework (CI)” and BizApps: Framework (Nightly)”.
For the description of your project, you should provide a short, one-line summary of what the build is for, and contact details for the owner or “build master” for the build. The first three lines of the build description are displayed in other dialogs in Team Foundation Server before scrolling is required. Therefore, this important information should be placed at the top so that people working with the builds can see what the build is for and who to contact for questions.
When creating a new build definition the Queue Processing should be set to Enabled as this allows builds to be triggered as soon as the build definition is saved. However, it may be useful to adjust the Queue Processing when performing maintenance to the build definition or build controllers. For example, if you are customizing the build process you can mark the build as Paused. New builds are queued if they get triggered as a continuous integration build or a gated build. However, they do not run until the build is enabled or a build administrator forces the build by right-clicking the queued build request in Build Explorer and selecting Start Now. This enables you to safely test that your changes to the build customization are working before re-enabling the build definition for use by the team. After the build is re-enabled, queued jobs are processed according to priority level and the order that they were submitted.
Trigger Section
Located in the Trigger section, the build trigger tells Team Foundation Server when to perform a build. As shown in Figure 5.7, there are a number of triggers available, including the following:
- Manual
- Continuous Integration
- Rolling Builds
- Gated Check-in
- Schedule
Manual
When you configure a build for a Manual trigger, the build only runs when explicitly queued, by using the user interface, by using the command line (that is, tfsbuild.exe), by using the Team Foundation Server .NET object model or the TFS SDK for Java.
Continuous Integration
In Team Foundation Server, the Continuous Integration trigger is one that queues a build for every check-in performed on the areas of code that you define as related to your build. (The “Workspace” section, later in this chapter, provides more information on defining those areas.)
Check-ins to Team Foundation Server are a discrete, atomic transaction represented by a changeset. By rebuilding the system for every changeset, you can easily determine which change broke the build (as well as who checked in that change). The downside to this is that there are, obviously, a lot of builds performed. Therefore, it is essential that build times are kept short to ensure rapid and frequent feedback to the development team as to the status of the current code base.
Rolling Builds
Rolling Builds are similar to the Continuous Integration trigger in that a check-in will trigger a build. However, rather than building on every check-in, rolling builds batch several check-ins together to ensure that the build server never becomes backlogged—and optionally setting a minimum time interval between which a new build may be triggered. This is the type of trigger that may be familiar to those who have experience with build servers that support multiple version control tools such as CruiseControl, CruiseControl.NET, or Hudson/Jenkins.
Performing rolling builds has the advantage of reducing the number of builds performed, which helps to reduce the number of builds queued at peak times (and, therefore, the time before the results of an individual developer's check-ins are known). However, it has the disadvantage of grouping changes together, therefore making it more difficult to determine the check-in responsible for the build failure. For this reason, many people stick with the Continuous Integration trigger and instead focus efforts on increasing the speed of the build or the number of build agents available to perform the build.
Gated Check-in
A Gated Check-in trigger means that check-ins to the areas of version control covered by the build are not allowed by the server until a build has been performed and passed successfully. When a user attempts to check in a file, they are presented with the dialog shown in Figure 5.8.
The changes are stored as a shelveset in version control. The build server takes the shelved changes and merges those changes with the latest version of code from version control before performing the build. In the event of a successful build, the changes are then checked into the build server, and the user is notified via the build notification tool in the system notification area. At this point, the user may “reconcile” his or her workspace to remove the pending changes that were committed as part of the build from the current pending changes list.
Because of the automatic merge process that is performed by the build server, it is important to realize that the actual code committed by the gated check-in may differ from the code submitted as part of the shelveset.
If you have two build definitions with overlapping workspace mappings that both have Gated Check-in triggers, the user will get to pick which one gets built to verify his or her changes at the time of check-in. In addition, even though Team Foundation Server 2012 has build agent pooling features, only one build of a gated check-in may be executed at a time to prevent conflicting merges from being submitted.
As discussed earlier in the chapter, due to the fact that only one gated build can be executed at a time, a backlog of queued builds can form when a large team is doing frequent gated check-ins. Therefore, as shown in Figure 5.2, Team Foundation Server 2012 has the ability to merge a number of queued gated check-ins working on the assumption that the build is likely to be successful. This helps reduce check-in validation times. If the build fails for some reason, then the build requests are requeued individually to allow the problem build to be identified and rejected. This is shown in Figure 5.4 where two check-ins have been merged into HelloWorld_20120703.7 which failed, so HelloWorld_20120703.8 and HelloWorld_20120703.9 were queued up, each containing the individual check-ins. In that case it turned out that the check-in included in HelloWorld_20120703.8 was bad so that is rejected and the user notified, but the check-in included in HelloWorld_20120703.9 was good and so that was checked in on that user's behalf.
Schedule
Builds may be triggered by a particular schedule—that is, a daily or nightly build. Note that a single time may be specified for each build definition for the chosen days of the week—repeated weekly. Also note that, in the case of a nightly build, the build time should be set outside of any backup or other regular maintenance jobs.
The time for a scheduled build is actually converted into the time zone for the Application tier when the build definition is saved. But this is always displayed in the time zone of the user's machine when editing the build definition in Visual Studio. For this reason, there can be some slight confusion as to the actual build time during periods where Daylight Savings Time is in operation in one of the time zones and not the other.
Workspace
The Workspace section enables you to define the working folder mappings that should be used for your build. These working folder mappings not only determine where on disk the files should be located but also which files on the server are considered relevant to the build.
The default working folder mapping for a new build definition is given as mapping the root of the team project (for example, $/Demo) to the sources directory represented by the environment variable ( $(SourceDir) ). This is almost always too broad for your build, and includes too many files, which not only slows down the build (because more files must be downloaded from version control), but also means that some check-ins to the project risk triggering a build even though they do not affect the results of the build.
Therefore, you should always modify the server path of the build to only include the files you need, as shown in Figure 5.9. You may also make use of cloaked working folder mappings to exclude certain subfolders or files from a working folder mapping that do not affect the build (such as a folder containing the source PSD image files used in a website).
Build Defaults
On the Build Defaults section shown in Figure 5.10, you specify which build controller you would like to use for the definition and where to copy the outputs from your build.
In Team Foundation Server 2012, build controllers and build agents are responsible for notifying the Team Foundation Server application tier of their existence as they are installed. If you have no build controllers available in the controller dropdown, then your Team Foundation Server administrator must install a build controller (and build agent) using the Team Foundation Server Setup media and configure it to point to your project collection. The description field displays the description given to the build controller, and it is not editable from this dialog. Note that when using the hosted Team Foundation Service at tfspreview.com, a Hosted Build Controller is present for every project collection that allows builds to be performed using a build controller in the cloud.
For regular builds, the drop folder location must be a Windows file share on the network to which the user running the build agent services has access. There is a limit (inherited from the .NET base class libraries) of 260 characters for the full path of all files copied to the drop folder location, so you should ensure that your server and share names are as short as possible, leaving you with the maximum space for your output. That being said, you should put your builds in directories corresponding to the build definition inside your drop folder location to help keep them organized. When talking to the hosted service you also have the option to store files in version control. Note that the build definition name is appended to the path specified so there is no need to specify it in the dialog.
Process
When talking to a Team Foundation Server 2012 server, you are required to select which process should be used to perform the build, as shown in Figure 5.11. These processes are Windows Workflow 4.0-based processes. The initial list of processes are defined by the process template used, and can then be added to from the Process section. Each process has a number of easily customizable properties that are designed to be used to alter the behavior of that process. Processes with mandatory inputs are marked with a warning triangle when the build definition is created.
From this section, you may edit and customize the build process parameters. (For more information on this, see the section “Team Build Process,” later in this chapter.)
For the creation of a basic team build using the DefaultTemplate, the only property that you must initially configure is which solution or project to build. Simply click the Projects to Build property and click the…button to add your solution or project to the list.
Retention Policy
After you start automating builds, you quickly end up with a lot of build results in your archive. Finding the build that you are looking for can get complicated—not to mention the large amount of disk space required to store all the build results. Team Foundation Server has automatic retention policies to help with this, as displayed in the Retention Policy section shown in Figure 5.12.
The retention policies determine, for each build result type, how many of those results you would like to keep by default. Note that, at any time, you can mark a build with the Retain Indefinitely Retention Policy from the build details context menu in the Build Explorer view. Marking a build as Retain Indefinitely means that it will be excluded from these automatic retention policies.
There are separate retention policies to control the team builds that are triggered or manually queued from the private builds of individual developers. Changing the private build retention policy affects all the developers performing private builds on that build definition—not just the developer editing the setting.
If you're storing build drops in version control using the hosted service, when the build binaries are deleted they are destroyed in version control to allow the disk space to be recovered.
Queuing a Build
Whenever you create a new build definition or make significant changes to it, you should manually queue the build the first time to ensure that it is working as desired. The first successful build for a build definition also acts as the baseline for that build. Every build from that point on records the changesets included since the last successful build for that definition. This information is stored in the build detail for each build, and reports into the Team Foundation Server data warehouse, thus allowing for historical trends over time.
A build can be manually invoked from the Builds node in Team Explorer by using the TFSBuild.exe command-line tool, or by using the Team Foundation Server API. Alternatively, the build might be triggered using one of the triggers defined earlier in this chapter (such as on a check-in into version control or on a specified schedule).
To manually queue a build in Visual Studio, right-click the build definition in Team Explorer and select Queue New Build. You are presented with the Queue Build dialog, as shown in Figure 5.13. The build definition is preselected in the build definition dropdown at the top of the dialog, and its description is displayed underneath.
When you manually queue a build, you have options of selecting an alternative build controller (if one is available), adjusting the priority of the build, and modifying the drop folder location to be different from the default. Based on the selected queue priority, you are also given an indication of the current position in the queue that your build would get if it were submitted.
On the Parameters tab you find all the customizable properties defined for the process, so you can alter the value of that property for this single invocation of the build.
Private Builds
You can adjust what you want to build from the General tab in the Queue Build dialog (Figure 5.14). You can either build from the latest version in source control at the time that the build is submitted to the queue, or you can take the latest version and apply a specified shelveset to the build before it is performed.
If you decide to perform a build that includes a shelveset of your changes not yet checked in to version control, this is called a private build, which can sometimes be referred to as a buddy build.
Private builds are useful when you want to check that you are including all the changes necessary to successfully perform the build on a different machine before you commit your changes to version control. Another use for them is when you may not have all the dependencies to perform that particular build definition on your local machine (such as a code signing certificate installed), but you want to test that your code functions correctly when built with those dependencies.
In many ways, a private build is similar to a gated check-in, apart from the fact that your changes are not automatically checked in to version control after a successful build, but you can choose to have them checked in if you want.
Private builds do not follow the same build numbering mechanism defined for the regular team builds, and have separate retention policies. The build results for a private build are displayed to the developer who is invoking the private build, not to the whole team.
Build Notifications
Team Foundation Server exposes a powerful eventing model and both .NET- and Java-based APIs that allow for custom integrations of any imaginable application or device for notification of build results—from standard e-mail alerts to lava lamps, confetti-filled leaf blowers, and even talking robot rabbits. However, two main notification systems are exposed to the developer out of the box—the build notification tool and e-mail alerts.
Build Notification Tool
The build notification tool is a separate application installed with Visual Studio. As shown in Figure 5.15, it is a small application that runs in the system notification area of Windows and notifies the end user of build events via an Outlook-style pop-up message in the bottom-right corner of the screen.
This tool can be configured to automatically start when you log in to Windows. However, it is always run during a gated check-in process so that the developers are aware of the status of the build containing their changes. If the build is a success, the developers can easily reconcile their workspaces to remove any pending changes that were included in the gated check-in shelveset from their local workspace.
To configure the build notification tool, while the tool is running right-click the icon and select Options. To quit the application entirely, right-click the icon and select Exit.
E-mail Alerts
Basic and custom e-mail alerts can be configured from the web. To quickly view the appropriate web page from Visual Studio, go to the Team ⇒ Project Alerts menu. Using the interface shown in Figure 5.16, you can enable basic e-mail alerts when a build quality changes, when any build completes, or when builds are initiated by the developer. For a more powerful alerts editor, click the Custom Alerts link. (In previous versions of Team Foundation Server, this level of control over alerts required use of power tools or the command line.)
As shown in Figure 5.16, a link is also provided on the My Alerts page to configure advanced alerts that are applicable to the whole team. Clicking the link takes you into the administrative configuration web portal for your team project.
E-mails can be sent to any e-mail address, including team aliases, provided the Team Foundation Server Application tier is configured with the correct SMTP server details to send the messages.
On the Team Foundation Server Application tier machine, the BisSubscribe.exe command is available in the Team Foundation ServerTools folder, and can be used to script the creation of project alerts.
Team Build Process
The process controlling the end-to-end build process in Team Foundation Server is described in a Windows Workflow 4.0 XAML file. The build process templates are created as part of the project creation process and are defined in the process template.
In the Scrum, MSF Agile, and MSF CMMI processes, the following build processes are included:
- DefaultTemplate—This is the default template to be used for most new builds created for Team Foundation Server. This is the template that is the primary focus of discussion in the remainder of this chapter.
- UpgradeTemplate—This is the default template for builds upgraded from Team Foundation Server 2008, or newer builds that make heavy use of MSBuild rather than Windows Workflow. Basically, it performs some housekeeping, and then just wraps the call to the TFSBuild.proj file for an MSBuild-based build configuration. Java builds created by Team Explorer Everywhere make use of the UpgradeTemplate to provide a thin wrapper around Ant or Maven. This allows all the configuration files to be edited by a simple text editor and does not require knowledge of Windows Workflow—but it pushes the majority of the build logic down into the Ant or Maven build script that is invoked.
In addition, the LabDefaultTemplate build process template is also installed for the Lab Management functionality by the Lab section of the MSF processes.
All the build process templates are stored as files in version control, allowing for quick and easy auditing of any changes to the process used to perform the build. By default, these are stored in a folder called BuildProcessTemplates at the root of the team project in version control, but may be located inside your team project branch structure, if that's more convenient.
The majority of the remainder of this chapter focuses on the DefaultTemplate—how it works, how to use it, and how to modify it.
DefaultTemplate Process
The DefaultTemplate is used for most new, un-customized build definitions. The process is outlined at a high level in Figure 5.17, but you can explore it in detail by opening the DefaultTemplate.xaml file from version control inside Visual Studio.
On the build controller, the build number is calculated and the drop location for the build is created. Then the build agent is determined, and the majority of the rest of the process is performed on the selected agent from the controllers build agent pool.
The working directory for the build is calculated by using the build agent working directory setting as defined in the Build Agent Properties dialog. Then the workspace is created (if required), and source is downloaded from version control. The version that is downloaded is usually the changeset that represented the latest version in the project collection at the time the build was triggered. If a subsequent change has been made while the build was queued, this change is not included. The files that were downloaded are then labeled in version control with the build number.
Next, the process calls MSBuild to perform the actual compilation of the desired project files for the configuration, and then any specified automated tests are executed. The build agent then looks at the changesets included since the last successful build of the build definition, and records any work items that were associated with those check-ins. For work items that were marked as resolved during check-in, the Fixed-In Build field for the work item is updated with the current build number.
From the files changed since the last successful build, the build agent then calculates which tests have been affected, and records them. The source code is then indexed and linked with the symbols that are published to the symbol server (if provided). Finally, on the build agent, the output from the build is copied over to the drop folder location previously created by the controller.
The process then moves back to the controller for the final step, which, for a build with a Gated Check-in trigger, is to check in the shelveset that contained the modified files included in the build.
Build Process Parameters
The build process templates are configured to make a number of parameters visible in the user interface in either the Build Definition editor or the Queue Build dialog (or both). These parameters (Figure 5.18) are provided to control the behavior of the selected build process.
When you create the build definition, you set one of these parameters, Items to Build, to be the solution file that you want to build. However, there are many other parameters provided for you to adjust the behavior of the template. If you select one of the parameters, additional information is displayed about the parameter in the comments box at the bottom of the process parameter table.
In the default process templates, these parameters are broken down into four categories: Required, Basic, Advanced, and Misc. Some of these parameters are worth calling out in this chapter, and are examined in the following discussions. However, it is worth familiarizing yourself with all the parameters and what they do.
Configurations to Build
The default Visual Studio build configuration to use is the default build configuration for your solution. To modify the configuration, use the Configurations dialog that is available when you press the…button in the Configurations to Build parameter under Required, Items to Build.
Logging Verbosity
By default, only messages above normal priority get included in the build log. However, you can adjust the logging priority to change the level of detail recorded. The more detailed the log, the slower the build will be performed, and the longer it will take to download build data to Visual Studio.
When diagnosing build problems, it is often useful to manually queue a build with this property set to Diagnostic. In that way, the log priority is only set for a single run of the build, rather than for all builds from that definition. The logging verbosity parameter can be found in the Basic category.
Agent Settings
Agent Settings can be found in the Advanced category of parameters. As well as limits for how long a build can run or wait for an available build agent, the Agent Settings group of process parameters includes both the Name Filter and Tags Filter. Together, these are used to determine on which build agent the build will be executed. If multiple build agents match the agent requirements, then the agent with the least number of builds running executes the build.
Specifying the Name of a build agent enables you to force it to run on a particular machine. You can also adopt a naming convention for your build agents, and then use wildcards in the Name Filter to assign builds to a pool containing a subset of all the build agents for the project collection (for example, “ProjectX*” for all build agents assigned to “ProjectX”).
A more flexible way you can limit which build agents are used for a build is to make use of the tagging feature for build agents. From the build agent properties dialog, you can assign tags (which are a set of text strings) to an agent to denote certain features. For example, you could use “CodeSign” if you have the project's code signing certificate installed on the machine, “Datacenter1” if it is located in your main data center, or “Ireland” if the build server is located in your remote office in Ireland. You can then filter on which tags are required for your build agent by using the Tags Filter in the Agent Requirements; only agents with that tag will be used.
To edit the tags applied to a particular agent, you can use the Team Foundation Server Administration Console on the build agent machine itself, or you can select the Actions ⇒ Manage Build Controllers…menu item in the Builds page in Team Explorer. You then select your build agent and click the Properties button. You are presented with the Build Agent Properties dialog, and, provided you have sufficient permissions, you are able to edit the assigned tags.
Clean Workspace
By default, the Clean Workspace parameter is set to All, meaning that all existing build outputs and sources for that build definition are deleted for every build. Although this is the safest option, it is also the slowest, because all the files must be downloaded from version control, and everything is rebuilt for every build, regardless of what has changed.
If you have a lot of source files (or some very large files in your source), then you could set the value of this parameter to Outputs. This simply deletes the build outputs every time the build is performed, and only gets the files that have changed between builds from version control.
If you set the value of the parameter to None, then neither the sources nor the build outputs are deleted at the start of a build. Only the files that have changed in version control are downloaded each time, and only the things that have changed are recompiled as part of the build. Because not a lot of things usually change between builds, this normally gives your builds a significant performance boost by taking much less time to complete. It is also often useful for things such as ASP.NET-based websites, where you might want to subsequently only publish the items that have changed to your public website to minimize the upgrade effect for new versions.
However, if you have customized your build process and you make any of the source files writable for some reason (for example, to modify the AssemblyInfo files to contain your version number), or if your customized build process assumes a clean output directory, then you may run into issues with altering the default value of the Clean Workspace. So, use with caution.
Note that on the hosted service at http://tfspreview.com, all build agents are created from a fresh image each time a build is executed so there is no persistence of the workspace in between builds. Therefore, altering this setting has no affect when using a hosted build agent.
Build Number Format
By default, Team Foundation Server numbers the builds in the format $(BuildDefinitionName)_$(Date:yyyyMMdd)$(Rev:.r). For example, in HelloWorld_20090927.5, the 5 is the fifth build executed for that build definition on that day. Build numbers must be unique across a team project, and this format serves as a good default. However, it is often not the format that people want.
Thankfully, starting in Team Foundation Server 2010, editing the build number is very easy using the Build Number Format parameter. When you edit the Build Number Format parameter, you are presented with a dialog, similar to Figure 5.18, that gives you the format string, a preview of what a build number of that format will look like when generated, and a set of macro strings that can be used in the format. Clicking each macro gives you more information about its behavior in the command section at the bottom of the dialog.
Figure 5.19
A common number format to use is $(BuildDefinitionName)_V1.0.0$(Rev:.r), where you are currently working on version 1.0.0 of the product, and the $(Rev:.r) macro translates to an incrementing number that makes the build number unique.
Path to Publish Symbols
The DefaultTemplate in Team Foundation Server includes a step to index source code and publish symbols to a symbol server in the organization. As mentioned earlier in this chapter, a symbol server is simply a file share that is used to store the symbols for your executable binaries. Visual Studio can then be configured with details of this server. From then on, when debugging code live, or using the advanced historical debugging features, Visual Studio is able to take you directly to the version of the source code from which the binary was generated, regardless of which version of the code that you have on your local system at that time.
The configuration of the symbol server is performed by adding the UNC file path of the share to be used as the symbol sever in the “Path to Publish Symbols” process parameter under “Basic, Source and Symbol Server Settings.”
Automated Tests
In the basic category of process parameters, you are able to configure automated tests that should run as part of the build using the Automated Tests parameter. By default, a new build runs all unit tests in assemblies matching the pattern *test*.dll. This means that, if you have created some unit tests in a companion test project called HelloWorldTests, for example, then they will be run automatically.
Pressing the…button opens the Automated Tests dialog shown in Figure 5.20, where you can add additional tests to run, or you can edit the test configuration.
If you select the existing test configuration and click Edit, the Add/Edit Test dialog shown in Figure 5.21 is displayed, enabling you to edit aspects of your test run. For example, you can configure it to fail the build on test failure, modify the test case filter criteria, specify the test runner, or enable code coverage data collection.
Get Version
Builds are usually performed with the latest sources from version control. However, occasionally you may want to perform a build of the source at a particular date, changeset, or label. In those circumstances, you can modify the Get Version process parameter which is in the Advanced section. This is usually done as you queue the build by clicking the Parameters tab. The value provided should be a valid version specification such as C1234 for changeset 1234, D2008-04-22T17:37 for a date/time, or LmyLabel for a label called myLabel.
Summary
In this chapter, you examined the build services provided by Team Foundation Server 2012 and how they have been enhanced from previous versions.
You learned how to create build definitions, trigger builds, and view and manage build results. You also learned how the new Windows Workflow-based build process works and how to perform common customizations by editing the process parameters.
In Chapter 6, you learn about common Team Foundation Server customizations, including how to edit the process template used by your builds to include new logic and parameters that do not ship in the default build processes.