Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Lab management workflow activities

 

When you customize a Lab Management workflow template (LabDefaultTemplate.11.xaml), you can use one or more of the pre-defined Lab Management activities. You can also access objects that are created by the Lab Management wizard. This topic describes the Team Foundation Lab Management activities and objects that are available when you customize a workflow template to build, deploy, and test your application. For information about how to use these activities in a customized workflow, see Customizing lab management workflow.

Requirements

  • Visual Studio Enterprise, Visual Studio Test Professional

The following table describes the individual Lab Management workflow activities.

ActivityDescription
CreateLabEnvironmentCreates a new environment from a stored template and deploys it on the specified host group.
DeleteLabEnvironmentDeletes an environment.
DeleteSnapshotDeletes a snapshot of an environment.
ExecuteRemoteTestRunCreates a test run on an environment and waits for it to finish.
GenerateEnvironmentViewerFileGenerates an environment viewer file that has snapshot link ID. It is used to connect to a snapshot of the environment.
GetBuildLocationAndBuildNumberReturns the build location and build number for a build, deploy, and test scenario.
GetLabEnvironmentInUseMarkerReturns the In Use marker for an environment.
GetLabEnvironmentSnapshotIdGets the ID of a snapshot of an environment.
GetLabEnvironmentStatusGets the environment status.
GetLabEnvironmentUriGets the environment URI for a given environment name and lab location name.
InitializeAgentSpecAndEnvironmentVariablesParses the deploy script details specified by property
ResetLabEnvironmentInuseMarkerResets the In Use marker for an environment.
RestoreLabEnvironmentRestores the environment to the specified snapshot.
RunDeploymentScriptRuns the deployment script. On failure, throws or writes a build warning as specified in the ThrowOnError property.
RunWorkflowQueues a new workflow on a build controller of a build server.
SaveLabEnvironmentCreates a new environment and stores it in a team project library share.
SetLabEnvironmentInuseMarkerSets the In Use marker on environment.
SnapshotLabEnvironmentTakes a snapshot of an environment.
StartLabEnvironmentStarts the environment.
StopLabEnvironmentStops the environment.
WaitForTestCapabilityServicesWaits the specified maximum time for the testing capability of environment to be ready. At the end of the wait time, if the test capability is not ready, a time-out exception is thrown.
WaitForWorkflowType of workflow.
WaitForWorkflowCapabilityServicesWaits for the queued build to complete for a given maximum wait time. If the build workflow does not finish in the given maximum time, the TimeOutException is thrown. The activity checks the queued build status periodically to determine which builds are finished. This interval is configured by using the RefreshInterval property.
WriteDeploymentInformationWrites deployment information that is included in the build summary.

CreateLabEnvironment

Creates a new environment from a stored template and deploys it on the specified host group. This is a long-running activity and will wait until the new environment is created. If the new lab environment cannot be created, this activity throws a LabDeploymentProcessException exception.

Properties

LabEnvironmentNameName of the new environment. If this property is null or empty, the environment template name will be used.
LabEnvironmentTemplateUriURI of a stored environment template. The lab environment template URI can be obtained by using GetLabEnvironmentUri activity. Required.
TeamProjectHostGroupNameHost group where the new environment will be deployed. If the specified host group is not found, a NoTeamProjectHostGroupFoundException exception is thrown. Required.

Back to top

DeleteLabEnvironment

Deletes an environment. This is a long-running activity and will wait until the environment is deleted. If the environment deletion fails, this activity throws a LabDeploymentProcessException exception.

Properties

LabEnvironmentUriURI of environment to be deleted. The lab environment URI can be obtained by using GetLabEnvironmentUri activity. Required.

Back to top

DeleteSnapshot

Deletes a snapshot of an environment. This is a long-running activity and will wait for the snapshot to be deleted. If the snapshot deletion fails this activity throws a LabDeploymentProcessException exception.

Properties

