Share via


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 Ultimate, Visual Studio Premium, Visual Studio Test Professional

This topic contains the following sections:

  1. Lab Management Activities

  2. Lab Management Classes

Lab Management Activities

The following table describes the individual Lab Management workflow activities.

Activity

Description

CreateLabEnvironment

Creates a new environment from a stored template and deploys it on the specified host group.

DeleteLabEnvironment

Deletes an environment.

DeleteSnapshot

Deletes a snapshot of an environment.

ExecuteRemoteTestRun

Creates a test run on an environment and waits for it to finish.

GenerateEnvironmentViewerFile

Generates an environment viewer file that has snapshot link ID. It is used to connect to a snapshot of the environment.

GetBuildLocationAndBuildNumber

Returns the build location and build number for a build, deploy, and test scenario.

GetLabEnvironmentInUseMarker

Returns the In Use marker for an environment.

GetLabEnvironmentSnapshotId

Gets the ID of a snapshot of an environment.

GetLabEnvironmentStatus

Gets the environment status.

GetLabEnvironmentUri

Gets the environment URI for a given environment name and lab location name.

InitializeAgentSpecAndEnvironmentVariables

Parses the deploy script details specified by property

ResetLabEnvironmentInuseMarker

Resets the In Use marker for an environment.

RestoreLabEnvironment

Restores the environment to the specified snapshot.

RunDeploymentScript

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

RunWorkflow

Queues a new workflow on a build controller of a build server.

SaveLabEnvironment

Creates a new environment and stores it in a team project library share.

SetLabEnvironmentInuseMarker

Sets the In Use marker on environment.

SnapshotLabEnvironment

Takes a snapshot of an environment.

StartLabEnvironment

Starts the environment.

StopLabEnvironment

Stops the environment.

WaitForTestCapabilityServices

Waits 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.

WaitForWorkflow

Type of workflow.

WaitForWorkflowCapabilityServices

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, 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.

WriteDeploymentInformation

Writes 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

LabEnvironmentName

Name of the new environment. If this property is null or empty, the environment template name will be used.

LabEnvironmentTemplateUri

URI of a stored environment template. The lab environment template URI can be obtained by using GetLabEnvironmentUri activity. Required.

TeamProjectHostGroupName

Host 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

LabEnvironmentUri

URI 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

LabEnvironmentUri

URI of the lab environment whose snapshot will be deleted. The lab environment URI can be obtained by using GetLabEnvironmentUri activity. Required.

SnapshotId

ID 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

BuildNumber

Build number on which tests are run.

LabEnvironmentUri

URI of the environment on which test cases will be executed. The environment URI can be obtained by using the GetLabEnvironmentUri activity.

MaxConsecutiveFailuresToIgnoreDuringWaitForCompletion

Maximum 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.

MaxWaitTime

A 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.

RefreshInterval

A TimeSpan that specifies the interval after which the status of the test run is refreshed. The default value of this interval is 60 seconds.

TestDirectory

Path to the test executables.

TestEnvironment

Name of the test environment on which test cases will be executed.

TestParameters

A Microsoft.TeamFoundation.Lab.Workflow.Activities.RunTestDetails object that specifies test parameters such as the test plan, the test suite, the test settings, and the test configuration. Required.

Title

Name 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

FilePath

UNC path of where to store the environment viewer file. The build service account must have write permission for the path. Required.

LabEnvironmentUri

URI of the environment. The environment URI can be obtained by using the GetLabEnvironmentUri activity. Required.

SnapshotId

ID 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

BuildDetails

A Microsoft.TeamFoundation.Lab.Workflow.Activities.BuildDetails object that contains build-related information in build, deploy, and test scenario.

BuildNumber

Build number of the selected build. This is an outArgument. This is null for non "team build" builds.

SelectedBuild

Build 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

LabEnvironmentUri

URI 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

LabEnvironmentUri

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

SnapshotName

Snapshot 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

LabEnvironmentUri

URI 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

LabEnvironmentName

Environment name. Required.

ProjectName

Name of the team project. If this property value is null or is not specified, the current project of the build is used.

TeamProjectLabLocationName

Lab 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

BuildLocation

Build location path. This is used to expand the macro $(BuildLocation). Required.

DeploymentScriptDetails

Deployment details in the format " labsystemname | script arguments | working directory". Required.

LabEnvironmentUri

URI 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

LabEnvironmentUri

URI 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

LabEnvironmentUri

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

SnapshotId

ID 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

MaximumAttemptsForNetUse

Maximum number of attempts to add net use.

ScriptDetails

A Script Details object for a lab system. Required.

SharedLocationForNetUse

Location that should be accessible by the lab service account.

ThrowOnError

Flag 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

BuildController

Build 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.

BuildDefinition

Build definition to be queued. Required.

LabEnvironmentUri

URI of environment with workflow capabilities. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

ProjectName

Name 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

LabEnvironmentName

Name for saved environment. If this property is null or is empty, the environment name will be used.

LabEnvironmentUri

URI of the environment to be saved. Use the GetLabEnvironmentUri activity to get the URI of the environment. Required.

TeamProjectLibraryShareName

Library 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

Comment

Comment written when the marker is set.

LabEnvironmentUri

URI 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

LabEnvironmentUri

URI of environment whose snapshot has to be taken. Use the GetLabEnvironmentUri activity to get the environment URI. Required.

SnapshotChainId

Returns the snapshot chain ID.

SnapshotName

Name 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

LabEnvironmentUri

URI 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

LabEnvironmentUri

URI 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

LabEnvironmentUri

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

MaxWaitTime

A 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.

RepairCapabilityBeforeWaitBegins

If 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 BuildStatus enumerated value that indicates the status of the workflow.

