Customizing Lab Management Workflow

Article
02/04/2013

The end-to-end workflow of Visual Studio Lab Management helps you automate building your application, deploying the new build to a virtual environment, and running tests on the new build. The LabDefaultTemplate ships as a default workflow template that you can use immediately. For information about how to use the LabDefaultTemplate, see How to: Deploy an Application on a Virtual Environment. But each build-deploy-test (BDT) process might be slightly different because of different requirements. For example, one workflow might require copying the test binaries from the regular build location whereas another workflow requires copying the test binaries from a temporary location. Or one workflow might require that the environment is saved in the library for each tester to deploy from, whereas another workflow does not save the environment at all. Because the default workflow template is based on Windows Workflow 4.0, it is fully extensible and customizable, and you can customize LabDefaultTemplate to meet your specific requirements.

This topic describes the general steps for customizing the workflow template and then provides five examples of scenarios where customization is very useful:

Specify test binaries location other than build location.
Support application deployments requiring a restart after installation.
Read source control files.
Access a build drop location using the build agent account.
Access other locations using the lab service account.

The Basic Concepts of Workflow Customization

There are three key concepts involved in workflow customization:

Template The template defines the sequence of activities or steps that are a part of the workflow. The template is based on Windows Workflow Foundation 4.0 and is stored as a .xaml file in Source Control. To load the template into the Workflow Editor, double-click the .xaml file. In the Editor, you will be able to see the various activities and sequences that determine the workflow. You can then use variables with different scopes, conditional logic, loops, and so on to program the template, just as you would with any other programming language. Windows Workflow Foundation enables you to customize the lab default template to suit your needs.
Activities The activity is the building block of a workflow, and the lab default template uses many activities. You can find additional activities in the Toolbox under the heading Team Foundation Lab Management Activities. To use an activity in the workflow, drag it from the toolbox into the Visual Studio Workflow Editor to appropriate location in the template. You can determine the input and output parameters by looking at the properties of the activity. For more information about each Lab Management activity, see Team Foundation LabManagement Activities. If the activities that are included with the product are insufficient to meet your requirements, you can add new activities.
Arguments You can create new input arguments for the inputs you need from the user, and pass these values to activities. Click the Arguments tab at the bottom of the Workflow Editor window to see the existing arguments. If you create new arguments, they will appear in the Build Process Parameters section of the Process tab in the build definition.

Think about these concepts as you review the following two examples where customization is needed. The first example talks about how to change the in-argument of an existing activity in the template, and the second example talks about how to add new activities from the toolbox. These examples should give you enough context to customize the LabDefaultTemplate according to your requirements.

Before Starting Customization

There are some general steps that you must complete before you start to customize the LabDefaultTemplate workflow template. The following diagram illustrates these steps.

Folder location for default workflow templates

To prepare for customization

In Team Explorer, double-click the Source Control node for your team project.
In Source Control Explorer, expand the Source Control tree and find the $/<Project_Name>/BuildProcessTemplates folder.
Map this folder to a local folder, for example, C:\Sources.
Right-click the file LabDefaultTemplate.xaml and then click Get Latest Version.
Make a copy of the file LabDefaultTemplate.xaml and give it a new name, for example, LabDefaultTemplate_customize.xaml
Add this new file to Source Control.
Double-click this new file. The file will open in the Visual Studio Workflow Editor.

Next you will customize the copy you just made of the default workflow template.

Customization to specify test binaries location other than build drop location

The default workflow template, LabDefaultTemplate, assumes that the location of the test binaries is the same as the location where builds are dropped. However, in your situation, the test code might not get built alongside the product code. If this occurs, you might want to customize the template so that test binaries are picked up from a different location. This customization involves three steps as shown in the following illustration.

Dragging a LabManagement activity from the toolbox

Defining a Workflow In-argument to Specify the Test Binaries Path

To define an in-argument

At the bottom of the workflow editor window, click the Arguments tab.
Click Create Argument. In the text box, type the name of the argument, for example, TestBinariesLocation. In the Direction drop-down list, click In. In the Argument type drop-down list, click String.

Passing an Argument Value to the ExecuteRemoteTestRun Activity

This activity creates a remote test run, waits until the test run finishes, and then updates the build information with test run statistics.

To pass the argument value

In the workflow editor, scroll to the activity Running Tests. Although the display name of the activity is Running Tests, the activity Type is ExecuteRemoteTestRun.
Right-click the activity and then click Properties. The Properties window opens in the lower-right corner and displays the in- and out- arguments of this activity. One of the in-argument of this activity is TestDirectory, which sets the path of the test binaries location.
In the Properties window, click TestDirectory. At the end of the row click the ellipses (…).
In the Expression Editor, type TestBinariesLocation and then click OK.
On the File menu, click Save LabDefaultTemplate_customize.xaml
On the Source Control Explorer menu bar, click the Check-in icon.

You can now use the customized .xaml file to create new build definitions. The new in-argument TestBinariesLocation will appear in the Misc section of the Process tab in your build definition, and you can assign a value there.

Customization to support application installers requiring a machine restart after deployment

The default workflow template, LabDefaultTemplate, does not restart the virtual environment after you deploy the application. You might want to customize the template to support applications that might require a restart after they are deployed. If you deployed the application manually in a virtual environment, you would restart only the virtual machine the where the application was installed. Visual Studio Lab Management does not support operations on individual virtual machines in an environment. Consequently, to restart one machine requires that all machines in the virtual environment be restarted.

