Work with build workspaces

Just like you need a workspace on your dev machine to develop your app, you must specify the workspace that the build agent uses to build and test your app.

What do you want to do?

• Specify a workspace for your build definition

• See an example of a build workspace definition

• Copy data among workspaces

• Understand how a build workspace works

Specify a workspace for your build definition

When you define your build process, you should follow some best practices when you specify the workspace.

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 Projects field on the Process tab, you might have 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 requires. If a subfolder of a mapped folder contains files that the build process does not require, 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 require.

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

Tip

For more information about optimizing a workspace, see Optimize your 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. Here’s an example. A developer checks in changes to a folder. The folder is mapped in the workspace of a build definition and that build definition has a Gated Check-in trigger. The changes will be blocked until the build process is complete.

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. Choose 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 choose the Source Settings tab.

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

2. Open the shortcut menu for a row in the Working folders table, and then choose Select All.

3. Open the shortcut menu for a row in the Working folders table, and then choose 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 or edit a build definition.

6. On the Source Settings tab, Open the shortcut menu for a row in the Working folders table, and then choose 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.

Understand how a build workspace works

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 Deploy and configure 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.