LabEnvironmentUriURI of the lab environment whose snapshot will be deleted. The lab environment URI can be obtained by using GetLabEnvironmentUri activity. Required.
SnapshotIdID of snapshot to be deleted. The snapshot ID can be obtained by using the GetLabEnvironmentSnapshotIdactivity. Required.

Back to top

ExecuteRemoteTestRun

Creates a test run on an environment and waits for it to finish. This is a long-running activity that waits until the test run finishes or time-out occurs. You can set the time-out using the MaxWaitTime property. This activity checks the test run status periodically to determine which test runs are finished. This interval is configurable using the RefreshInterval property. The MaxConsecutiveFailuresToIgnoreDuringWaitForCompletion property can be used to specify the number of consecutive times to ignore Team Foundation Server errors while checking for the test run status.

Return value

A TestRunStatistics object that stores the details of the test run.

Properties

BuildNumberBuild number on which tests are run.
LabEnvironmentUriURI of the environment on which test cases will be executed. The environment URI can be obtained by using the GetLabEnvironmentUri activity.
MaxConsecutiveFailuresToIgnoreDuringWaitForCompletionMaximum number of consecutive failures that should be ignored while the activity waits for the tests to run. The default value of this property is 3.
MaxWaitTimeA TimeSpan that specifies the maximum wait time for the test run to finish. A time-out exception is thrown at the end of specified time duration. The default value is 0 (zero), which means that the activity waits indefinitely.
RefreshIntervalA TimeSpan that specifies the interval after which the status of the test run is refreshed. The default value of this interval is 60 seconds.
TestDirectoryPath to the test executables.
TestEnvironmentName of the test environment on which test cases will be executed.
TestParametersA RunTestDetails object that specifies test parameters such as the test plan, the test suite, the test settings, and the test configuration. Required.
TitleName of the test run. Required.

Back to top

GenerateEnvironmentViewerFile

Generates an environment viewer file which contains the ID of the snapshot link. This activity is used to connect to a snapshot of the environment. The name of the environment viewer file is the snapshot name without any of the following special characters: @"[`~!@#$%^&*()+=[{\]}|\\;:',/?]" + "\"".

Properties

FilePathUNC path of where to store the environment viewer file. The build service account must have write permission for the path. Required.
LabEnvironmentUriURI of the environment. The environment URI can be obtained by using the GetLabEnvironmentUri activity. Required.
SnapshotIdID of the snapshot. Snapshot ID can be obtained by using the GetLabEnvironmentSnapshotIdactivity. If the snapshot is not valid, an InvalidSnapshotException exception is thrown. Required.

Back to top

GetBuildLocationAndBuildNumber

Returns the build location and build number for a build, deploy, and test scenario. If "team build" is selected and build the URI is null, the last good build is selected and details are returned. If no last good build is found, a System.ArgumentException is thrown. If "team build" is not selected, only the build location specified by the user is returned.

Return value

A String that specifies the build location.

Properties

BuildDetailsA Microsoft.TeamFoundation.Lab.Workflow.Activities.BuildDetails object that contains build-related information in build, deploy, and test scenario.
BuildNumberBuild number of the selected build. This is an outArgument. This is null for non "team build" builds.
SelectedBuildBuild information about the build server. This is an outArgument. This is null for non "team build" builds.

Back to top

GetLabEnvironmentInUseMarker

Gets the In Use marker for an environment.

Return value

A LabEnvironmentInUseMarker that specifies the details of the environment marker

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

GetLabEnvironmentSnapshotId

Gets the snapshot ID of a snapshot of an environment. If no snapshot with specified name is found, this activity throws a NoSnapshotFoundException exception.

Return value

An Int64 that specifies the identifier of the snapshot.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.
SnapshotNameSnapshot name. Required.

Back to top

GetLabEnvironmentStatus

Gets the status of the environment.

Return value

A LabEnvironmentState enumerated value that indicates the current state of the environment.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

GetLabEnvironmentUri

Gets the environment URI for a given environment name and lab location name. The lab location can be either a host group or a library share. If environment is not found, this activity throws LabEnvironmentNotFoundException exception.

