Understanding the Build Definition Dialog

The build definition dialog can be accessed from the Team Explorer. For more information on accessing the dialog see:

You can use the Build Definition dialog box to create and edit build definitions. You have the following configuration options:

 

Workspace Section

The workspace section allows you to define the working folder layout for the workspace used to perform the build on the build agent.  Each path is mapped to a relative location beneath a root build directory on the build agent which is referenced as {SourceDir}.

The build agent will be running on a Microsoft Windows based operating system, therefore the relative LocalFolder paths must be provided using Windows directory naming conventions, i.e. a path separator of “\”. 

By default, the whole Team Project will be included in the workspace.  It is recommended that you limit this selection to only include the files you require to form your build.  You may also provide cloaked working folder mappings to hide folders with-in an active working folder mapping.

A “Copy Existing Workspace...” button (2) is provided to use the working folder mappings in an existing workspace as a template.

Project File Section

Team Foundation Build uses an MSBuild script named TFSBuild.proj to control the build process.

The project file section is used to browse to an existing TFSBuild.proj file in source control or to create a new TFSBuild.proj file to be associated with the build definition. If two or more build definitions share a single TFSBuild.proj file, customizing it affects each build definition.

If a build definition must be able to be managed from a Microsoft Visual Studio 2005 client, you must store the project file in a folder called “TeamBuildTypes” in the root of the Team Project in version control (1). This will be the default location specified; however, if all of the contributors to that build will be using Teamprise or Microsoft Visual Studio 2008 then the build folder may exist anywhere within the Team Project in version control.

Creating a New Project File.

If a file called TFSBuild.proj is not found in the specified directory then the “Create...” button will be displayed (2).  Pressing this will take you to the Create Build Configuration Wizard.

Select “MSBuild Configuration from Existing Ant Buildfile” and press Next.  You will then be presented with the Create Ant Build Configuration Wizard, which allows you to select the Ant file that will be used to perform your build.

Note that you must select a file that will be included as part of the workspace declaration defined earlier; otherwise the build will fail because it will be unable to find the build file during the build process.  Once you have selected the desired ant build file from version control, press finish and a TFSBuild.proj file will be generated for your build and checked into version control in the build configuration folder location specified in the project file section.

Retention Policy Section

Use this section to specify the retention policy for failed, stopped, partially-successful, or fully-successful builds.   For each status of completed build status, you may specify a number of builds of that type to keep automatically.

Note that if a build is marked as “Keep Forever” in the build explorer view then it will never be automatically deleted.  “Keep All” means that no completed builds with that status will be automatically deleted.

Build Defaults Section

This section is used to specify the build agent (the computer on which the build runs) and the shared folder where the built files are stored.  For more information on managing build agents see:

Note that the drop location, must be a valid path to a Microsoft Windows file share (or SMB share), on which the build machine can put the results of the build.  This path needs to be provided in the Microsoft Windows UNC format, i.e. \\servername\share.

Trigger Section

The trigger section is used to define when a build should be run.

Several triggers are provided by Team Foundation Build:

  1. Build run on demand (manual trigger)
  2. Build should run continuously on each check-in.  If the build agent has not finished performing an earlier build then the new build will be queued.
  3. Each check-in should add a build to the queue to be run as soon as an agent is free.  This can also be limited (3a) so that a minimum time between builds is provided.  This is useful if your build takes a long time and you have a large number of check-ins that would result in an unacceptable number of builds in the build queue.
  4. Scheduled (daily) builds.  You can specify the days on which the build is performed (4a) and the time (4b).  You can also force the build to always run at that time, even if no changes have been performed in the intervening period (4c).  Note that if the machine creating the build definition is in a different time zone to the Team Foundation Server then the actual time that the build runs might be unexpected during a period when daylight savings between those two time zones is different.  For more detail see the following blog post “Scheduling a Build in VS2008 and Daylight Savings Time”. Note that the bug mentioned in that post only occurs in the Visual Studio 2008 client (RTM version) and does not exist in the Teamprise clients.