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, or set the quality of the build.

The build quality is a text string assigned 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.

General Section

On the Builds page in Build Explorer, click General in the left-side 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 the latest version and generates 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 build, you should provide a short, one-line summary of what the build is for, and contact details about the owner or “build master” of 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, you should set the Queue Processing to Enabled, as this allows builds to be triggered as soon as the build definition is saved. However, it might be useful to adjust the Queue Processing setting 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

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. You should note that this option is available only when using Team Foundation version control. When users attempt 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 them 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 users are notified via the build notification tool in the system notification area. At this point, users can “reconcile” their workspaces 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 gets to pick which one is built to verify her changes at the time of check-in. In addition, even though Team Foundation Server 2013 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.

Source Settings

The Source Setting section (called Workspace in previous releases) 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)). In addition, you'll now see an entry for a folder called Drops in your Team Project that is cloaked (for example $/Demo/Drops). This Drops folder mapping is primarily designed for folks using Visual Studio Online and can be safely removed if you're only using the on-premises version of Team Foundation Server. That said, these default settings are almost always too broad for your build, and include 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 2013, 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 drop-down, 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 Visual Studio Online at http://visualstudio.com, a Hosted Build Controller is present for every project collection that allows builds to be performed using a build controller in the cloud.

You now have more choice when it comes to your staging location. 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. Note that the build definition name is appended to the path specified, so there is no need to specify it in the dialog.

For CI builds, you often only care about the correctness of the build. Therefore, the option to not copy build output to a drop folder can decrease build time and reduce management of the output. You can use the new option to copy the build output to your Team Foundation Server.

When talking to the hosted service, you also have the option to store files in version control. Traditional network shares are not easily accessible over the Internet. Therefore, a new option was created in the 2012 release that is only enabled for hosted builds to enable results of the build to be copied to version control. Note that when builds are deleted (either by the retention policy settings or manually) 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. This reduces the amount of space consumed by your project collection.

Process

When talking to a Team Foundation Server 2013 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.5-based processes. The initial list of processes are defined by the process template you 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 can 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 Default Template, 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 ellipsis (…) button to add your solution or project to the list. By default, if you have a version-controlled solution open in Visual Studio when you create a new build definition, Visual Studio will automatically set your current solution as the one to build. You'll of course need to make sure that the solution's files are available via the workspace mappings that you configure using the Source Settings option.

Retention Policy

After you start automating builds, you quickly end up with a lot of build results in your archive. Finding the build you need can get complicated—not to mention a large amount of disk space may be 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 want 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 output 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.

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 sometimes is 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 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 always runs 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.

Email Alerts

Basic and custom email 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 email 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.

Emails can be sent to any email 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 Server 12.0Tools folder, and can be used to script the creation of project alerts.

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 ellipsis (…) button in the Configurations to Build parameter under Required, Items to Build.

Logging Verbosity

In previous releases, you controlled how much log data Team Build generated. While in theory this could make your build run faster, when you had a problem, you had to change the setting, rerun the build, and hope the error occurred the same way. In 2013, Microsoft revamped how logging is handled and the build process always generates a detailed log that goes to a file and is put on your drop share as well as stored in the server. Because Microsoft removed a bunch of database I/O, you shouldn't see any negative performance impact to your build times.

Clean Workspace

The Clean Workspace parameter, only available in Team Foundation version control builds, changed in 2013 from being a three-value item to simply a True/False option. By default, the Clean Workspace parameter is set to True, 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 set the value of the parameter to False, 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://visualstudio.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 effect when using a hosted build agent.

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, only available in Team Foundation version control builds, which is in the TF Version Control 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.

Automated Tests

In the Test category of process parameters, you can 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 and *test*.appx. 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 ellipsis (…) button opens the Automated Tests dialog shown in Figure 5.18, 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.19 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.

Path to Publish Symbols

The Default Template 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 when using the advanced historical debugging features, Visual Studio can take you directly to the version of the source code from which the binary was generated, regardless of which version of the code 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 the Publish Symbols Server Settings. Unfortunately, this feature doesn't work with hosted builds on www.visualstudio.com.

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 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 setting 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 sets 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's 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 can edit the assigned tags.

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.20, 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.

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.