Use the Default Template for your build process
The Default Template (.png "TFVC icon")
TfvcTemplate.12.xaml or .png "Git icon")
GitTemplate.12.xaml) lets you quickly define a basic process that builds and tests your code. You have options to control the way Team Foundation Build (TFBuild) builds your code, runs your tests, and runs other processes such as scripts.
Get started
(Optional) Before you create a new build definition, from the Team Explorer Home page (Keyboard: Ctrl + 0, H), open the solution you want to build so that it is automatically specified in the Projects box.
In Team Explorer, make sure you are connected to the team project (Keyboard: Ctrl + 0, C), and then open the Builds page (Keyboard: Ctrl + 0, B).
Choose the New Build Definition link or select a build, open its context menu, and choose Edit Build Definition.
Tip
If a TF225001 error message appears, configure a build controller.
On the Process tab, under Build process template, the Default Template is selected by default.
.png "Default Template build process")
Warning
Are you connected to a
Git team project hosted on Visual Studio Online? Are you missing the Checkout override and Projects parameters?.png "Parameters from the wrong Git default template")
See How do I make sure I’m using the correct default Git build process template on Visual Studio Online?
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 or edit a build definition.
What do you want to do next?
Get your code
Build your code
Specify the projects to build
Specify the platforms and configurations to build
Specify build options
Run other processes during the build
Perform code analysis during the build
Control how the servers run your build
Specify which build agents process your build
Specify build agent time limits
Control the build outcome
Specify the build output location
Make the names of completed builds useful to your team
Publish symbols from the build
Associate and create work items
Create a work item on failure
Label your source code
Get answers to common questions
Get your code
You can set some options for how the build agent gets the source code that you’ve specified on the Source Settings tab.
If you want to… |
Then set this parameter… |
Using this guidance… |
|---|---|---|
Specify whether to clean the workspace or Git repo on the build agent before it processes the build |
|
Select True to delete all existing outputs and source code files before the build is processed. Use this if you want your compilation process to be as thorough as possible at exposing problems in your build process. Tip If your build process does not require a clean workspace or repository, you can significantly reduce the time that is required to run the build setting this parameter value to False. This setting has no effect if you use the Hosted Build Controller. In this case, you get a new working directory with each build. |
Build a specific version of your source code |
|
TFVC: Specify the versionspec that identifies the version that you want to build. Git: specify the branch or commit id to checkout. |
Build your code
You can use MSBuild to compile your code.
Specify the projects to Build
In the Projects box under Build in the Build process parameters table, you can specify one or more solutions or code projects to build. 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 cell instead of listing each project separately.
In the Projects 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 box manually for a TFVC team project, 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
If you use TFVC, make sure that the path to each project or solution is a child of one of the Source Control Folder values that are listed on the Source Settings tab of the build definition. If you use Git, make sure that the project or solution is in your Git repo, in a branch that you’re building.
Specify the platforms and configurations to Build
In the Configurations box, you can specify which platforms and configurations you want to build. 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 box empty, the default configuration and platform that is defined in each solution or project is built.
In the Configurations 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 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 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 could experience unexpected results when your build is completed.
Note
If you are building individual code projects instead of a solution file and you want to specify Any CPU as the platform, you should specify it as AnyCPU instead of Any CPU.
Specify build options
You can control several build options.
If you want to… |
Then set this parameter… |
Using this guidance… |
|---|---|---|
Control whether to rebuild |
Build, Clean build |
Set to True if you want to rebuild all the code in the code projects. This is equivalent to MSBuild /target:clean. This option has no practical effect unless you also set Clean repository to False. Tip You can significantly reduce the time that is required to build large codebases by setting this option to False. |
Validate your code against layer diagrams |
Build, Advanced, 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 |
Build, Advanced, 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 |
Build, Advanced, MSBuild Platform |
Specify one of the following values:
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. |
Run other processes
You can run other processes during the build.
Perform code analysis
To find common defects during the build, you can analyze your code. Set the Perform code analysis parameter in the advanced build parameters.
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:
Control how the servers run your build
You can control how the build servers run your build
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. |
Control the build outcome
Specify the Build Output Location
To control where the TFBuild places the build outputs, choose:
SingleFolder to place all the build output files together in the drop folder.
PerProject to group the build outputs into drop folder sub-folders for each solution or code project that you have specified in the Projects box.
AsConfigured to leave the binaries in the build agent sources folder, organized into the same sub-folder structure you see when you build your code on your dev machine in Visual Studio. This structure is defined in your code projects.
If you use this option, TFBuild will not copy the output to the drop folder. Instead, you can program your scripts to copy the outputs to the location specified by TF_BUILD_BINARIESDIRECTORY so that they get dropped to the staging location. See post-build or post-test scripts.
Make the names of completed builds useful to your team
You and your team can use the Advanced, Build number format to load useful data into the name of each completed build. For the valid values for this parameter, see Use build numbers to give meaningful names to completed builds.
Publish Symbols from the Build
Specify the Path to publish symbols parameter to index and publish symbol data to enable features such as historical debugging. See Index and publish symbol data.
Associate changesets, commits, and work items
The build process automatically links each completed build with all the changesets or commits that went into the code as well as their associated work items. You cannot disable this behavior, but under Advanced you can decide whether or not you want to Update work items with build number by selecting True or False.
How does the build process determine when to associate changesets, commits, and work items?
Create a work item on failure
For Advanced, Create work item on failure, select True if, when the build fails, you want the build process to create a bug and assign it to the person who checked in the TFVC changeset or pushed the Git commit.
Label your source code
For TF Version Control, Label Sources select True if you want to automatically mark every source code file with a label to enable your team to easily identify which version of each file is included in the completed build. This setting does not apply to Git team projects.
For information about how TFBuild determines which version to label, see How good was that build?
Q & A
How do I make sure I’m using the correct default Git build process template on Visual Studio Online?
Are you connected to a Git team project hosted on Visual Studio Online? Are you missing the Checkout override and Projects parameters?
When you show details does Default Template (GitTemplate.xaml) appear?
.png "The wrong Git default template")
If so, select GitTemplate.12.xaml. After you do this, the Checkout override parameter and the browse button in the Projects parameter will appear.
.png "The correct Git default template")
Q: How does the build process determine when to associate changesets, commits, and work items?
A: Each build definition maintains its own record of which changesets (TFVC), commits (Git), 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.
For information on how TFBuild determines which version to associate, see How good was that build?