Return value

A String that specifies the uri of the environment.

Properties

LabEnvironmentNameEnvironment name. Required.
ProjectNameName of the team project. If this property value is null or is not specified, the current project of the build is used.
TeamProjectLabLocationNameLab location name. Can be either a host group name or a library share name. If the lab location is not found, a NoLabLocationFoundException exception is thrown. Required.

Back to top

InitializeAgentSpecAndEnvironmentVariables

Initializes the arguments required for the RunDeploymentScript activity. InitializeAgentSpecAndEnvironmentVariables extracts the properties of the virtual machines in the environment, that are required to target the deployment script on the machines.

Return value

A ScriptDetails object that stores the script details that are required for deployment.

Properties

BuildLocationBuild location path. This is used to expand the macro $(BuildLocation). Required.
DeploymentScriptDetailsDeployment details in the format " labsystemname | script arguments | working directory". Required.
LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

ResetLabEnvironmentInuseMarker

Resets the In Use marker for an environment.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

RestoreLabEnvironment

Restores the environment to the specified snapshot. If the snapshot is not valid, the activity throws an InvalidSnapshotException exception.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.
SnapshotIdID of the snapshot to restore the environment to. The snapshot ID can be obtained by using GetLabEnvironmentSnapshotId activity. Required.

Back to top

RunDeploymentScript

Runs the deployment script. If the script fails, throws or writes a build warning as specified in the ThrowOnError property.

Return value

A BuildStatus enumerated value that specifies the status of the deployment operation.

Properties

MaximumAttemptsForNetUseMaximum number of attempts to add net use.
ScriptDetailsA Script Details object for a lab system. Required.
SharedLocationForNetUseLocation that should be accessible by the lab service account.
ThrowOnErrorFlag to indicate if exception should be thrown for error. Default value is True.

Back to top

RunWorkflow

Queues a new workflow on a build controller of a build server. There are two ways that you can specify on which build controller the build has to be queued:

  1. Use the LabEnvironmentUri property. If this environment is configured for workflow integration, it will use its build controller of the environment for queuing workflow. Otherwise, a LabDeploymentProcessException is thrown.

  2. Use the BuildControler property to specify the build controller.

Return value

An Int32 that specifies the ID of the queued build.

Properties

BuildControllerBuild Controller Name. If this property and the LabEnvironmentUri property value are null or are not specified, the current build controller is used to queue the build.
BuildDefinitionBuild definition to be queued. Required.
LabEnvironmentUriURI of environment with workflow capabilities. Use the GetLabEnvironmentUri activity to get the environment URI. Required.
ProjectNameName of the team project. If this property is null or is not specified, the current project of the build is used.

Back to top

SaveLabEnvironment

Creates a new environment and stores it in a team project library share. This is a long-running activity and will wait until the environment is saved. If creating the new environment fails, this activity throws a LabDeploymentProcessException exception.

Return value

A String that specifies the url of the new environment.

Properties

LabEnvironmentNameName for saved environment. If this property is null or is empty, the environment name will be used.
LabEnvironmentUriURI of the environment to be saved. Use the GetLabEnvironmentUri activity to get the URI of the environment. Required.
TeamProjectLibraryShareNameLibrary share where environment is stored. If the specified library share is not found, a NoTeamProjectLibraryShareFoundException exception is thrown. Required.

Back to top

SetLabEnvironmentInuseMarker

Sets the In Use marker on environment.

Properties

CommentComment written when the marker is set.
LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

SnapshotLabEnvironment

Takes a snapshot of an environment. This is a long-running activity and will wait until the snapshot of environment is created. If creating the snapshot fails, this activity throws a LabDeploymentProcessException exception.

Return value

A Int64 that specifies the ID of the snapshot.

Properties

LabEnvironmentUriURI of environment whose snapshot has to be taken. Use the GetLabEnvironmentUri activity to get the environment URI. Required.
SnapshotChainIdReturns the snapshot chain ID.
SnapshotNameName of the snapshot to be taken. If this property is null, the current DateTime value is used as the snapshot name.

