Work with Build Workspaces

During the build process, the build agent compiles and does other work with your source files. Before the build agent can do this work, it downloads the files from folders on your version control server into a local working directory. To facilitate downloading these files, the build agent creates a version control workspace, which maps the folders on the server to the local folders in the working directory for the build agent.

Before the build process starts

You set the working directory for each build agent in your build system. For more information, see Create and Work with Build Agents.

When you create your build definition, on the Workspace tab, you specify the folders that contain the files that you want to download and how these folders should be mapped to local folders on the build agent.

During the build process

The build process passes your workspace specifications to the CreateWorkspace workflow activity to create a workspace in its working directory.

The build process uses the DownloadFiles activity to download the files into the workspace. After this step, the build agent can start work (such as compilation) on these files.

Design a Workspace for Your Build Definition

When you design the workspace for your build definition, you should follow some best practices.

Include all required folders.

Make sure that you include all folders that contain files that your build process requires. For example, if you add another solution to the Items to Build field on the Process tab, you may need to add another mapping to the workspace.

Include only required folders.

Map with a Status value of Active only the folders that your build process needs. If a subfolder of a mapped folder contains files that the build process does not need, map it with a Status value of Cloaked. In many situations, when you create a build definition, the root folder of team project is mapped in the workspace. This configuration results in the build agent downloading all the files in the version control folder of your team project. If this folder contains lots of data, your build could waste build system resources and slow down your build process by downloading large amounts of data that it does not need.

When you remove items from the Items to Build field on the Process tab, look for mappings that you can remove from the workspace.

Use the $(SourceDir) token to map a server folder to a local folder in the ..\Sources subdirectory.

In most cases, the best location for the source files on the build agent is under the ..\Sources subdirectory in the working directory. You can specify this location by using the $(SourceDir) token in the Build Agent Folder box.

Be aware of how the workspace affects a build definition that is triggered by check-ins.

If you have set the Trigger of the build definition to Continuous Integration, Rolling builds, or Gated Check-in, the server folders that you map are bound to the build process. For example, if a developer checks in changes to a folder that is mapped in the workspace of a build definition that has a Gated Check-in trigger, those changes will be blocked until the build process is complete.

For more information about triggers, see Specify Build Triggers and Reasons.

Build Definition Workspace Example

Roberto, the build engineer, created the Storefront Nightly build definition.

This build definition builds two solutions: $/Core/Controllers/Controllers.sln and $/Core/Viewers/Viewers.sln. As a result, it must map the two folders that contain these solutions, the projects that they contain, and all the other files that they require.

To improve build process efficiency, Roberto excludes a folder that contains documentation files that his build process does not require: $/Core/Viewers/Docs.

The solutions depend on some binaries in a component library from another company. These binaries are protected by a proprietary mechanism that requires them to be located in a specific physical folder: c:\adatum\widgets.

Copy Data Among Workspaces

You can save time by copying mappings from one workspace to another.

To copy mappings from one of your workspaces

1. Click Copy Existing Workspace.

2. In the Select a Workspace to Copy dialog box, copy the mappings from the workspace.

To copy mappings from another build definition workspace or another team member’s workspace

1. Perform one of the following steps:

   • To copy mappings from another build definition workspace, open the build definition, and then click the Workspace tab.

   • To copy mappings from another team member’s workspace, ask the team member to open the File menu, click Source Control, and then click Workspaces. Select the workspace, and then click Edit.

2. Right-click a row in the Working folders table, and then click Select All.

3. Right-click a row in the Working folders table, and then click Copy.

4. Create a text file, paste the contents of the Clipboard into the text file, and then save it.

5. Create a build definition, or modify an existing build definition that is the target of the mappings that you are copying.

   For more information, see Create a Basic Build Definition or Edit a Build Definition.

6. On the Workspace tab, right-click a row in the Working folders table, and then click Paste.

7. As necessary, adapt the mappings for use by the build agent. In particular, make sure that the value in the Build Agent Folder box is correct and includes the $(SourceDir) token as appropriate.

For More Information

You define the build agent workspace when you create a build definition. For more information, see Create a Basic Build Definition.

A built agent workspace is basically the same mechanism as the version control workspace that a developer uses to work with source files in a team project. You can copy mappings between a version control workspace and a build agent workspace. For more information about version control workspaces, see Create a Workspace to Work with your Team Project.

Change History