Appendix
Applies To: Windows 8 Release Preview, Windows Server 2012
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
In this Appendix
The following supplementary information can help you author and run workflows in Windows PowerShell.
Reserved parameter names
The following are reserved parameter names that cannot be inside either Windows PowerShell script-based workflows, or workflow XAML files.
Reserved Parameter Name | Description |
---|---|
PSParameterCollection |
List of hash tables to specify different parameter values for different target computers. |
PSComputerName |
List of computers on which the workflow will be run. |
PSCredential |
Credential to use for workflow session to target computers. |
PSPort |
Specifies the network port on the remote computer that is used for this connection. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). |
PSUseSSL |
Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. |
PSConfigurationName |
Specifies the session configuration that is used for the connection to target computer. If the specified session configuration does not exist on the target computer, the command fails. The default value is Microsoft.PowerShell. |
PSApplicationName |
Specifies the application name segment of the connection URI for connection to target computer. The default value is WSMAN. This value is appropriate for most uses |
PSThrottleLimit |
|
PSConnectionURI |
Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the session. The URI must be fully qualified. The format of this string is as follows: <Transport>://<ComputerName>:<Port>/<ApplicationName> The default value is: https://localhost:5985/WSMAN. |
PSAllowRedirection |
Allows redirection of this connection to an alternate URI. The target computer can return an instruction to redirect to a different URI. By default, Windows PowerShell Workflow does not redirect connections, but you can use this parameter to allow it to redirect the connection. |
PSSessionOption |
Sets advanced options for the connection to target computer. Enter a SessionOption object that you create by using the New-PSSessionOption cmdlet. |
PSAuthentication |
Specifies the mechanism that is used to authenticate the user's credentials. Valid values are Default, Basic, Credssp, Digest, Kerberos, Negotiate, and NegotiateWithImplicitCredential. The default value is Default. |
PSAuthenticationLevel |
Specifies the authentication level to use for the WMI connection. Valid values are: Unchanged, Default, None, Connect, Call, Packet, PacketIntegrity, and PacketPrivacy. |
PSCertificateThumbprint |
Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. |
PSConnectionRetryCount |
Number of times workflow should try reconnecting to target computers when there are problems establishing a connection. |
PSActionRetryCount |
|
PSConnectionRetryIntervalSec |
Number of seconds to wait between each successive connection retry. |
PSActionRetryInterval |
|
PSMaxRunningTime |
|
PSMaxElapsedTime |
|
PSMaxIdleTimeout |
|
AsJob |
Runs the workflow as a background job on the local computer. Use this parameter to run workflows that take an extended time to complete. When you use AsJob, the command returns an object that represents the job, and then displays the command prompt. To manage the job, use the Job cmdlets. To get the job results, use Receive-Job. |
PSOutputPath |
|
PSAutoCheckpointing |
|
PSPrivateMetadata |
Hashtable object that represents user/application level information that can later be used to identify/filter the workflow. |
Verbose |
|
Debug |
|
ErrorAction |
|
ErrorVariable |
|
WarningVariable |
|
Input |
|
Results |
|
PSRunningTimeoutSec |
Number of seconds the workflow has to run. If it takes longer, the workflow is stopped and all workflow data is removed. This timeout does not include the time period when the workflow is in suspended state. |
PSElapsedTimeoutSec |
Number of seconds the workflow has to run. If it takes longer, the workflow is stopped and all workflow data is removed. This timeout does include the time period when the workflow is in suspended state. |
PSPersist |
Forces the workflow to checkpoint the workflow data and state after each performing each step (activity) within the workflow. |
PSRunningTimeoutSec |
Number of seconds the workflow has to run. If it takes longer, the workflow is stopped and all workflow data is removed. This timeout does not include the time period when the workflow is in suspended state. |
PSElapsedTimeoutSec |
Number of seconds the workflow has to run. If it takes longer, the workflow is stopped and all workflow data is removed. This timeout does include the time period when the workflow is in suspended state. |
PSPersist |
Forces the workflow to checkpoint the workflow data and state when used after a step (activity) within the workflow or after every activity when used at workflow run time (when the workflow is invoked at the command-line). |
List of non-supported Windows Workflow Foundation activities
Windows PowerShell Workflow supports most of the built-in Windows Workflow Foundation activities. For a complete list of built-in Windows Workflow Foundation activities, see the .NET Framework 4 Built-In Activity Library (https://go.microsoft.com/fwlink/?LinkId=251933).
The following is the small subset of Windows Workflow Foundation activities that Windows PowerShell workflows do not support. These activities are excluded because they typically require host level support such as WCF messaging or transactions that are not supported by the Windows PowerShell Workflow runtime.
Activity Category | Activity Names |
---|---|
Flow control |
Pick PickBranch |
Messaging |
Send SendReply Receive ReceiveReply |
Transaction |
CancellationScope CompensableActivity Compensate Confirm TransactionScope TransactionReceiveScope |
Migration |
Interop |
List of cmdlets that can only run locally
Windows PowerShell Workflow inherently supports running cmdlet actions remotely, however, there is a set of utility and object manipulation cmdlets that is always invoked locally. This is done to improve performance. These cmdlets can be remotely run using the InlineScript activity. For more information, see Running isolated blocks of Windows PowerShell script.
Cmdlets that always run locally in a workflow | |
---|---|
Add-Member |
New-PSSessionOption |
Compare-Object |
New-PSTransportOption |
ConvertFrom-Csv |
New-TimeSpan |
ConvertFrom-Json |
Out-Default |
ConvertFrom-StringData |
Out-Host |
Convert-Path |
Out-Null |
ConvertTo-Csv |
Out-String |
ConvertTo-Html |
Select-Object |
ConvertTo-Json |
Sort-Object |
ConvertTo-Xml |
Update-List |
ForEach-Object |
Where-Object |
Get-Host |
Write-Debug |
Get-Member |
Write-Error |
Get-Random |
Write-Host |
Get-Unique |
Write-Output |
Group-Object |
Write-Progress |
Measure-Command |
Write-Verbose |
Measure-Object |
Write-Warning |
Cmdlets that do not implement activities
Windows PowerShell workflows include corresponding activities for most of the default cmdlets however there is a small set of cmdlets for which it does not make sense. These cmdlets are listed in the following table. To invoke the following cmdlets in a workflow, you have to wrap them in InlineScript. For more information, see Running isolated blocks of Windows PowerShell script.
Reason | Cmdlet Names |
---|---|
Only changes Windows PowerShell session; does not work across activities in workflow (each step in the workflow is isolated) |
|
No interactive support from workflow |
|
No Windows PowerShell script debugging support via workflow |
|
No Windows PowerShell transaction support via workflow |
|
No formatting support via workflow |
|
Workflow does its own remoting |
|
Other |
|
Windows PowerShell workflow endpoint
Apart from the default remoting endpoint (Microsoft.PowerShell), Windows PowerShell ships with a workflow endpoint: Microsoft.PowerShell.Workflow. Unlike the default Windows PowerShell remoting endpoint, the Windows PowerShell Workflow endpoint runs with -UseSharedProcess set to true. This setting allows the user to connect to the Windows PowerShell Workflow endpoint from different PSSessions and still connect to the same process running on the server machine.
Creating a session to the workflow endpoint ensures that the Windows PowerShell Workflow functionality is loaded.
Get-PSSessionConfiguration –Name *Workflow
Additionally, the Windows PowerShell Workflow endpoint has a very limited set of commands that are necessary for running and managing the workflow.
Invoke-Command -ComputerName . –ConfigurationName Microsoft.PowerShell.Workflow -ScriptBlock {get-command}
Creating a session to the default workflow endpoint
Creating a connection to the Windows PowerShell Workflow endpoint is as easy as calling New-PSWorkflowSession. This command has all the remoting related parameters that allows you to connect to remote Windows PowerShell Workflow sessions. Alternatively, one can use the full configuration name –Microsoft.PowerShell.Workflow with the New-PSSession cmdlet as well.
$wfsession = New-PSWorkflowSession
$wfsession2 = New-PSSession -ConfigurationName Microsoft.PowerShell.Workflow
Creating a custom workflow endpoint
Creating a custom Windows PowerShell Workflow endpoint is the same as creating a new Windows PowerShell remoting endpoint: you can still use the Register/Set-PSSessionConfiguration cmdlets for this purpose. You will notice that among other new parameters, these cmdlets have -SessionType and -SessionTypeOption parameters. The SessionType parameter lets you specify the type of endpoint you want to create. The SessionTypeOption parameter takes an object for specifying additional options for the endpoint. For workflow-type endpoints, you can specify the various workflow related quotas (such as number of running workflows, allowed workflow activities, and list of activities that run in-process.) via the object produced by the New-PSWorkflowExecutionOption cmdlet.