How to: Create a Build Definition
Team Foundation Build uses build definitions to configure the conditions under which a single solution or a set of solutions in a team project will be built. To conduct a build, you must either create a new build definition or use an existing build definition.
When you create build definitions by using the Build Definition dialog box, you can set several options. These options include build name, source control workspace for the files to be built, and location of TFSBuild.proj project file, build agent, build retention policy, and the build trigger. If you do not have an existing MSBuild project file, you can use the Build Definition dialog box to launch the MSBuild Project File Creation Wizard to create a new TFSBuild.proj file for your build definition. You can also launch the Build Agent Properties dialog box to create a new build agent.
After you have created a new build definition, you can change these options. For more information, see How to: Edit a Build Definition.
You can customize your build definitions further by editing the TFSBuild.proj file that is written in MSBuild format. For more information, see Customizing Team Foundation Build.
Build definitions are removed by first deleting the builds that are associated with the build definition. Then the build definition itself can be deleted. For more information, see How to: Delete a Build Definition.
Required Permissions
To perform this procedure, you must have the Administer a build permission set to Allow. Additionally, the application-tier service account and the Team Foundation Build service account must have read/write permissions to the build drop location. For more information, see Team Foundation Server Permissions.
To create a new build definition
In Team Explorer, select the project for which you want to create a new build definition.
On the Build menu, select New Build Definition.
The Build Definition dialog box appears with General selected.
Tip
The tabs that have a warning icon next to them require input.
Specify the name to associate with the build definition in the Build definition name text box.
The name you enter must be a unique and valid Windows file name.
Add an appropriate description in the Description text box.
This description appears in the Queue Build "<team project name>" dialog box. For more information, see How to: Queue or Start a Build Definition.
Click the Workspace tab.
The Working folders table includes by default the source control folder for the team project for which you are creating the new build definitions and a local folder on the build agent. The local folder on the build agent is listed in the Local Folder column. All the workspace paths on the build agent are mapped relative to the default root directory shown.
To copy an existing workspace to the list of working folders, click the Copy Existing Workspace button to launch the Select a Workspace dialog box.
The workspace you select becomes a child of the common root directory on the build agent.
You can also click an empty table cell in the Source Control Folder, and then click the ellipses (…) to browse to a source control folder to add as a working folder. The source control folder you select is also normalized to the common root directory on the build agent.
Click the Project File tab. On the Project File pane you can either browse to an existing TFSBuild.proj project file or launch the MSBuild Project File Creation Wizard to create a new TFSBuild.proj file.
To browse to an existing TFSBuild.proj file, click Browse. On the Browse for Folder dialog box, select an existing build definition from the TeamBuildTypes folder, and then click OK.
The TFSBuild.proj file is now shared between the existing and your new build definition.
If a TFSBuild.proj file was found, the text: Found MSBuild project file: TFSBuild.proj is displayed on the Project File pane. If a project file was not found, the Project File pane displays warning text and advises you to create a new MSBuild project file.
.gif "Important note")
Important Note:Any change you make to a shared TFSBuild.proj file customizes all build definitions with which the file is associated. For more information, see Customizing Team Foundation Build.
To create a new project file for your build definition, click Create. The MSBuild Project File Creation Wizard appears.
On the Select and order solutions to build page, select the solutions to build. To order the solutions select a single solution and use the arrow keys to the right of the list to change their location in the build order.
Warning
Be aware of one solution having dependencies on another when you determine the order in which they are built. For example, if Solution2 has a dependency on Solution1, set Solution1 to build before Solution2.
Click Next.
The Select configurations to build page appears.
In the grid under Which configurations would you like to build, select the desired configuration and platforms to include in your build definitions. The build configuration indicates the configuration and platform, for example, Release and Any CPU.
Note
If you are creating a build definition for Web projects, select Mixed Platforms in the Platform drop-down menu.
Click Next.
The Select build options page appears.
Indicate the build options that you want to enable by selecting the Run test (e.g. run BVTs, etc.) and Run code analysis check boxes, as appropriate. If the Run test (e.g. run BVT's, etc.) check box is selected, use the drop-down options to specify the Test metadata file and Test list to run as appropriate.
For more information, see Using Test Lists and Writing Quality Code.
Important Note:In order to run tests, Team Edition for Testers has to be installed on the build agent. To run code analysis, Team Edition for Developers has to be installed on the build agent.
Click Finish.
The Project File pane of the Build Definition dialog box appears. The TFSBuild.proj file you created is stored in under $<Team Project>\TeamBuild Types\<Build Definition Name>\TFSBuild.proj in source control.
Click the Retention Policy tab. On the Specify how builds should be retained list, you can select the retention policy for failed, stopped, partially-successful, and fully-successful builds. Select a retention policy from the drop-down list. If you select <Specify Count to Keep> the Number of Builds dialog box appears. On the Specify the number of builds to retain text box, indicate how many builds you want to keep for the specified build outcome.
Click the Build Defaults tab. On the Build Defaults pane you can choose an existing build agent from the Build agent drop-down list. If no build agent exists or you want to create a new one, click New. The Build Agent Properties dialog box appears. Fill in the text boxes for Display name, Description and Computer name, and click OK. For more information, see How to: Create and Manage Build Agents.
In the Builds will be staged to the following share (for example, \\server\share) text box, type the UNC (\\server\share) location. The built binaries and log files will be located in this folder as soon as the build finishes.
Note
Before you complete this step, you must have created a public folder on the build agent computer where the TFSService account has full rights. For more information about Team Foundation service accounts, see How to: View Team Foundation Server Services.
Click the Trigger tab.
On the Trigger pane, select Check-ins do not trigger a new build to build on demand only.
Select Build each check-in (more builds) to build continuously every time a change is checked in to the files that are built by your build definition.
Select Accumulate check-ins until the prior build finishes (fewer builds) to create rolling builds. If the Accumulate check-ins until the prior build finishes (fewer builds) check box is selected, you can indicate how often builds take place by selecting the Build no more often than every check box and by entering a number in the minutes text box.
The valid range for the minutes text box is 0 to 2147483647 (Int32 MaxValue).
Note
If you are using Visual Studio Team System 2008 Team Foundation Server with Service Pack 1, you can set the rolling-build interval to between 120 and 240 minutes. If you are using Visual Studio Team System 2008 Team Foundation Server without Service Pack 1, Team Foundation Build ignores any value in that range.
Select Build every week on the following days to create scheduled builds. Select each day on which you want to build using the check boxes that are provided for each weekday. Enter the build time in the Queue the build on the default build agent at text box.
Note
Scheduled builds will not take place if no changes have been checked in since the previous build.
Click OK to create your build definition once you have filled in all the required information.
The created build definition is displayed in the Builds folder in Team Explorer. To review the information stored on the server for your build definition, right-click it in Team Explorer and click Edit Build Definition. The Build Definition dialog is displayed with the information you entered filled in. You can also change the information you entered. For more information, see How to: Edit a Build Definition.
Important Note:If your build definition shares a TFSBuild.proj file with another build, your build definition and the associated files do not display in Source Control Explorer under the TeamBuildTypes folder. Only the original build definition is listed.
See Also
Tasks
Walkthrough: Creating a Build Definition in Team Foundation Build
How to: Establish Permissions for Team Foundation Build Agent
How to: Set up and Install Team Foundation Build
Walkthrough: Customizing Team Foundation Build with a Custom Task
Concepts
Team Foundation Build Overview