Properties

AllowPartiallySucceededBuild

If true, partially succeeded is treated as success.

BuildDetails

A Microsoft.TeamFoundation.Build.Client.IBuildDetail object that contains queued build details on the build server. This is an out argument.

LabWorkflowType

The type of workflow.

MaxConsecutiveFailuresToIgnoreDuringWaitForCompletion

Maximum 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.

MaxWaitTime

A 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.

QueueBuildId

The ID of the queued build. Required.

RefreshInterval

A 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.

ThrowOnError

If 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

LabEnvironmentUri

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

MaxWaitTime

A 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.

RepairCapabilityBeforeWaitBegins

If this value is true, an attempt to repair the capability will be done before waiting.

WaitForComputerNames

If 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

Message

Message to be displayed in the summary. Required.

Url

Optional URL or link to add to the message.

DeploymentInformationType

Specifies the subsection of the deployment information for this information message. Use one of the following values:

  • Build

  • Deploy

  • Test

Back to top

Lab Management Classes

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.

Object

Description

LabWorkflowDetails

The LabWorkflowDetails class contains the configuration data from the Lab Workflow Parameters wizard. The LabWorkflowDetails object contains BuildDetails, RunTestDetails, and ScriptDetails objects.

BuildDetails

Stores the build details for a build, deploy, and test scenario.

DeploymentDetails

Stores the test parameter details that are required to create the automated test run in the build, deploy, and test workflow

LabEnvironmentDetails

Stores the information required to identify the lab environment in build, deploy and test scenario

LabEnvironmentInUseMarker

Stores details of the In Use marker of an environment.

LabEnvironmentState

Specifies the current state of the environment.

RunTestDetails

Stores the test parameter details that are required to create the automated test run.

ScriptDetails

Stores the deployment script details that are required for a build, deploy, and test scenario.

TestRunStatistics

Stores 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 theLabWorkflowParameters argument. The LabWorkflowDetails class contains the following properties:

BuildDetails

A Microsoft.TeamFoundation.Lab.Workflow.Activities.BuildDetails object that is created by the workflow wizard and that stores the build details for a build, deploy, and test scenario.

DeploymentDetails

A Microsoft.TeamFoundation.Lab.Workflow.Activities.DeploymentDetails 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.

EnvironmentDetails

A Microsoft.TeamFoundation.Lab.Workflow.Activities.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.

TestParameters

A Microsoft.TeamFoundation.Lab.Workflow.Activities.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

IsTeamSystemBuild

A Boolean that indicates whether the build used is Team Build type.

BuildDefinitionUri

A Uri that specifies the uri of the build definition.

BuildDefinitionName

A String that specifies the name of the build definition

QueueNewBuild

A Boolean that indicates whether the new build has to be queued.

BuildUri

A Uri that specifies the uri of the build, if the build is a Team Build type,

CustomBuildPath

A 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 argument.

Properties

PostDeploymentSnapshotPath

A String that contains the path to store post deployment snapshot.

PostDeploymentSnapshotName

A String that specifies the name of the snapshot taken after deployment.

TakePostDeploymentSnapshot

A Boolean that specifies whether a post deployment snapshot is needed.

Scripts

A StringList object that contains a list of virtual machines with corresponding deployment scripts.

DeploymentNeeded

A 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 the LabWorkflowParameters Argument argument.

Properties

ProjectName

A String that specifies the name of the team project

LabEnvironmentName

A String that specifies the name of the lab environment

NewLabEnvironmentName

A String that specifies the name of the lab environment to create.

HostGroupName

A String that specifies the name of the host group where the environment is deployed.

LabLibraryShareName

A String that specifies the name of the library share that contains the stored lab environment template.

RevertToSnapshot

A Boolean that indicates whether the environment should be rolled back to a snapshot.

SnapshotName

A String that specifies the name of the environment snapshot to roll back to.

TfsUrl

A String that specifies the url of the Team Foundation Server.

LabEnvironmentUri

A Uri that specifies the uri of the selected environment.

Disposition

A 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 argument.

Properties

TfsUrl

A String that specifies the URL of the Team Foundation Server.

Project name

A String that specifies the name of the team project.

TestConfigurationId

A Int32 that specifies the id of the test configuration for the test run.

TestPlanId

A Int32 that specifies the id of the test plan

TestSuiteIdList

A Systems.Collections.Generic.List<int> that contains the numeric ids of the test suites to run

TestSettingsId

A Int32 that specifies the id of the test settings for the test run.

RunTest

A 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

LabSystemName

A String that specifies the name of the lab environment.

AgentSpec

A AgentReservationSpec object that contains tags that are associated with a build agent in the lab system.

FileName

A String that specifies the name of the deployment script file.

Arguments

A String that specifies the arguments to pass to the deployment script.

WorkingDirectory

A String that specifies the working directory for the deployment script on the lab system.

EnvironmentVariables

A 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

TotalTests

An Int32 that specifies the total number of tests in the test run.

PassedTests

An Int32 that specifies the number of tests that passed in the test run.

FailedTests

An Int32 that specifies the number of tests that failed in the test run.

InconclusiveTests

An Int32 that specifies the number of tests that were inconclusive in the test run.

PendingTests

An Int32 that specifies the number of tests that have not yet run in the test run.

AbortedTests

An Int32 that specifies the number of tests that were aborted in the test run.

InProgressTests

An Int32 that specifies the number of tests that have are currently running in the test run.

TestRunStatus

A TestRunState enumerated value that specifies the status of the test run.

TestRunId

An 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

User

A String that specifies the user who marked the environment.

Timestamp

A DateTime that specifies time that the user marked the environment.

Comment

A 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

See Also

Concepts

LabDefaultTemplate Workflow Activities