New-PSWorkflowExecutionOption

Article
02/22/2012

New-PSWorkflowExecutionOption

Creates an object that contains session configuration options for workflow sessions.

Syntax

Parameter Set: Default
New-PSWorkflowExecutionOption [-ActivityProcessIdleTimeoutSec <Int32> ] [-AllowedActivity <String[]> ] [-EnableValidation <Boolean> ] [-MaxActivityProcesses <Int32> ] [-MaxConnectedSessions <Int32> ] [-MaxDisconnectedSessions <Int32> ] [-MaxPersistenceStoreSizeGB <Int64> ] [-MaxRunningWorkflows <Int32> ] [-MaxSessionsPerRemoteNode <Int32> ] [-MaxSessionsPerWorkflow <Int32> ] [-OutOfProcessActivity <String[]> ] [-PersistencePath <String> ] [-PersistWithEncryption <Boolean> ] [-RemoteNodeSessionIdleTimeoutSec <Int32> ] [-SessionThrottleLimit <Int32> ] [-WorkflowApplicationPersistUnloadTimeoutSec <Int32> ] [-WorkflowShutdownTimeoutMSec <Int32> ] [ <CommonParameters>]

Detailed Description

The New-PSWorkflowExecutionOption cmdlet creates an object that contains advanced options for session configurations (also known as "endpoints"). These options are designed especially for session configurations that are used to run workflows.

You can use the PSWorkflowExecutionOption object that New-PSWorkflowExecutionOption generates as the value of the SessionTypeOption parameter of cmdlets that create or change a session configuration, such as the Register-PSSessionConfiguration and Set-PSSessionConfiguration cmdlets.

By default, session configurations do not have these options and they are not applied to sessions that use the session configuration.

The New-PSWorkflowExecutionOption cmdlet is part of the Windows PowerShell Workflow feature.

This cmdlet is introduced in Windows PowerShell 3.0.

Parameters

-ActivityProcessIdleTimeoutSec<Int32>

Determines how long each activity host process is maintained when the process is idle. When the interval expires, the session closes.

Enter a value in seconds. The default value is 60.

Aliases	none
Required?	false
Position?	named
Default Value	60
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-AllowedActivity<String[]>

Specifies the activities that are permitted to run in the session.

Enter the activity name. The default value is PSDefaultActivities, which includes the built-in Windows Workflow Foundation activities and the activities that represent the Windows PowerShell Core cmdlets.

Aliases	none
Required?	false
Position?	named
Default Value	PSDefaultActivities
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-EnableValidation<Boolean>

Enables validation of all workflow activities in the session. The default value is True.

Aliases	none
Required?	false
Position?	named
Default Value	True
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxActivityProcesses<Int32>

Specifies the maximum number of processes that can be created in the session to support workflow activities. The default value is 5.

Aliases	none
Required?	false
Position?	named
Default Value	5
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxConnectedSessions<Int32>

Specifies the maximum number of sessions that are connected to a managed node and are in an operational state. The default value is 100.

Aliases	none
Required?	false
Position?	named
Default Value	100
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxDisconnectedSessions<Int32>

Specifies the maximum number of sessions that are connected to a managed node and are in a disconnected state. The default value is 1000.

Aliases	none
Required?	false
Position?	named
Default Value	1000
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxPersistenceStoreSizeGB<Int64>

Specifies the maximum size, in gigabytes, of the persistence store available to workflows that run in this session. The default value is 10.

The persistence store contains data for workflow jobs that are suspended. The ability to store data allows the jobs to resume without losing state.

Aliases	none
Required?	false
Position?	named
Default Value	10
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxRunningWorkflows<Int32>

Specifies that maximum number of workflows that can run in the session concurrently. The default value is 30.

Aliases	none
Required?	false
Position?	named
Default Value	30
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxSessionsPerRemoteNode<Int32>

Specifies the maximum number of sessions that can be connected to each managed node. The default value is 5

Aliases	none
Required?	false
Position?	named
Default Value	5
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-MaxSessionsPerWorkflow<Int32>

Specifies the maximum number of session that can be created to support each workflow. The default value is 5.

Aliases	none
Required?	false
Position?	named
Default Value	5
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-OutOfProcessActivity<String[]>

Specifies the out-of-process activities that are permitted in the session. The default value is InlineScript.

Aliases	none
Required?	false
Position?	named
Default Value	InlineScript
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PersistencePath<String>

Specifies the location on disk where workflows that are running in the session are stored. Storing the workflows allows workflows to be suspended and resumed without losing state.

The default value is $env:LocalAppData\Microsoft\Windows\PowerShell\WF\PS

Aliases	none
Required?	false
Position?	named
Default Value	$env:LocalAppData\Microsoft\Windows\PowerShell\WF\PS
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-PersistWithEncryption<Boolean>

Encrypts the data in the persistence store for this session. The default value is False.

Aliases	none
Required?	false
Position?	named
Default Value	False
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-RemoteNodeSessionIdleTimeoutSec<Int32>

Specifies how long a session that is connected to a managed node is maintained if it is idle.

Enter a value in seconds. The default value is 60.

Aliases	none
Required?	false
Position?	named
Default Value	60
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-SessionThrottleLimit<Int32>

Specifies how many workflows can run concurrently in the session. When the specified value is exceeded, newly invoked workflows are saved in a queue. The default value is 100.

Aliases	none
Required?	false
Position?	named
Default Value	100
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-WorkflowApplicationPersistUnloadTimeoutSec<Int32>

Specifies how long Windows PowerShell waits for an application in persistent storage to close. When the timeout expires, Windows PowerShell closes the application forcibly.

Enter a value in seconds. The default value is 5.

Aliases	none
Required?	false
Position?	named
Default Value	5
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

-WorkflowShutdownTimeoutMSec<Int32>

Specifies how long Windows PowerShell waits a workflow to end. When the timeout expires, Windows PowerShell closes the workflow forcibly.

Enter a value in milliseconds. The default value is 500.

Aliases	none
Required?	false
Position?	named
Default Value	500
Accept Pipeline Input?	false
Accept Wildcard Characters?	false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

None

You cannot pipe input to this cmdlet.

Outputs

The output type is the type of the objects that the cmdlet emits.

Microsoft.PowerShell.Commands.PSWorkflowExecutionOption

Notes

When the maximum value set by an option is exceeded, the command to create another instance in the session fails, unless noted in the parameter description. For example, if the value of MaxConnectedSessions is 100. The command to create the 101st session to a managed node fails.
The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties.

In particular, the properties of session configurations ("endpoints") that include a PSWorkflowExecutionOptions object vary based on the workflow option values. For example, if the session configuration includes a PSWorkflowExecutionOptions object that sets a non-default value for the SessionThrottleLimit property, the session configuration has a SessionThrottleLimit property. Otherwise, it does not.

Examples

Example 1: Create a Workflow Options Object

This command uses the New-PSWorkflowExecutionOption cmdlet to increase the MaxSessionsPerWorkflow value to 10 and decrease the MaxDisconnectedSessions value to 200.

The output shows the object that the cmdlet returns.

PS C:\> New-PSWorkflowExecutionOption -MaxSessionsPerWorkflow 10 -MaxDisconnectedSessions 200

SessionThrottleLimit                       : 100
PersistencePath                            : C:\Users\User01\AppData\Local\Microsoft\Windows\PowerShell\WF\PS
MaxPersistenceStoreSizeGB                  : 10
PersistWithEncryption                      : False
MaxRunningWorkflows                        : 30
AllowedActivity                            : {PSDefaultActivities}
OutOfProcessActivity                       : {InlineScript}
EnableValidation                           : True
MaxDisconnectedSessions                    : 200
MaxConnectedSessions                       : 100
MaxSessionsPerWorkflow                     : 10
MaxSessionsPerRemoteNode                   : 5
MaxActivityProcesses                       : 5
WorkflowApplicationPersistUnloadTimeoutSec : 5
ActivityProcessIdleTimeoutSec              : 60
RemoteNodeSessionIdleTimeoutSec            : 60
WorkflowShutdownTimeoutMSec                : 500

Example 2: Using a Workflow Options Object

This example shows how to use a workflow options object to establish or change the workflow options in a session configuration.

The first command uses the New-PSWorkflowExecutionOption cmdlet to create a workflow options object. The command saves the object in the $wo variable.

PS C:\> $wo = New-PSWorkflowExecutionOption -MaxSessionsPerWorkflow 10 -MaxDisconnectedSessions 200

The second command uses the Register-PSSessionConfiguration cmdlet to create the ITWorkflows session configuration. To set the workflow options in the session configuration, the command uses the SessionTypeOption parameter. The value of the SessionTypeOption parameter is the workflow options object in the $wo variable. The command also uses the Force parameter to suppress confirmations prompts.

PS C:\> Register-PSSessionConfiguration -Name ITWorkflows -SessionTypeOption $wo -Force

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin

Type            Keys                                Name
----            ----                                ----
Container       {Name=ITWorkflows}                  ITWorkflows

The third command shows the workflow options in the session configuration. The command uses the Get-PSSessionConfiguration cmdlet to the get the ITWorkflows session configuration and the Format-List to display all properties of the session configuration in a list.

The output shows that the workflow options in the session configuration. Specifically, the session configuration has a MaxSessionsPerWorkflow property with a value of 10 and a MaxDisconnectedSessions property with a value of 200.

PS C:\> Get-PSSessionConfiguration ITWorkflows | Format-List -Property *

Architecture                  : 64
Filename                      : %windir%\system32\pwrshplugin.dll
ResourceUri                   : https://schemas.microsoft.com/powershell/ITWorkflows
MaxConcurrentCommandsPerShell : 1000
allowedactivity               : PSDefaultActivities
SharedHost                    : false
HostIdleTimeoutSeconds        : 0
xmlns                         : https://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
MaxConcurrentUsers            : 5
maxsessionsperworkflow        : 10
lang                          : en-US
sessionconfigurationdata      : <SessionConfigurationData><Param Name='PrivateData'><PrivateData><Param
                                Name='enablevalidation' Value='True' /><Param Name='allowedactivity'
                                Value='PSDefaultActivities' /><Param Name='outofprocessactivity' Value='InlineScript'
                                /><Param Name='maxdisconnectedsessions' Value='200' /><Param
                                Name='maxsessionsperworkflow' Value='10'
                                /></PrivateData></Param></SessionConfigurationData>
SupportsOptions               : true
ExactMatch                    : true
RunAsUser                     :
IdleTimeoutms                 : 7200000
PSVersion                     : 3.0
ServerBufferingMode           : Block
AutoRestart                   : false
MaxShells                     : 25
MaxMemoryPerShellMB           : 1024
MaxIdleTimeoutms              : 43200000
outofprocessactivity          : InlineScript
SDKVersion                    : 2
Name                          : ITWorkflows
XmlRenderingType              : text
Capability                    : {Shell}
RunAsPassword                 :
MaxProcessesPerShell          : 15
enablevalidation              : True
Enabled                       : True
maxdisconnectedsessions       : 200
MaxShellsPerUser              : 25
Permission                    :

New-PSWorkflowExecutionOption