Warning

Ensure that your deployment scripts never restart the virtual machine. If this occurs, the build agent running the deployment script will lose connection with the build controller and the workflow might stop.

Restarting the virtual machines after you deploy the new build requires adding three activities to the LabDefaultTemplate:

Stop the environment
Start the environment
Wait for the virtual machines to start before continuing with the rest of the workflow.

Stop the Environment

You can add a stop environment activity to the default workflow template by dragging the StopLabEnvironment activity from the Toolbox to the workflow template and initializing the activity variables.

To stop the environment

In the workflow editor, scroll to an activity with the display name Application Deployment Succeeded.
On the View menu, click Toolbox. The toolbox opens on the left side and displays a list of the Team Foundation Build Activities. Scroll through the list of activities until you see the list of Team Foundation Lab Management Activities.
In the toolbox, click the StopLabEnvironment activity. Drag it to the Workflow Editor, and position it before the Application Deployment Succeeded activity.
Right-click the activity and then click Properties. The properties window displays the in- and out-arguments for this activity. Notice the workflow already has a variable called LabEnvironmentUri which refers to the environment URI.
Click the Variables tab. The list of variables is displayed.
In the LabEnvironmentUri row and under the Default column, double-click Enter a VB Expression. In the text box, type LabEnvironmentUri. The editor will display any existing uses of the parameter and you can select the value from that list instead of typing it in.

Start the Environment

You can add a start environment activity to the default workflow template by dragging the StartLabEnvironment activity from the Toolbox to the workflow template and initializing the activity variables.

To start the environment

In the toolbox, click the StartLabEnvironment activity. Drag it to the Workflow Editor, and position it before the Application Deployment Succeeded activity but after the StopLabEnvironment activity.
Right-click the activity and then click Properties. The properties window displays the in- and out-arguments for this activity. Again, notice the workflow already has a variable called LabEnvironmentUri, which refers to the environment URI.

Click the Variables tab. The list of variable is displayed.

In the LabEnvironmentUri row and under the Default column, double-click Enter a VB Expression. In the text box, type LabEnvironmentUri. The editor will display any existing uses of the parameter and you can select the value from that list instead of typing it in.

Wait for the Machines to Restart before Continuing with the Rest of the Workflow.

You can add wait time for the virtual machines to start by dragging the Delay activity from the Toolbox to the workflow template and initializing the activity variables. This activity is located on the Primitives tab of the Toolbox.

To wait for the virtual machines to start

In the Toolbox, click the Primitives tab.
Click the Delay activity. Drag it to the Workflow Editor, and position it before the Application Deployment Succeeded activity but after the StartLabEnvironment activity.
Right-click the activity and then click Properties. The properties window displays the in- and out-arguments for this activity. Notice the workflow already has a variable called Duration, which refers to the wait time.
In the Properties window, click Duration and then click the ellipses (…).
In the Expression Editor, type the wait time (for example, 10 minutes) in the format TimeSpan.FromMinutes(10).

After you have modified this template, check it in to Source Control and use it to create a new build definition to deploy applications that require restart after installation.

Customization to read source control files

If you create custom activities and then use them in the workflow template, make sure that the build agent, which communicates by using the lab service account, can access those activities. Because these activities have to be checked in to the source control system as custom assemblies, you must make sure that that lab service account has permission to read the path in which custom assemblies are checked in. For more information about the lab service account, see How to: Configure the Service Account for the Testing and Workflow Integration You can grant permissions to the lab service account using the tf permissions command. For example, to grant read permissions to the lab service account mydomain\labAccount on the path $/MyProject/CustomAssemblies, you should execute a command similar to: C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE>tf permission /user:mydomain\labAccount /collection:http://aseemb-tfs10:8080/tfs/Collection0 /allow:read $/MyProject/CustomAssemblies

Customization to access a build drop location using the build agent account

The build agent that executes the lab workflow accesses the build drop location using the lab service account. If you want the build agent to use the build agent account instead, you can customize the workflow template. In the template, find the activity RunDeploymentScript which executes the deployment scripts. This activity exposes the property SharedLocationForNetUse, which defines the location that should be accessed by using the lab service account. <mtlwa:RunDeploymentScript DisplayName="Running Deployment Script" ScriptDetails="[scriptDetails]" ThrowOnError="True" SharedLocationForNetUse="[BuildLocation]" />To access the drop location under the build agent account instead of the lab service account, either delete the property from the template or set the value of this property to null ({x:Null}) as shown in this example: mtlwa:RunDeploymentScript DisplayName="Running Deployment Script" ScriptDetails="[scriptDetails]" ThrowOnError="True" SharedLocationForNetUse="{x:Null}" />

Customization to access other locations using the lab service account

If the build agent running under the lab service account needs to read locations other than the build drop location, you can change the value of the property SharedLocationForNetUse from the default value [BuildLocation] to the desired location. For example, for the build agent running under the lab service account to access \\contoso\scripts directory, you should have: <mtlwa:RunDeploymentScript DisplayName="Running Deployment Script" ScriptDetails="[scriptDetails]" ThrowOnError="True" SharedLocationForNetUse="\\contoso\scripts" />

Share via