Walkthrough: Creating a Build Definition in Team Foundation Build
This walkthrough shows you how to configure a build definition for Team Foundation Build. Before you start this walkthrough, it is important to have some basic knowledge of Team Foundation Build. For more information, see Managing Builds with Team Foundation Build.
In this walkthrough, you step through the process of configuring a build definition by using the Build Definition dialog box. You will also establish the permissions required for the build agent and the users who will run the newly-created build definitions. In this walkthrough, you will complete the following tasks:
Create a new build definition.
Select the solutions to build.
Select a build agent and drop location.
Select build steps.
Select a configuration and the platforms for build.
Establish permissions on the build agent.
Establish permissions for specified users that will enable them to run the newly-created build definition.
Prerequisites
Visual Studio Team System Team Foundation Server.
A connection to a Team Foundation Server and at least one existing team project. For more information, see Walkthrough: Joining a Team Project and How to: Create a Team Project.
A workspace in the source control server that contains at least one solution to build. For more information, see How to: Create a Mapped Workspace.
Required Permissions
To complete this walkthrough, you must have the Administer a build permission set to Allow. Also, 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 you want 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. A local folder that mirrors the source control hierarchy is created on the build agent. The Local Folder column lists the local folder on the build agent. 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 is normalized to 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, appears on the Project File pane. If it does not find a project file, 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.
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, Test Edition has to be installed on the build agent. To run code analysis, Development Edition 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 Type 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.
Important Note:Before you complete this step, you must first create 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.
Note
Each generated build will be dropped into a separate directory. You will need to ensure that the account with which build computer is configured has write access to this UNC location.
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 you checked the Accumulate check-ins until the prior build finishes (fewer builds) check box, 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).
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 your information 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 default location, the TeamBuildTypes folder. Only the original build definition is listed. You can also store the TFSBuild.proj file in another location.
To establish build permissions
Contact the system administrator for the previously selected build computer to determine the name of the account under which the Visual Studio Team Foundation Build service is running.
From Team menu, select Team Project Settings, and then select Group Membership.
The Project Groups dialog box appears.
In Project Groups, under the Users and Groups listing, find the group called Build Services, and click Properties.
The Team Foundation Server Group Properties dialog box appears.
Select the Members tab.
If the account obtained in the preceding step is present in the member list, then the selected build computer can build this build definition. Otherwise, use the following steps:
In the Add member section, choose Windows User or Group, and click Add.
The Select Users or Groups dialog box appears.
In Select Users or Groups dialog box, enter the account associated with the Visual Studio Team Foundation Build service on the build computer used for this build definition.
Note
If this build definition is built on multiple build agents, then all of the Visual Studio Team Foundation Build service accounts need to be added as members of this project's 'Build Services' group.
Configure which users are to run build definitions by granting them the start/resume a build permission.
See Also
Tasks
Walkthrough: Running a Build Definition in Team Foundation Build
How to: Set up and Install Team Foundation Build
How to: Create a Build Definition
How to: Establish Permissions for Team Foundation Build Agent