PowerShell Logo Small

about_ActivityCommonParameters



This is the built-in help made by Microsoft for the document 'about_ActivityCommonParameters', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-24.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

Search powershellhelp.space

TOPIC
about_ActivityCommonParameters

SHORT DESCRIPTION
Describes the parameters that Windows PowerShell
Workflow adds to activities.

LONG DESCRIPTION
Windows PowerShell Workflow adds the activity common
parameters to activities that are derived from the
PSActivity base class. This category includes the
InlineScript activity and Windows PowerShell cmdlets
that are implemented as activities, such as Get-Process
and Get-WinEvent.

The activity common parameters are not valid on the
Suspend-Workflow and Checkpoint-Workflow activities
and they are not added to cmdlets or expressions that
Windows PowerShell Workflow automatically runs in an
InlineScript script block or similar activity. The
activity common parameters are available on the
InlineScript activity, but not on commands in the
InlineScript script block.

Several of the activity common parameters are also
workflow common parameters or Windows PowerShell
common parameters. Other activity common parameters
are unique to activities.

For information about the workflow common parameters,
see about_WorkflowCommonParameters. For information
about the Windows PowerShell common parameters, see
about_CommonParameters.


LIST OF ACTIVITY COMMON PARAMETERS

AppendOutput PSDebug
Debug PSDisableSerialization
DisplayName PSError
ErrorAction PSPersist
Input PSPort
MergeErrorToOutput PSProgress
PSActionRetryCount PSProgressMessage
PSActionRetryIntervalSec PSRemotingBehavior
PSActionRunningTimeoutSec PSRequiredModules
PSApplicationName PSSessionOption
PSAuthentication PSUseSSL
PSCertificateThumbprint PSVerbose
PSComputerName PSWarning
PSConfigurationName Result
PSConnectionRetryCount UseDefaultInput
PSConnectionRetryIntervalSec Verbose
PSConnectionURI WarningAction
PSCredential


PARAMETER DESCRIPTIONS
This section describes the activity common parameters.

-AppendOutput <Boolean>
A value of $True adds the output of the activity to the value of
the variable. A value of $False has no effect. By default, assigning
a value to a variable replaces the variable value.

For example, the following commands add a process object to the
service object in the $x variable.

workflow Test-Workflow
{
$x = Get-Service
$x = Get-Process -AppendOutput $true
}

This parameter is designed for XAML-based workflows. In script
workflows, you can also use the += assignment operator to add
output to the value of a variable, as shown in the following
example.

workflow Test-Workflow
{
$x = Get-Service
$x += Get-Process
}

-Debug <SwitchParameter>
Displays programmer-level detail about the operation
performed by the command. The Debug parameter
overrides the value of the $DebugPreference variable
for the current command. This parameter works only
when the command generates debugging messages. This
parameter is also a Windows PowerShell common parameter.


-DisplayName <String>
Specifies a friendly name for the activity. The
DisplayName value appears in the progress bar while
the workflow runs and in the value of the Progress
property of the workflow job. When the PSProgressMessage
parameter is also included in the command, the progress
bar content appears in <DisplayName>:<PSProgressMessage>
format.


-ErrorAction <ActionPreference>
Determines how the activity responds to a non-terminating
error from the command. It has no effect on termination
errors. This parameter works only when the command
generates a non-terminating error, such as those from the
Write-Error cmdlet. The ErrorAction parameter overrides
the value of the $ErrorActionPreference variable for the
current command. This parameter is also a Windows PowerShell
common parameter.


Valid values:
Continue. Displays the error message and continues
executing the command. "Continue" is the default value.

Ignore. Suppresses the error message and continues


executing the command. Unlike SilentlyContinue, Ignore
does not add the error message to the $Error automatic
variable. The Ignore value is introduced in Windows
PowerShell 3.0.

Inquire. Displays the error message and prompts you for
confirmation before continuing execution. This value is
rarely used.

Suspend. Automatically suspends a workflow job to allow for further
investigation. After investigation, the workflow can be resumed.

SilentlyContinue. Suppresses the error message and
continues executing the command.

Stop. Displays the error message and stops executing
the command.


-Input <Object[]>
Submits a collection of objects to an activity. This is an
alternative to piping objects to the activity one at a time.


-MergeErrorToOutput <Boolean>
A value of $True adds errors to the output stream. A value of
$False has not effect. Use this parameter with the Parallel and
ForEach -Parallel keywords to collect errors and output from
multiple parallel commands in a single collection.


-PSActionRetryCount <Int32>
Tries repeatedly to run the activity if the first attempt
fails. The default value, 0, does not retry.


-PSActionRetryIntervalSec <Int32>
Determines the interval between action retries in seconds.
The default value, 0, retries the action immediately. This
parameter is valid only when the PSActionRetryCount
parameter is also used in the command.


-PSActionRunningTimeoutSec <Int32>
Determines how long the activity can run on each target
computer. If the activity does not complete before the
timeout expires, Windows PowerShell Workflow generates a
terminating error and stops processing the workflow on
the affected target computer.


-PSAllowRedirection <Boolean>
A value of $True allows redirection of the connection
to the target computers. A value of $False has no effect.
This activity common parameter is also a workflow common
parameter.

When you use the PSConnectionURI parameter, the remote
destination can return an instruction to redirect to a
different URI. By default, Windows PowerShell does not
redirect connections, but you can use the PSAllowRedirection
parameter with a value of $True to allow redirection of
the connection to the target computer.

You can also limit the number of times that the connection
is redirected by setting the MaximumConnectionRedirectionCount
property of the $PSSessionOption preference variable, or
the MaximumConnectionRedirectionCount property of the value
of the SSessionOption parameter of cmdlets that create a
session. The default value is 5.


-PSApplicationName <String>
Specifies the application name segment of the connection
URI that is used to connect to the target computers. Use
this parameter to specify the application name when you
are not using the ConnectionURI parameter in the command.
This activity common parameter is also a workflow common
parameter.

The default value is the value of the $PSSessionApplicationName
preference variable on the target computer. If this preference
variable is not defined, the default value is WSMAN. This value
is appropriate for most uses. For more information, see
about_Preference_Variables
(http://go.microsoft.com/fwlink/?LinkID=113248).

The WinRM service uses the application name to select a
listener to service the connection request. The value of
this parameter should match the value of the URLPrefix
property of a listener on the remote computer.


-PSAuthentication <AuthenticationMechanism>
Specifies the mechanism that is used to authenticate the
user's credentials when connecting to the target computers.
Valid values are Default, Basic, Credssp, Digest, Kerberos,
Negotiate, and NegotiateWithImplicitCredential. The default
value is Default. This activity common parameter is also a
workflow common parameter.

For information about the values of this parameter, see the
description of the
System.Management.Automation.Runspaces.AuthenticationMechanism
enumeration in MSDN.

CAUTION: Credential Security Service Provider (CredSSP)
authentication, in which the user's credentials are passed
to a remote computer to be authenticated, is designed for
commands that require authentication on more than one
resource, such as accessing a remote network share. This
mechanism increases the security risk of the remote operation.
If the remote computer is compromised, the credentials that
are passed to it can be used to control the network session.


-PSCertificateThumbprint <String>
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. This activity


common parameter is also a workflow common parameter.

Certificates are used in client certificate-based authentication.
They can only be mapped to local user accounts; they do not
work with domain accounts.

To get a certificate, use the Get-Item
(http://go.microsoft.com/fwlink/?LinkID=113319) or
Get-ChildItem (http://go.microsoft.com/fwlink/?LinkID=113308)
cmdlets in the Windows PowerShell Cert: drive.


-PSComputerName <String[]>
Specifies the target computers on which the activity run.
The default is the local computer. This activity common
parameter is also a workflow common parameter.

Type the NETBIOS name, IP address, or fully-qualified
domain name of one or more computers in a comma-separated
list. To specify the local computer, type the computer name,
"localhost", or a dot (.).

To include the local computer in the value of the
PSComputerName parameter, open Windows PowerShell with
the "Run as administrator" option.

If this parameter is omitted from the command, or it value
is $null or an empty string, the workflow target is the local
computer and Windows PowerShell remoting is not used to run
the command.

To use an IP address in the value of the ComputerName
parameter, the command must include the PSCredential
parameter. Also, the computer must be configured for HTTPS
transport or the IP address of the remote computer must be
included in the WinRM TrustedHosts list on the local computer.
For instructions for adding a computer name to the TrustedHosts
list, see "How to Add a Computer to the Trusted Host List" in
about_Remote_Troubleshooting
(http://go.microsoft.com/fwlink/?LinkID=135188).


-PSConfigurationName <String>
Specifies the session configurations that are used to
create sessions on the target computers. Enter the name of a
session configuration on the target computers (not on the
computer that is running the workflow. The default is
Microsoft.PowerShell. This activity common parameter
is also a workflow common parameter.


-PSConnectionRetryCount <UInt>
Specifies the maximum number of attempts to connect to
each target computer if the first connection attempt fails.
Enter a number between 1 and 4,294,967,295 (UInt.MaxValue).
The default value, zero (0), represents no retry attempts.
This activity common parameter is also a workflow common
parameter.


-PSConnectionRetryIntervalSec <UInt>
Specifies the delay between connection retry attempts in
seconds. The default value is zero (0). This parameter is
valid only when the value of PSConnectionRetryCount is at
least 1. This activity common parameter is also a workflow
common parameter.


-PSConnectionURI <System.Uri>
Specifies a Uniform Resource Identifier (URI) that
defines the connection endpoint for the activity on
the target computer. The URI must be fully qualified.
This activity common parameter is also a workflow common
parameter.

The format of this string is as follows:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

The default value is http://localhost:5985/WSMAN.

If you do not specify a PSConnectionURI, you can
use the PSUseSSL, PSComputerName, PSPort, and
PSApplicationName parameters to specify the PSConnectionURI
values.

Valid values for the Transport segment of the URI
are HTTP and HTTPS. If you specify a connection URI
with a Transport segment, but do not specify a port,
the session is created with standards ports: 80 for
HTTP and 443 for HTTPS. To use the default ports for
Windows PowerShell remoting, specify port 5985 for HTTP
or 5986 for HTTPS.


-PSCredential <PSCredential>
Specifies a user account that has permission to
run the activity on the target computer. The default
is the current user. This parameter is valid only
when the PSComputerName parameter is included in the
command. This activity common parameter is also a
workflow common parameter.

Type a user name, such as "User01" or "Domain01\User01",
or enter a variable that contains a PSCredential object,
such as one that the Get-Credential cmdlet returns. If
you enter only a user name, you will be prompted for a
password.


-PSDebug <PSDataCollection[DebugRecord]>
Adds debug messages from the activity to the specified
debug record collection, instead of writing the debug
messages to the console or to the value of the Debug
property of the workflow job. You can add debug messages
from multiple activities to the same debug record collection
object.

To use this activity common parameter, use the New-Object
cmdlet to create a PSDataCollection object with a type of
DebugRecord and save the object in a variable. Then, use the
variable as the value of the PSDebug parameter of one or
more activities, as shown in the following example.

workflow Test-Workflow
{
$debugCollection = New-Object -Type System.Management.Automation.PSDataCollection[System.Management.Automation.DebugRecord]
InlineScript {\\Server01\Share01\Get-AssetData.ps1} -PSDebug $debugCollection -Debug $True
InlineScript {\\Server01\Share01\Set-AssetData.ps1} -PSDebug $debugCollection -Debug $True
if ($debugCollection -like "*Missing*") { ...}
}

-PSDisableSerialization <Boolean>
Directs the activity to return "live" (not serialized)
objects to the workflow. The resulting objects have
methods, as well as properties, but they cannot be
saved when a checkpoint is taken.


-PSError <PSDataCollection[ErrorRecord]>
Adds error messages from the activity to the specified error
record collection, instead of writing the error messages to
the console or to the value of the Error property of the
workflow job. You can add error messages from multiple
activities to the same error record collection object.

To use this activity common parameter, use the New-Object
cmdlet to create a PSDataCollection object with a type
of ErrorRecord and save the object in a variable. Then,
use the variable as the value of the PSError parameter
of one or more activities, as shown in the following example.

workflow Test-Workflow
{
$errorCollection = New-Object -Type System.Management.Automation.PSDataCollection[System.Management.Automation.ErrorRecord]
InlineScript {\\Server01\Share01\Get-AssetData.ps1} -PSError $errorCollection
InlineScript {\\Server01\Share01\Set-AssetData.ps1} -PSError $errorCollection
if ($errorCollection.Count -gt 2) { ...}
}


-PSPersist <Boolean>
Takes a checkpoint after the activity. This checkpoint
is in addition to any checkpoints that are specified in
the workflow. This activity common parameter is also a
workflow common parameter.

A "checkpoint" or "persistence point" is a snapshot of the
workflow state and data that is captured while the workflow
runs and is saved to a persistence store on disk. Windows
PowerShell Workflow uses the saved data to resume a suspended
or interrupted workflow from the last persistence point,
rather than to restart the workflow.

Valid values:

-- (Default) If you omit this parameter, no checkpoints are
added. Checkpoints are taken based on the settings for the
workflow.

-- $True. Takes a checkpoint after the activity completes.
This checkpoint is in addition to any checkpoints that
are specified in the workflow.

-- $False. No checkpoints are added. Checkpoints are taken
only when specified in the workflow.



-PSPort <Int32>
Specifies the network port on the target computers.
The default ports are 5985 (the WinRM port for HTTP)
and 5986 (the WinRM port for HTTPS). This activity
common parameter is also a workflow common parameter.

Do not use the PSPort parameter unless you must. The
port set in the command applies to all computers or
sessions on which the command runs. An alternate port
setting might prevent the command from running on all
computers. Before using an alternate port, you must
configure the WinRM listener on the remote computer
to listen at that port.


-PSProgress <PSDataCollection[ProgressRecord]>
Adds progress messages from the activity to the
specified progress record collection, instead of
writing the progress messages to the console or
to the value of the Progress property of the
workflow job. You can add progress messages
from multiple activities to the same progress
record collection object.


-PSProgressMessage <String>
Specifies a friendly description of the activity.
The PSProgressMessage value appears in the progress
bar while the workflow runs. When the DisplayName is
also included in the command, the progress bar content
appears in <DisplayName>:<PSProgressMessage> format.

This parameter is particularly useful for identifying
activities in a ForEach -Parallel script block. Without
this message, activities in all parallel branches are
identified by the same name.


-PSRemotingBehavior <RemotingBehavior>
Specifies how remoting is managed when the activity is
run on target computers. PowerShell is the default.

Valid values are:

None: The activity is not run on remote computers.

PowerShell: Windows PowerShell remoting is used to
run the activity on target computers.

Custom: The activity supports its own type of remoting.
This value is valid when the cmdlet that is being
implemented as an activity sets the value of the
RemotingCapability attribute to SupportedByCommand and
the command includes the ComputerName parameter.

-PSRequiredModules <String[]>
Imports the specified modules before running the command.
Enter the module names. The modules must be installed on
the target computer.

Modules that are installed in a path specified in the
PSModulePath environment variable are automatically
imported on first use of any command in the module. Use
this parameter to import modules that are not in a
PSModulePath location.

Because each activity in a workflow runs in its own
session, an Import-Module command imports a module only
into the session in which it runs. It does not import the
module into sessions in which other activities run.


-PSSessionOption <PSSessionOption>
Sets advanced options for the sessions to the
target computers. Enter a PSSessionOption object,
such as one that you create by using the New-PSSessionOption
cmdlet. This activity common parameter is also a workflow
common parameter.

The default values for the session options are
determined by the value of the $PSSessionOption
preference variable, if it is set. Otherwise, the
session uses the values specified in the session
configuration.

For a description of the session options, including
the default values, see the help topic for the
New-PSSessionOption cmdlet
(http://go.microsoft.com/fwlink/?LinkID=144305).

For more information about the $PSSessionOption
preference variable, see about_Preference_Variables
(http://go.microsoft.com/fwlink/?LinkID=113248).


-PSUseSSL <Boolean>
A value of $True uses the Secure Sockets Layer (SSL)
protocol to establish a connection to the target
computer. By default, SSL is not used. A value of $False
has no effect. This activity common parameter is also
a workflow common parameter.

WS-Management encrypts all Windows PowerShell
content transmitted over the network. UseSSL is
an additional protection that sends the data across
an HTTPS, instead of HTTP. If you use this parameter,
but SSL is not available on the port used for the
command, the command fails.


-PSVerbose <PSDataCollection[VerboseRecord]>
Adds verbose messages from the activity to the
specified verbose record collection, instead of
writing the verbose messages to the console or
to the value of the Verbose property of the workflow
job. You can add verbose messages from multiple
activities to the same verbose record collection
object.


-PSWarning <PSDataCollection[WarningRecord]>
Adds warning messages from the activity to the
specified warning record collection, instead of
writing the warning messages to the console or
to the value of the Warning property of the
workflow job. You can add warning messages from
multiple activities to the same warning record
collection object.


-Result
This parameter is valid only in XAML workflows.


-UseDefaultInput <Boolean>
Accepts all workflow input as input to the
activity by value.

For example, the Get-Process activity in the
following sample workflow uses the UseDefaultInput
activity common parameter to get input that is
passed to the workflow. When you run the workflow
with input, that input is used by the activity.

workflow Test-Workflow
{
Get-Service -UseDefaultInput $True
}

PS C:\>Test-Workflow -InputObject WinRm

Status Name DisplayName PSComputerName
------ ---- ----------- --------------
Running winrm Windows Remote Management (WS-Manag... localhost


-Verbose <SwitchParameter>
Displays detailed information about the
operation performed by the command. This
information resembles the information in a
trace or in a transaction log. The Verbose
parameter overrides the value of the
$VerbosePreference variable for the current
command. This parameter works only when the
command generates a verbose message. This
parameter is also a Windows PowerShell common
parameter.


-WarningAction <ActionPreference>
Determines how the activity responds to a warning.
"Continue" is the default value. The WarningAction
parameter overrides the value of the $WarningPreference
variable for the current command. This parameter works
only when the command generates a warning message. This
parameter is also a Windows PowerShell common parameter.

Valid Values:

SilentlyContinue. Suppresses the warning message
and continues executing the command.

Continue. Displays the warning message and continues
executing the command. "Continue" is the default
value.

Inquire. Displays the warning message and prompts
you for confirmation before continuing execution.
This value is rarely used.

Stop. Displays the warning message and stops
executing the command.

NOTE: The WarningAction parameter does not override
the value of the $WarningAction preference variable
when the parameter is used in a command to run a
script or function.




EXAMPLES
The activity common parameters are extremely useful.
For example, you can use the PSComputerName parameter
to run particular activities on only a subset of the
target computers.

Or, you might use the PSConnectionRetryCount and
PSConnectionRetryIntervalSec parameters to adjust the
retry values for particular activities.

The following example shows how to use the PSComputerName
activity common parameters to run a Get-EventLog activity
only on computers it a particular domain.

Workflow Test-Workflow
{
$UserDomain = Get-Content -Path .\UserComputers.txt
$Log = (Get-EventLog -LogName "Windows PowerShell" -PSComputerName $UserDomain}
if ($Log) ...
}

KEYWORDS
about_Activity_Common_Parameters
about_Activity_Parameters
about_ActivityParameters

SEE ALSO
about_Workflows
about_WorkflowCommonParameters
a