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:
Lab Management Activities
The following table describes the individual Lab Management workflow activities.
Activity |
Description |
|---|---|
Creates a new environment from a stored template and deploys it on the specified host group. |
|
Deletes an environment. |
|
Deletes a snapshot of an environment. |
|
Creates a test run on an environment and waits for it to finish. |
|
Generates an environment viewer file that has snapshot link ID. It is used to connect to a snapshot of the environment. |
|
Returns the build location and build number for a build, deploy, and test scenario. |
|
Returns the In Use marker for an environment. |
|
Gets the ID of a snapshot of an environment. |
|
Gets the environment status. |
|
Gets the environment URI for a given environment name and lab location name. |
|
Parses the deploy script details specified by property |
|
Resets the In Use marker for an environment. |
|
Restores the environment to the specified snapshot. |
|
Runs the deployment script. On failure, throws or writes a build warning as specified in the ThrowOnError property. |
|
Queues a new workflow on a build controller of a build server. |
|
Creates a new environment and stores it in a team project library share. |
|
Sets the In Use marker on environment. |
|
Takes a snapshot of an environment. |
|
Starts the environment. |
|
Stops the environment. |
|
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. |
|
Type of workflow. |
|
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. |
|
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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:
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.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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:
|
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 |
|---|---|
The LabWorkflowDetails class contains the configuration data from the Lab Workflow Parameters wizard. The LabWorkflowDetails object contains BuildDetails, RunTestDetails, and ScriptDetails objects. |
|
Stores the build details for a build, deploy, and test scenario. |
|
Stores the test parameter details that are required to create the automated test run in the build, deploy, and test workflow |
|
Stores the information required to identify the lab environment in build, deploy and test scenario |
|
Stores details of the In Use marker of an environment. |
|
Specifies the current state of the environment. |
|
Stores the test parameter details that are required to create the automated test run. |
|
Stores the deployment script details that are required for a build, deploy, and test scenario. |
|
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 the LabWorkflowParameters 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 |
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
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. |
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
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. |
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
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. |
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. |
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. |
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. |
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