Back to top

StartLabEnvironment

Starts the environment. This is a long-running activity and will wait until the environment starts. If starting the environment fails, the activity throws a LabDeploymentProcessException exception.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

StopLabEnvironment

Stops the environment. This is a long-running activity and will wait until the environment stops. If stopping the environment fails, the activity throws a LabDeploymentProcessException exception.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

Back to top

WaitForTestCapabilityServices

Waits the specified maximum time for the testing capability of environment to be ready. If the test capability is not ready at the end of the wait time, a time-out exception is thrown. If the RepairCapabilityBeforeWaitBegins property is set, the repair capability is invoked before waiting for capability to be ready. The maximum wait time can be configured by using the MaxWaitTime property.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.
MaxWaitTimeA System.TimeSpan object that specifies the maximum wait time for capability to be ready. A time-out exception is thrown at the end of specified time-out duration. The default value is 0 (zero), which means wait indefinitely.
RepairCapabilityBeforeWaitBeginsIf this value is true, an attempt to repair capability will be done before waiting.

Back to top

WaitForWorkflow

Waits for the queued build to complete for a given maximum wait time. If the build workflow does not finish in the given maximum time TimeOut Exception is thrown. The activity checks the queued build status periodically to determine which builds are finished. This interval is configured by using the RefreshInterval property.

Return value

