Define a Build Process that is Based on the Default Template

Article
08/20/2012

You can use the Default Template (DefaultTemplate.11.1.xaml) to quickly define a basic build by selecting the code projects that you want to build. You can also use this template to include more advanced functionality (such as running automated tests) and to adjust several aspects of the build process to meet your team's needs.

Required Permissions

To perform this procedure, you must have the Edit build definition permission set to Allow. For more information, see Team Foundation Server Permissions.

To create a build definition using the default template

In Team Explorer:
1. If you are not already connected to the team project that you want to work in, then connect to the team project.
2. Choose Home, and then choose Builds.
3. On the Builds page, choose New Build Definition.
A new build definition window appears.
On the Process tab, under Build process template, the Default Template is selected by default. Under Build process parameters, expand the Required node, and specify at least one solution or project to build.

For more information, see Specify the Projects You Want to Build later in this topic.
Use the information later in this topic to complete the fields that provide the functionality that you want to put into this build definition.
After you have completed the fields on the Process tab, specify build process options on the other tabs.

For more information, see Create a Build Definition.

In This Topic

About the Build Process Parameters for the Default Template
Specify the Projects You Want to Build
Specify the Platforms and Configurations You Want to Build
Specify Which Build Agents Process Your Build
Specify Build Agent Time Limits
Run Automated Tests and Enable Test Impact Analysis
Specify Basic Build Process Parameters
Specify Advanced Build Process Parameters

About the Build Process Parameters for the Default Template

This topic explains how to define a build by using the build process parameters in builds that are based on the Default Template. The information in this topic describes functionality that should match Visual Studio as long as the following conditions are true:

You are working in a team project that was created from one of the process templates that are included with Visual Studio.
No one on your team has removed or customized DefaultTemplate.11.1.xaml.

Specify the Projects You Want to Build

In the Projects to Build box, you can specify one or more solutions or code projects to build. (To display this box, expand the Required node, and then expand the Items to Build node.) You must specify at least one solution or project.

If you are building several related projects, you should typically add them to a single solution and specify that solution in the Projects to Build box instead of listing each project separately.

In the Projects to Build box, you can choose the ellipsis button (...) to open and use the Solutions/Projects dialog box to specify the solutions or projects to build.

To fill in the Projects to Build box manually, you specify the full version control path to each project or solution that you want to build. You delimit each value with a comma, as the following example shows:

$/Features/FeatureA/Server/All Server Projects.sln, $/Features/FeatureA/Client/All Client Projects.sln

Important

Make sure that the path to each project or solution is a child of one of the Source Control Folder values that is listed on the Workspace tab of the build definition.

Specify the Platforms and Configurations You Want to Build

In the Configurations to Build box, you can specify which platforms and configurations you want to build. (To show this box, expand the Required node, and then expand the Items to Build node.) For example, you can specify that this build should build only the release configuration of the 32-bit version of your C++ project by including Release|x86 in this box.

Tip

If you have a large codebase, you can significantly increase how quickly the build is processed by building only the configurations and platforms that you need.

If you leave the Configurations to Build box empty, the default configuration and platform that is defined in each solution or project is built.

In the Items to Build box, you can choose ellipsis button (...) to open and use the Configurations dialog box to specify which items to build. You can also specify them manually.

Each configuration in the Configurations to Build box should be in the following form:

Configuration|Platform

You must replace the following placeholders:

Configuration is a value such as Debug, Release, or All Configurations.
Platform is a value such as Win32, x86, x64 or Any CPU.

The configurations in the list must be delimited by commas.

For example, if you wanted to build both the Debug and Release configuration of your C# project, you would specify Debug|Any CPU, Release|Any CPU in the Configurations to Build box.

The tokens that you use for configuration and platform must match the tokens that are set up in your solution properties or code project properties. If they do not match, you may experience unexpected results when your build is completed.

Specify Which Build Agents Process Your Build

To specify which build agents are used to process your build, expand the Advanced node, expand the Agent Settings node, and then specify values for the following parameters:

Name Filter: You can filter the build agents that are used to process this build definition by typing the name of the agent in this field. You can also specify a set of names by using the * and the ? wildcard characters. For example, you could specify CI* to specify any agent whose name starts with the characters CI. Agents that would match this criterion include CI, CI1, or CI_Agent2.
Tags Filter: Specify one or more tags to ensure that only build agents that have matching tags will run this build. You typically apply tags to certain build agents to reserve them for special purposes. For example, you set up a build agent on a build machine that is designed to process your gated check-in builds. You apply the tag gated to this build agent. Finally, you apply the gated tag to the build definition so that it is processed only by the agent is also tagged with the gated tag. To specify tags, you choose the ellipsis button (...).

Note

The pool of build agents that are available to process this build is determined by the build controller that you have specified for this build definition. To modify the build controller, choose the Build Defaults tab, open the Build controller menu, and then choose a build controller.
Tag Comparison Operator: On the menu, choose one of the following values:
- MatchExactly: Choose this value if you want this build definition to be processed by only those build agents that have exactly the same set of tags that you specified in the Tags Filter box. If you do not specify any tags, any agent can process this build definition.
  
  Tip
  
  By choosing MatchExactly, you restrict the agents that are available for this build definition to only those that have the exact set of tags that are in the Tags Filter field.
- MatchAtLeast: Choose this value if you want this build definition to be processed by any build agent that has at least the same set of tags that you specified in the Tags Filter box. If you do not specify any tags, only agents that have no tags can process this build definition.

Specify Build Agent Time Limits

To specify time limits, you expand the Advanced node, expand the Agent Settings node, and then specify the parameters in the following table.

If you want to…	Then set this parameter…	Using this guidance…
Specify the maximum time allowed for the build agent to process the build	Maximum Execution Time	Enter a time span value in hh:mm:ss format. For example, the build will fail with a time-out error if you specify a value of 04:30:15 and the build agent has not completed its work after 4 hours, 30 minutes, and 15 seconds. Specify a value of 00:00:00 if you want to give the build agent unlimited time to process the build.
Specify the maximum time allowed to assign the build request to a build agent	Maximum Wait Time	Enter a time span value in hh:mm:ss format. For example, the build will fail with a time-out error if you specify a value of 01:30:45 and the build has not been assigned to a build agent after 1 hour, 30 minutes, and 45 seconds. Specify a value of 00:00:00 if you want to give the build controller unlimited time to find a build agent to process this build definition.

Run Automated Tests and Analyze Test Impact

You can design your build to perform one or more automated test runs and to analyze the impact of code changes on your tests. For more information, see Run Tests in Your Build Process.

Specify Basic Build Process Parameters

You often must modify the build process parameters in the Basic node to successfully complete some of the more typical scenarios.

If you want to…	Then set this parameter…	Using this guidance…
Perform one or more automated test runs	Automated Tests	Run Tests in Your Build Process
Customize the convention that is used to name completed builds	Build Number Format	You and your team can load useful data into the name of each completed build. For more information, see Work with Build Numbers. To customize this parameter, you can enter text directly into this field. However, you can more easily modify the value and display the available tokens by choosing the ellipsis button (...) to open and then use the BuildNumber Format Editor dialog box. In this dialog box, choose Macros to display and insert the tokens that you want to use.
Specify whether and how to clean the workspace of the build agent before it processes the build	Clean Workspace	On this menu, choose one of the following values: Select All to delete all existing outputs and source code files before the build is processed. Use this option if you want your compilation process to be as thorough as possible at exposing problems in your build process. Select Outputs to delete all existing outputs but to retain source code files that have not changed since the most recent build (by performing a tf get without the /all switch). Select None to leave existing outputs and to retain source code files that have not changed since the most recent build (by performing a tf get without the /all switch). Tip If your build process does not require the additional cleaning that the All option performs, you can significantly reduce the time that is required to run the build if you specify None (the fastest option) or Outputs. However, your team is more likely to miss some types of defects (such as those introduced during refactoring) if the workspace is not cleaned.
Specify how verbose you want the build log to be	Logging Verbosity	Build information is important to your team, but a build process that logs too much information can cause problems. Such problems can include depleting server storage and CPU resources, slowing server performance, and degrading the user experience in the build results window on the client computer. You can control how much information your deployment must process, store, and display. For more information, see Manage Build Information and Control Verbosity.
Analyze your code to find common defects	Perform Code Analysis	On this menu, choose one of the following values: Select As Configured to analyze each code project in which this feature is enabled. Select Always to analyze every code project, regardless of whether this feature is enabled in the code projects. Select Never to skip code analysis. For more information, see one of the following topics: How to: Set Code Analysis Properties for C/C++ Projects How to: Configure Code Analysis for a Managed Code Project How to: Configure Code Analysis for an ASP.NET Web Application
Store your symbols to enable features such as historical debugging	Index Sources and Path to Publish Symbols	You can configure your build definition to publish symbol data to enable features such as historical debugging. For more information, see Publish Symbol Data.

Specify Advanced Build Process Parameters

The build process parameters offered in the Advanced node are those that you need to modify to successfully complete some of the less typical scenarios.

If you want to…	Then set this parameter…	Using this guidance…
Specify build agent settings	Agent Settings	Specify Which Build Agents Process Your Build, Specify Build Agent Time Limits
Analyze test impact	Analyze Test Impact	Run Tests in Your Build Process
Link each completed build with all the changesets that went into the code as well as their associated work items	Associate Changesets and Work Items	In most cases the best practice is to set this parameter to True (the default value). This is especially true for scheduled builds (such as a nightly build) because you often use successfully completed scheduled builds to confirm fixes or run additional tests. Each build definition maintains its own record of which changesets and work items are waiting to be associated with the next completed build. For example, changeset 382 is built by both Build A and Build B. Build A is queued and successfully completed. Build B is queued and fails. Changeset 382 is now linked with the successfully completed build of Build A and the failed completed build of Build B. Changeset 382 will not be linked with the next completed build of Build A, but it will be linked with the next completed build of Build B.
Create a work item when the build fails	Create Work Item on Failure	Set this parameter to True if you want the system to create a work item when the build fails.
Disable tests	Disable Tests	Run Tests in Your Build Process
Build a specific version of your source code	Get Version	Specify the versionspec that identifies the version that you want to build. For more information about versionspecs, see Command-Line Syntax.
Label the version of each file that was compiled into each completed build	Label Sources	Set this parameter to True if you want the system to mark every source code file with a label. This action enables your team to easily identify which version of each file is included in the completed build.
Validate your code against layer diagrams	MSBuild Arguments	Include the following string in this parameter value: /p:ValidateArchitecture=true. For more information, see Validate Code with Layer Diagrams.
Specify command-line arguments to pass to MS Build	MSBuild Arguments	If your build process requires that you pass arguments to MSBuild, enter them in the MSBuild Arguments parameter. For more information, see MSBuild Command Line Reference.
Specify the bitness of the MSBuild version that is used to process your build	MSBuild Platform	Specify one of the following values: Specify Auto if you want to run MSBuild at the same CPU bitness of the Team Foundation Build Service that is installed on the build agent. Specify X86 to always process this build by using the 32-bit version of MSBuild. Because Visual Studio runs as a 32-bit application, you may experience problems when your build is processed by a build agent that is running the 64-bit version of Team Foundation Build Service. By specifying X86, you may resolve these kinds of problems. Specify X64 to always process this build by using the 64-bit version of MSBuild. If you specify this value, you should make sure (for example, by using a tag as explained earlier in this topic) that your build is processed by a build agent that is hosted by a 64-bit build machine. Otherwise, your build will fail.
Queue a private build	Private Drop Location	You typically do not specify a value for this parameter in the build definition. For more information about queuing a private build, see Queue a Build.
Organize output files by solution	Solution Specific Build Outputs	Set this parameter to True if you want to organize output files by solution.

Share via