Define a Build Using the Upgrade Template

You can use the Upgrade Template to continue to use legacy build definitions in Visual Studio Team Foundation Server 2010. Specifically, you can use this template to run the following kinds of build objects:

• Build definitions that were created by using Visual Studio Team System 2008 Team Foundation Server.

• Build types that were created by using Visual Studio 2005 Team Foundation Server.

When you first upgrade to Team Foundation Server 2010, the system automatically creates an Upgrade Template build definition for each legacy build definition and each build type that is in your system.

Also, when you use an older version of Visual Studio ALM to create a build definition or build type on a server that is running Team Foundation Server 2010, the system will automatically create an Upgrade Template build definition.

To modify most aspects of these legacy build objects, you must modify the TFSBuild.proj file. For more information, see Team Foundation Build Targets, Tasks, and Properties. But you can change some settings in the build definition object by opening the Builds node in Team Explorer. These settings are explained in this topic.

Required Permissions

To perform this procedure, your Edit Build Definition permission must be set to Allow. For more information, see Team Foundation Server Permissions.

To modify an Upgrade Template build definition

1. In Team Explorer, expand the team project in which you want to define your build, and then expand the Builds node.

2. Right-click the build definition that you want to modify, and then click Edit Build Definition.

3. On the Build Defaults tab, open the Build controller menu, and then select a build controller.

4. Click the Process tab.

5. Make sure that Upgrade Template appears under Build process template.

6. Expand the Required node.

7. In Configuration Folder Path, make sure that the path to the folder that contains your TFSBuild.proj file is correctly specified.

8. Use the information later in this topic to complete the fields that provide the functionality that you want to put into this build definition.

9. After you have completed the fields in the Process tab, as necessary, modify the fields in the Trigger, Workspace, Build Defaults, and Retention Policy tabs.

   For more information, see Create a Basic Build Definition.

In this topic

• About the Upgrade Template Build Process Parameters

• Specify Log Verbosity

• Specify Which Build Agents Process Your Build

• Specify Build Agent Time Limits

• Specify Advanced Build Process Parameters

About the Upgrade Template Build Process Parameters

This topic explains how to modify a build by using the build process parameters for builds that are based on the Upgrade Template. This information should match Visual Studio Application Lifecycle Management (ALM) as long as the following conditions are true:

• You are working in a team project that was created from one of the two process templates that are included with Visual Studio ALM: MSF for Agile Software Development v5.0 or MSF for CMMI Process Improvement v5.0.

• No one on your team has removed or customized the Upgrade Template.

Specify Log Verbosity

To specify the verbosity of the log that appears in the build results window, expand the Basic node, and then select a value in the Logging Verbosity list. The following table lists the Logging Verbosity values and their corresponding effects.

Value	Build Errors	Build Warnings	High-Importance Build Messages	Normal-Importance Build Messages	Low-Importance Build Messages	Workflow Activity Properties (inputs and outputs)
Minimal	Y	N	N	N	N	N
Normal	Y	Y	Y	N	N	N
Detailed	Y	Y	Y	Y	N	N
Diagnostic	Y	Y	Y	Y	Y	Y

The Logging Verbosity value that you specify also affects the verbosity of messages that come from MSBuild. For more information, see MSBuild Command Line Reference.

For more information about build reports, see View the Build Results Window.

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 fill in either of the following boxes:

• 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 ? 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 this build will be run only by build agents that have matching tags. 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 that is also tagged with the gated tag. To specify tags, click 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, click the Build Defaults tab, open the Build controller menu, and then select a build controller from that menu.

Specify Build Agent Time Limits

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

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	Type 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	Type 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.

Specify Advanced Build Process Parameters

To successfully complete some of the less typical scenarios, you must modify the build process parameters in the Advanced node.

If you want to…	Then set this parameter…	Using this guidance…
Specify the subdirectory where the binaries are located after they are built	Binaries Subdirectory	If you do not specify a subdirectory, the system will use a subdirectory that is named Binaries.
Use the build type definition that exists on the local computer	Do Not Download Build type	Set this flag to True if you want to use the build type definition that exists on the local computer instead of downloading the definition from Team Foundation Server. The local path used is the local workspace for the build type. This parameter is typically set to True temporarily so that you can debug a TFSBuild.proj file.
Generate error and warning log files for individual projects	Log File Per Project	Set this value to True to generate error and warning log files for individual projects instead of for individual platform and configuration combinations.
Specify command-line arguments to pass to MSBuild	MSBuild Arguments	If your build process requires that you pass arguments to MSBuild, type 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 2010 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. Note 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.
Make MSBuild recursively get and use files that are in your Configuration Folder Path	Recursion Type	Specify one of the following values: One Level if the folder that is specified in Configuration Folder Path contains files for MSBuild to process. Full if the folder that is specified in Configuration Folder Path or subdirectories of that folder contain files for MSBuild to process.
Specify the subdirectory that is used to map the workspace and build	Sources Subdirectory	Set this value to the appropriate sources subdirectory for the build agents that use this build computer. If you do not specify a subdirectory, the system will use a subdirectory that is named Sources.
Specify the subdirectory that is used to store the results of the tests	Test Results Subdirectory	Set this value to the appropriate test results subdirectory for the build agents that use this build computer. If you do not specify a subdirectory, the system will use a subdirectory that is named TestResults.