A [T: Microsoft.TeamFoundation.Build.Client.BuildStatus](assetId:///T: Microsoft.TeamFoundation.Build.Client.BuildStatus?qualifyHint=False&autoUpgrade=True) enumerated value that indicates the status of the workflow.

Properties

AllowPartiallySucceededBuildIf true, partially succeeded is treated as success.
BuildDetailsA Microsoft.TeamFoundation.Build.Client.IBuildDetail object that contains queued build details on the build server. This is an out argument.
LabWorkflowTypeThe type of workflow.
MaxConsecutiveFailuresToIgnoreDuringWaitForCompletionMaximum number of consecutive failures that should be ignored while it waits for the workflow to finish. The default value of this is 3. This property can be used to increase the robustness of workflow.
MaxWaitTimeA System.TimeSpan object that specifies the maximum wait time for the workflow to finish. A time-out exception is thrown at the end of specified time-out duration. The default value is 0 (zero) which means wait indefinitely.
QueueBuildIdThe ID of the queued build. Required.
RefreshIntervalA System.TimeSpan object that specifies the interval after which the status of the workflow is refreshed. The default value of this interval is 60 seconds.
ThrowOnErrorIf true, throws an exception if build fails.

Back to top

WaitForWorkflowCapabilityServices

Waits the specified time for the workflow capability of environment to be ready. If the workflow capability is not ready at the end of the wait time, throws a time-out exception. If the RepairCapabilityBeforeWaitBegins property is set, the repair capability is invoked before waiting for the capability to be ready. The maximum wait time can be configured by using the MaxWaitTime property.

Properties

LabEnvironmentUriURI of the environment. Use the GetLabEnvironmentUri activity to get the environment URI. Required.
MaxWaitTimeA System.TimeSpan object that specifies the maximum wait time for capability to be ready. A time-out exception is thrown at the end of specified time-out duration. Default value is 0 (zero), which means wait indefinitely.
RepairCapabilityBeforeWaitBeginsIf this value is true, an attempt to repair the capability will be done before waiting.
WaitForComputerNamesIf this value is true, waits until the computer names of all the virtual machines of the environment are available.

Back to top

WriteDeploymentInformation

Writes deployment information that is included in the build summary. Deployment information section has three sub sections: Build, Deployment, and Test. You can add deployment information to a particular subsection by using the DeploymentInformationType property. Links can be added to deployment information by using the Url property.

Properties

MessageMessage to be displayed in the summary. Required.
UrlOptional URL or link to add to the message.
DeploymentInformationTypeSpecifies the subsection of the deployment information for this information message. Use one of the following values:

- Build
- Deploy
- Test

Back to top

The following table summarizes Lab management classes that you can use in the Workflow Designer to customize a build, deploy, and test process. The classes are part of the Microsoft.TeamFoundation.Lab.Workflow.Activities namespace.

ObjectDescription
LabWorkflowDetailsThe LabWorkflowDetails class contains the configuration data from the Lab Workflow Parameters wizard. The LabWorkflowDetails object contains BuildDetails, RunTestDetails, and ScriptDetails objects.
BuildDetailsStores the build details for a build, deploy, and test scenario.
DeploymentDetailsStores the test parameter details that are required to create the automated test run in the build, deploy, and test workflow
LabEnvironmentDetailsStores the information required to identify the lab environment in build, deploy and test scenario
LabEnvironmentInUseMarkerStores details of the In Use marker of an environment.
LabEnvironmentStateSpecifies the current state of the environment.
RunTestDetailsStores the test parameter details that are required to create the automated test run.
ScriptDetailsStores the deployment script details that are required for a build, deploy, and test scenario.
ScriptDetailsStores details of a test run.

LabWorkflowDetails

The LabWorkflowDetails class contains the configuration data from the Lab Workflow Parameters wizard. In the LabDefaultTemplate, the LabWorkflowDetails object of a workflow is contained in the LabWorkflowParameters argument. The LabWorkflowDetails class contains the following properties:

BuildDetailsA BuildDetails object that is created by the workflow wizard and that stores the build details for a build, deploy, and test scenario.
DeploymentDetailsA LabEnvironmentDetails object that is created by the workflow wizard and that stores the information that is required for the deployment of a build in a build, deploy, and test scenario.
EnvironmentDetailsA LabEnvironmentDetails object that is created by the workflow wizard and that stores the information that identifies the environment to use for a build, deploy, and test scenario.
TestParametersA RunTestDetails object that is created by the workflow wizard and that stores the test parameter details that are required to create the automated test run.

BuildDetails

BuildDetails stores the build details for a build, deploy, and test scenario.

Properties

IsTeamSystemBuildA Boolean that indicates whether the build used is Team Build type.
BuildDefinitionUriA Uri that specifies the uri of the build definition.
BuildDefinitionNameA String that specifies the name of the build definition
QueueNewBuildA Boolean that indicates whether the new build has to be queued.
BuildUriA Uri that specifies the uri of the build, if the build is a Team Build type,
CustomBuildPathA String that specifies the path to the build, if the build is not a Team Build type.
Configuration

Back to top

DeploymentDetails

DeploymentDetails stores the test parameter details that are required to create the automated test run in the build, deploy, and test workflow. You can access the DeploymentDetails object that is created by the Lab Management wizard by using the DeploymentDetails property of the LabWorkflowParameters argument.

Properties

PostDeploymentSnapshotPathA String that contains the path to store post deployment snapshot.
PostDeploymentSnapshotNameA String that specifies the name of the snapshot taken after deployment.
TakePostDeploymentSnapshotA Boolean that specifies whether a post deployment snapshot is needed.
ScriptsA StringList object that contains a list of virtual machines with corresponding deployment scripts.
DeploymentNeededA Boolean that specifies whether deployment needs to be done.

Back to top

LabEnvironmentDetails

A LabEnvironmentDetails stores the information required to identify the lab environment in build, deploy and test scenario. You can access the LabEnvironmentDetails object that is created by the Lab Management workflow wizard by using the EnvironmentDetails property of theLabWorkflowParameters argument.

Properties

ProjectNameA String that specifies the name of the team project
LabEnvironmentNameA String that specifies the name of the lab environment
NewLabEnvironmentNameA String that specifies the name of the lab environment to create.
HostGroupNameA String that specifies the name of the host group where the environment is deployed.
LabLibraryShareNameA String that specifies the name of the library share that contains the stored lab environment template.
RevertToSnapshotA Boolean that indicates whether the environment should be rolled back to a snapshot.
SnapshotNameA String that specifies the name of the environment snapshot to roll back to.
TfsUrlA String that specifies the url of the Team Foundation Server.
LabEnvironmentUriA Uri that specifies the uri of the selected environment.
DispositionA LabEnvironmentDisposition enumerated value that indicates the status of the environment. The values are:

 Unknown - the status of the environment is not known.

 Active - the environment is deployed on a host and can be started and run.

 Stored - the environment is stored in a library share and cannot be used until it is deployed.

Back to top

RunTestDetails

RunTestDetails stores the test parameter details that are required to create the automated test run in the build, deploy, and test workflow. You can access the RunTestDetails object that is created by the Lab Management wizard by using the TestParameters property of the LabWorkflowParameters argument.

Properties

TfsUrlA String that specifies the URL of the Team Foundation Server.
Project nameA String that specifies the name of the team project.
TestConfigurationIdA Int32 that specifies the id of the test configuration for the test run.
TestPlanIdA Int32 that specifies the id of the test plan
TestSuiteIdListA Systems.Collections.Generic.List<int> that contains the numeric ids of the test suites to run
TestSettingsIdA Int32 that specifies the id of the test settings for the test run.
RunTestA Boolean that specifies whether to run the test.

Back to top

ScriptDetails

Provides details for deploy scripts. A ScriptDetails object is required when you add a RunDeploymentScript activity to the workflow designer. The InitializeAgentSpecAndEnvironmentVariables returns a ScriptDetails object.

Properties

LabSystemNameA String that specifies the name of the lab environment.
AgentSpecA AgentReservationSpec object that contains tags that are associated with a build agent in the lab system.
FileNameA String that specifies the name of the deployment script file.
ArgumentsA String that specifies the arguments to pass to the deployment script.
WorkingDirectoryA String that specifies the working directory for the deployment script on the lab system.
EnvironmentVariablesA System.Collection.Generic.IDictionary<String,String> that contains the environment variable name/value pairs.

Back to top

TestRunStatistics

Stores details of a test run. A TestRunStatistics object is returned by the ExecuteRemoteTestRun activity.

Properties

TotalTestsAn Int32 that specifies the total number of tests in the test run.
PassedTestsAn Int32 that specifies the number of tests that passed in the test run.
FailedTestsAn Int32 that specifies the number of tests that failed in the test run.
InconclusiveTestsAn Int32 that specifies the number of tests that were inconclusive in the test run.
PendingTestsAn Int32 that specifies the number of tests that have not yet run in the test run.
AbortedTestsAn Int32 that specifies the number of tests that were aborted in the test run.
InProgressTestsAn Int32 that specifies the number of tests that have are currently running in the test run.
TestRunStatusA TestRunState enumerated value that specifies the status of the test run.
TestRunIdAn Int32 that specifies the identifier of the test run.

Back to top

LabEnvironmentInUseMarker

Stores details of the In Use marker of an environment. Use the GetLabEnvironmentInUseMarker activity to return a LabEnvironmentInUseMarker object.

Properties

UserA String that specifies the user who marked the environment.
TimestampA DateTime that specifies time that the user marked the environment.
CommentA String that is specified by the user who marked the environment.

Back to top

LabEnvironmentState

An enumeration that specifies the current state of the environment. The state of a lab environment is mostly determined by the states of the virtual machines it contains. If all the virtual machines are in a consistent stable state, the LabEnvironmentState value matches that state. Otherwise, the value is Mixed or Failed. When an operation is in progress on the environment, the lab environment is in a transitioning state, which indicates the ongoing operation.

LabEnvironmentState has the following values:

Unknown

Creating

CreateFailed

CreateCancelling

Updating

Stored

Starting

Running

Pausing

Paused

Stopping

Stopped

CreatingSnapshot

DeletingSnapshot

RestoringSnapshot

Deleting

DeleteFailed

Deleted

Mixed

Failed

UnderMigration

LabDefaultTemplate workflow activities

Show: