Define a Build Using the Default Template
You can use the Default Template 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, click the team project in which you want to define your build.
On the Build menu, click New Build Definition.
In Build definition name, type a name.
Click 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, complete 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 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
Specify Test Categories
Set up Multiple Test Runs
Temporarily Disable Tests
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 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 Default Template.
Specify the Projects You Want to Build
In the Projects to Build box, you can specify one or more solutions or 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 click 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
Důležité
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 click 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 ? 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 click the ellipsis button (...).
Poznámka
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 click a build controller.
Tag Comparison Operator: On the menu, click one of the following values:
MatchExactly: Click 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 clicking 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: Click 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 |
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. |
Run Automated Tests
You can design your build to perform one or more automated test runs. For each test run that you set up, you can specify the following settings:
which tests are run
which settings are used to run the test
whether the build should fail if a test fails
Důležité
Your build can run tests only if it is processed by a build agent on which Visual Studio Test Professional 2010 is installed. For more information, see Create and Work with Build Agents.
To configure your build to run automated tests
On the Process tab of your build definition, expand the Basic node.
Select the Automated Tests box, and then click ellipsis button (...) in this box.
The Automated Tests dialog box appears.
Perform one of the following steps:
To add a new test run, click Add.
To modify an existing test run, click it, and then click Edit.
The Add/Edit Test dialog box appears.
Click the method that you want use to run the tests:
Test assembly file specification (recommended)
Leave the default value (**\*test*.dll) if you want the build agent to search recursively for any .dll files that match *test*.dll in the binaries subdirectory of the build agent's working directory. As an alternative, modify the file specification to meet your needs.
(Optional) Specify a Test Settings File to configure how the tests are run. For more information, see Create Test Settings to Run Automated Tests from Visual Studio.
Test metadata file (.vsmdi)
If you click this option, click Browse to locate and specify the test metadata file that you want to use. You can then either leave the Run all tests in this VSMDI file check box selected, or clear it and then select one or more tests in the Test lists to run list.
For more information, see Defining Test Lists to Group Your Tests.
Click the Criteria/Arguments tab.
(Optional) Filter the tests to run by category.
For more information, see Specify Test Categories later in this topic.
(Optional) Filter the tests to run by priority.
Tip
If you have assigned priorities to your tests, this parameter can be an important mechanism to help you define a balance between thorough testing and faster builds.
Set Minimum Test Priority to either a positive integer that is equal to or lower than Maximum Test Priority or to -1 to indicate no minimum value.
Set Maximum Test Priority to either a positive integer that is equal to or larger than Minimum Test Priority or to -1 to indicate no maximum value.
If you want the build to fail if any of the tests in this test run fail, select the Fail Build on Test Failure check box. If you leave this check box cleared and if any test fails, the completed build will be classified as Partially Succeeded.
Click OK.
Specify Test Categories
You can use test categories to filter the tests that are run during a test run.
Assign Categories to Your Tests
Before you can use test categories to filter the tests that you run, you must first assign categories to your tests by using Test Professional 2010. For example, you could create a test category called CI and then specify that category in your continuous integration builds. You could create another category for your build verification tests called bvt and then specify that category in scheduled builds, such as your nightly build.
For more information, see Defining Test Categories to Group Your Tests.
Specify Test Categories for a Test Run
You can specify test categories in two ways:
When you first create the test run, as explained earlier in this topic.
By modifying an existing test run. (You modify an existing test run by expanding the Basic node, expanding the Automated Tests node, expanding the test run that you want to modify, and then clicking in the Category Filter box.)
You can specify test categories in one of the following forms:
Specify a single test category to include or exclude. For example, you have a test category that is called bvt. You set this parameter to bvt to run only tests that are part of this category or !bvt to run all tests except those tests that are part of this category.
Specify multiple test categories by using the && ("and" operator) and the ! ("not" operator). For example, you can specify quick&&gui&&!deep to run only tests that are part of both the quick and gui categories but that are not part of the deep category.
Specify multiple test categories by using the | ("or" operator) and the ! ("not" operator). For example, you can specify quick|gui|!deep to run tests that are part of the quick category, tests that are part of the gui category, and any tests that are not part of the deep category.
Set up Multiple Test Runs
You can set up as many test runs as you need to meet the requirements of your team's build and test process. For example, you might need to set up multiple test runs in a single build in the following scenarios:
You have two sets of tests:
A set of top-priority core tests that must pass. You add a test run that specifies a Minimum Test Priority and Maximum Test Priority of 1. You select the Fail build on test failure check box.
A set of less important tests that you want to run but that are not required to pass for the build to be usable. You add a test run that specifies a Minimum Test Priority of 2 and a Maximum Test Priority of 3. You leave the Fail build on test failure check box cleared.
You want to run the same set of tests with different test settings.
You want the main set of assemblies that you build to be subject to code coverage. However, you have another set of assemblies from an external source that do not require code coverage. To enable this kind of process, you could use two test runs that are configured to use two sets of test settings files.
Temporarily Disable Tests
If you must temporarily disable tests without deleting your test runs, expand the Advanced node, and set Disable Tests to True. Set the value back to False when you want to enable tests again.
Enable Test Impact Analysis
Your testers and developers may need to know how code changes that are encompassed in a completed build have affected your tests. When you enable test impact analysis in a build, the system analyzes and then reports on how code changes affected your tests in the build report of the completed build.
To enable test impact analysis
Configure test impact analysis in a test settings file.
For more information, see How to: Collect Data to Check Which Tests Should be Run After Code Changes.
Create a test run that is configured to use the test settings file.
For more information, see Run Automated Tests earlier in this topic.
Expand the Advanced node, and make sure that Analyze Test Impact is set to True and that Disable Tests is set to False.
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… |
|---|---|---|
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 example, the default value includes tokens that are replaced with the following information:
To customize this parameter, you can type text directly into this field. However, you can more easily modify the value and display the available tokens by clicking the ellipsis button (...) to open and then use the BuildNumber Format Editor dialog box. In this dialog box, click 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, click one of the following values:
.gif "Tip") 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.
|
Specify how verbose you want the build log to be |
Logging Verbosity |
You can control the verbosity of the log that appears in the build report. For a list of the values and their corresponding effects, see Logging Verbosity Values later in this topic. For more information, see View the Build Results Window. |
Analyze your code to find common defects |
Perform Code Analysis |
On this menu, click one of the following values:
For more information, see one of the following topics: |
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. To enable Team Foundation Build Service to use SymStore to store your symbols, perform the following steps:
For more information, see Debugging with IntelliTrace and the following topics on the Microsoft Web site: |
Logging Verbosity Values
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.
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… |
|---|---|---|
Validate your code against layer diagrams |
MSBuild Arguments |
Include the following string in this parameter value: /p:ValidateArchitecture=true. For more information, see How to: Validate .NET Code Against Layer Diagrams. |
Specify command-line arguments to pass to MS Build |
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. |
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. |
Copy to the drop folder the executables and other binaries that result from building the projects |
Copy Outputs to Drop Folder |
Set this parameter to True to copy the executables and other binaries that result from building the projects to that drop folder. Note
The drop folder is specified in the Build Defaults tab.
|
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. |
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 on versionspecs, see Command-Line Syntax (Version Control). |
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. |
Specify the bitness of the MSBuild version that is used to process your build |
MSBuild Platform |
Specify one of the following values:
|