about_ActivityCommonParameters

  • 项目

简短说明

介绍由 Windows PowerShell 工作流添加到活动的参数。

详细说明

Windows PowerShell 工作流将活动通用参数添加到从 PSActivity 基类派生的活动。 此类别包括 InlineScript 活动和作为活动实现的 Windows PowerShell cmdlet，例如 Get-Process 和 Get-WinEvent。

活动通用参数对 Suspend-Workflow 和 Checkpoint-Workflow 活动无效，它们不会添加到 Windows PowerShell 工作流在 InlineScript 脚本块或类似活动中自动运行的 cmdlet 或表达式。 活动通用参数在 InlineScript 活动上可用，但在 InlineScript 脚本块中的命令上不可用。

有多个活动通用参数也是工作流通用参数或 Windows PowerShell 通用参数。 其他活动通用参数是活动所特有的。

有关工作流通用参数的信息，请参阅 about_WorkflowCommonParameters。 有关 Windows PowerShell 通用参数的信息，请参阅 about_CommonParameters。

活动通用参数列表

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

参数说明

本部分介绍活动通用参数。

AppendOutput <Boolean>

值 $True 将活动输出添加到变量值中。 值 $False 不起作用。 默认情况下，向变量分配值会替换变量值。

例如，以下命令向 $x 变量中的服务对象添加进程对象。

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

此参数专为基于 XAML 的工作流而设计。 在脚本工作流中，还可以使用 += 赋值运算符将输出添加到变量值，如以下示例所示。

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

Debug <SwitchParameter>

显示有关命令执行的操作的程序员级详细信息。 Debug 参数重写当前命令的 $DebugPreference 变量值。 此参数仅在命令生成调试消息时有效。 此参数也是 Windows PowerShell 通用参数。

DisplayName <String>

为活动指定友好名称。 DisplayName 值显示在进度栏中（工作流运行期间）和工作流作业的 Progress 属性值中。 当 PSProgressMessage 参数也包含在命令中时，进度栏内容会以 <DisplayName>:<PSProgressMessage> 格式显示。

ErrorAction <ActionPreference>

确定活动如何从命令响应非终止错误。 它不影响终止错误。 仅当命令生成非终止错误（例如来自 Write-Error cmdlet 的错误）时，此参数才有效。 ErrorAction 参数重写当前命令的 $ErrorActionPreference 变量值。 此参数也是 Windows PowerShell 通用参数。

有效值：

  • Continue。 显示错误消息并继续执行命令。 默认值为 Continue。

  • Ignore。 禁止显示错误消息并继续执行该命令。 与 SilentlyContinue 不同，Ignore 不会将错误消息添加到 $Error 自动变量。 Ignore 值是在 Windows PowerShell 3.0 中引入的。

  • Inquire。 显示错误消息，并在继续执行之前提示你确认。 此值很少使用。

  • Suspend。 自动暂停工作流作业以便进一步调查。 调查后，可以恢复工作流。

  • SilentlyContinue。 禁止显示错误消息并继续执行该命令。

  • Stop。 显示错误消息并停止执行命令。

Input <Object[]>

将对象的集合提交到活动。 这是将对象一次一个地通过管道传递给活动的替代方法。

MergeErrorToOutput <Boolean>

值 $True 向输出流添加错误。 值 $False 不起作用。 将此参数与 Parallel 和 ForEach -Parallel 关键字结合使用可以从单个集合中的多个并行命令收集相关错误和输出。

PSActionRetryCount <Int32>

如果首次尝试失败，则反复尝试运行活动。 默认值 0 表示不重试。

PSActionRetryIntervalSec <Int32>

确定操作重试之间的间隔（以秒为单位）。 默认值 0 表示立即重试操作。 仅当命令中还使用了 PSActionRetryCount 参数时，此参数才有效。

PSActionRunningTimeoutSec <Int32>

确定活动每台目标计算机上可以运行的时间长度。 如果活动在超时到期之前未完成，则 Windows PowerShell 工作流将生成终止错误，并停止在受影响的目标计算机上处理工作流。

PSAllowRedirection <Boolean>

值 $True 允许将连接重定向到目标计算机。 值 $False 不起作用。 此活动通用参数也是工作流通用参数。

使用 PSConnectionURI 参数时，远程目标将返回一个指令，以重定向到不同的 URI。 默认情况下，Windows PowerShell 不会重定向连接，但你可以使用值为 $True 的 PSAllowRedirection 参数，以允许将连接重定向到目标计算机。

还可以通过设置 $PSSessionOption 首选项变量的 MaximumConnectionRedirectionCount 属性，或设置用于创建会话的 cmdlet 的 SessionOption 参数值的 MaximumConnectionRedirectionCount 属性，来限制连接的重定向次数。 默认值为 5。

PSApplicationName <String>

指定用于连接到目标计算机的连接 URI 的应用程序名称段。 当命令中未使用 ConnectionURI 参数时，请使用此参数指定应用程序名称。 此活动通用参数也是工作流通用参数。

默认值是目标计算机上 $PSSessionApplicationName 首选项变量的值。 如果未定义此首选项变量，则默认值为 WSMAN。 该值适用于大多数使用情况。 有关详细信息，请参阅 about_Preference_Variables。

WinRM 服务使用应用程序名称来选择为连接请求提供服务的侦听器。 此参数的值应与远程计算机上的侦听器的 URLPrefix 属性值相匹配。

PSAuthentication <AuthenticationMechanism>

指定在连接到目标计算机时用于验证用户凭据的机制。 有效值为 Default、Basic、CredSSP、Digest、Kerberos、Negotiate 和 NegotiateWithImplicitCredential。 默认值为 Default。 此活动通用参数也是工作流通用参数。

有关此参数的值的信息，请参阅 PowerShell SDK 中 System.Management.Automation.Runspaces.AuthenticationMechanism 枚举的说明。

警告

在凭据安全服务提供程序 (CredSSP) 身份验证中，用户凭据传递到远程计算机中以进行验证，这种验证用于要求对多个资源（例如访问远程网络共享）进行验证的命令。 此机制增加了远程操作的安全风险。 如果远程计算机的安全受到威胁，则传递给该计算机的凭据可用于控制网络会话。

PSCertificateThumbprint <String>

指定有权执行此操作的用户帐户的数字公钥证书 (X509)。 输入证书的证书指纹。 此活动通用参数也是工作流通用参数。

在基于客户端证书的身份验证中使用证书。 证书只能映射到本地用户帐户，而不适用于域帐户。

若要获取证书，请在 Windows PowerShell Cert: 驱动器中使用 Get-Item 或 Get-ChildItem cmdlet。

PSComputerName <String[]>

指定运行活动的目标计算机。 默认为本地计算机。 此活动通用参数也是工作流通用参数。

在以逗号分隔的列表中键入一台或多台计算机的 NETBIOS 名称、IP 地址或完全限定的域名。 若要指定本地计算机，请键入计算机名称 localhost 或点 (.)。

若要在 PSComputerName 参数值中包含本地计算机，请使用“以管理员身份运行”选项打开 Windows PowerShell。

如果在命令中省略此参数，或者参数值为 $null 或空字符串，则工作流目标是本地计算机，并且不会使用 Windows PowerShell 远程处理来运行该命令。

若要在 ComputerName 参数值中使用 IP 地址，该命令必须包含 PSCredential 参数。 此外，必须为计算机配置 HTTPS 传输，或者必须在本地计算机上的 WinRM TrustedHosts 列表中包含远程计算机的 IP 地址。 有关将计算机名称添加到 TrustedHosts 列表的说明，请参阅 about_Remote_Troubleshooting 中的“如何将计算机添加到受信任主机列表中”。

PSConfigurationName <String>

指定用于在目标计算机上创建会话的会话配置。 输入目标计算机（而不是运行工作流的计算机）上的会话配置的名称。 默认值为 microsoft.PowerShell.Workflow。 此活动通用参数也是工作流通用参数。

PSConnectionRetryCount <UInt>

指定在首次连接尝试失败时尝试连接到每台目标计算机的最大次数。 输入介于 1 和 4,294,967,295 (UInt.MaxValue) 之间的数字。 默认值零 (0) 表示不重试。 此活动通用参数也是工作流通用参数。

PSConnectionRetryIntervalSec <UInt>

指定下一次重试连接之前的延迟（以秒为单位）。 默认值为零 (0)。 仅当 PSConnectionRetryCount 的值至少为 1 时，此参数才有效。 此活动通用参数也是工作流通用参数。

PSConnectionURI <System.Uri>

指定统一资源标识符 (URI)，用于定义目标计算机上活动的连接终结点。 URI 必须完全限定。 此活动通用参数也是工作流通用参数。

此字符串的格式如下：

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

默认值是 http://localhost:5985/WSMAN。

如果未指定 PSConnectionURI，你可以使用 PSUseSSL、PSComputerName、PSPort 和 PSApplicationName 参数来指定 PSConnectionURI 值。

URI 的 Transport 段的有效值为 HTTP 和 HTTPS。 如果使用传输段指定连接 URI，但不指定端口，将使用以下标准端口来创建会话：80 用于 HTTP，443 用于 HTTPS。 若要使用 Windows PowerShell 远程处理的默认端口，请指定 HTTP 端口 5985 或 HTTPS 端口 5986。

PSCredential <PSCredential>

指定有权在目标计算机上运行活动的用户帐户。 默认为当前用户。 仅当命令中包含 PSComputerName 参数时，此参数才有效。 此活动通用参数也是工作流通用参数。

输入用户名（例如 User01 或 Domain01\User01），或输入包含 PSCredential 对象的变量（例如 Get-Credential cmdlet 返回的变量）。 如果仅输入用户名，则系统会提示你输入密码。

PSDebug <PSDataCollection[DebugRecord]>

将来自活动的调试消息添加到指定的调试记录集合，而不是将调试消息写入控制台或工作流作业的 Debug 属性值。 可以将来自多个活动的调试消息添加到同一个调试记录集合对象中。

若要使用此活动通用参数，请使用 New-Object cmdlet 创建类型为 DebugRecord 的 PSDataCollection 对象，并将该对象保存在变量中。 然后，使用该变量作为一个或多个活动的 PSDebug 参数的值，如以下示例所示。

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>

指示活动将“实时”（未序列化）对象返回给工作流。 得到的对象具有方法以及属性，但它们无法在采用检查点时进行保存。

PSDisableSerializationPreference <Boolean>

将等效于 PSDisableSerialization 参数的参数应用于整个工作流，而不仅仅是应用于活动。 通常不建议添加此参数，因为不序列化其对象的工作流无法恢复或持久保留。

有效值：

  • （默认值）如果省略此参数，同时未将 PSDisableSerialization 参数添加到活动，则对象将被序列化。

  • $True。 指示工作流中的所有活动返回“实时”（未序列化）对象。 得到的对象具有方法以及属性，但它们无法在采用检查点时进行保存。

  • $False。 工作流对象进行序列化。

PSError <PSDataCollection[ErrorRecord]>

将来自活动的错误消息添加到指定错误记录集合，而不是将错误消息写入控制台或工作流作业的 Error 属性值。 可以将来自多个活动的错误消息添加到同一个错误记录集合对象中。

若要使用此活动通用参数，请使用 New-Object cmdlet 创建类型为 ErrorRecord 的 PSDataCollection 对象，并将该对象保存在变量中。 然后，使用该变量作为一个或多个活动的 PSError 参数的值，如以下示例所示。

Workflow Test-Workflow
{
   $typeName = "System.Management.Automation.PSDataCollection"
   $typeName += '[System.Management.Automation.ErrorRecord]'
   $ec = New-Object $typeName
   InlineScript {\Server01\Share01\Get-AssetData.ps1} -PSError $ec
   InlineScript {\Server01\Share01\Set-AssetData.ps1} -PSError $ec
   if ($ec.Count -gt 2)
   {
      # Do Some Work.
   }
}

PSPersist <Boolean>

在活动完成后创建一个检查点。 此检查点是对工作流中指定的任何检查点的补充。 此活动通用参数也是工作流通用参数。

“检查点”或“持久性点”是工作流运行时捕获的工作流状态和数据的快照，将保存到磁盘上的持久性存储中。 Windows PowerShell 工作流使用保存的数据从最后一个持久性点恢复已暂停或中断的工作流，而不会重启工作流。

有效值：

  • （默认值）如果省略此参数，则不会添加检查点。 检查点是根据工作流设置创建的。

  • $True。 在活动完成后使用一个检查点。 此检查点是对工作流中指定的任何检查点的补充。

  • $False。 不会添加检查点。 仅当在工作流中指定时才会创建检查点。

PSPort <Int32>

指定目标计算机上的网络端口。 默认端口为 5985（HTTP 的 WinRM 端口）和 59`86（HTTPS 的 WinRM 端口）。 此活动通用参数也是工作流通用参数。

除非必要，否则不要使用 PSPort 参数。 在命令中设置的端口将应用于运行该命令的所有计算机或会话。 备用端口设置可能会阻止在所有计算机上运行该命令。 使用备用端口之前，你必须在远程计算机上配置 WinRM 侦听器，才能在该端口上进行侦听。

PSProgress <PSDataCollection[ProgressRecord]>

将来自活动的进度消息添加到指定进度记录集合，而不是将进度消息写入控制台或工作流作业的 Progress 属性值。 可以将来自多个活动的进度消息添加到同一个进度记录集合对象中。

PSProgressMessage <String>

指定活动的友好说明。 当工作流运行时，PSProgressMessage 值将显示在进度栏中。 当 DisplayName 也包含在命令中时，进度栏内容将以 <DisplayName>:<PSProgressMessage> 格式显示。

此参数对于在 ForEach -Parallel 脚本块中标识活动特别有用。 没有此消息时，所有并行分支中的活动都通过相同名称进行标识。

PSRemotingBehavior <RemotingBehavior>

指定活动在目标计算机上运行时的远程处理管理方式。 PowerShell 是默认值。

有效值为：

  • None：活动不会在远程计算机上运行。

  • PowerShell：Windows PowerShell 远程处理用于在目标计算机上运行活动。

  • Custom：活动支持其自己的远程处理类型。 当作为活动实现的 cmdlet 将 RemotingCapability 属性值设置为 SupportedByCommand 并且命令包含 ComputerName 参数时，此值是有效的。

PSRequiredModules <String[]>

在运行命令之前导入指定的模块。 输入模块名。 模块必须安装在目标计算机上。

安装在 PSModulePath 环境变量指定的路径中的模块会在首次使用模块中的任何命令时自动导入。 使用此参数可以导入不在 PSModulePath 位置的模块。

因为工作流中的每个活动都在其自己的会话中运行，所以 Import-Module 命令仅将模块导入运行它的会话中。 它不将模块导入运行其他活动的会话中。

PSSessionOption <PSSessionOption>

将会话的高级选项设置为目标计算机。 输入 PSSessionOption 对象，例如使用 New-PSSessionOption cmdlet 创建的对象。 此活动通用参数也是工作流通用参数。

会话选项的默认值由 $PSSessionOption 首选项变量的值（如果已设置）确定。 否则，会话将使用会话配置中指定的值。

有关会话选项的说明（包括默认值），请参阅 New-PSSessionOption cmdlet New-PSSessionOption 的帮助主题。

有关 $PSSessionOption 首选项变量的信息，请参阅 about_Preference_Variables。

PSUseSSL <Boolean>

$True 值使用安全套接字层 (SSL) 协议来建立与目标计算机的连接。 默认情况下，不使用 SSL。 值 $False 不起作用。 此活动通用参数也是工作流通用参数。

WS-Management 对通过网络传输的所有 Windows PowerShell 内容进行加密。 UseSSL 是一种额外的保护措施，它通过 HTTPS 而不是 HTTP 来发送数据。 如果你使用此参数，但 SSL 在用于此命令的端口上不可用，则命令将失败。

PSVerbose <PSDataCollection[VerboseRecord]>

将来自活动的详细消息添加到指定详细记录集合，而不是将详细消息写入控制台或工作流作业的 Verbose 属性值。 可以将来自多个活动的详细消息添加到同一个详细记录集合对象中。

PSWarning <PSDataCollection[WarningRecord]>

将来自活动的警告消息添加到指定警告记录集合，而不是将警告消息写入控制台或工作流作业的 Warning 属性值。 可以将来自多个活动的警告消息添加到同一个警告记录集合对象中。

结果

此参数仅在 XAML 工作流中有效。

UseDefaultInput <Boolean>

按值接受所有工作流输入作为活动的输入。

例如，以下示例工作流中的 Get-Process 活动使用 UseDefaultInput 活动通用参数获取传递给工作流的输入。 使用输入运行工作流时，活动会使用该输入。

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>

显示有关命令执行的操作的详细信息。 此信息类似于跟踪或事务日志中的信息。 Verbose 参数重写当前命令的 $VerbosePreference 变量值。 仅当命令生成详细消息时，此参数才有效。 此参数也是 Windows PowerShell 通用参数。

WarningAction <ActionPreference>

确定活动如何响应警告。 默认值为 Continue。 WarningAction 参数重写当前命令的 $WarningPreference 变量的值。 仅当命令生成警告消息时，此参数才有效。 此参数也是 Windows PowerShell 通用参数。

有效值：

  • SilentlyContinue。 禁止显示警告消息并继续执行命令。

  • Continue。 显示警告消息并继续执行命令。 默认值为 Continue。

  • Inquire。 显示警告消息，并在继续执行之前提示确认。 此值很少使用。

  • Stop。 显示警告消息并停止执行命令。

注意

在命令中使用参数来运行脚本或函数时，WarningAction 参数不会重写 $WarningAction 首选项变量的值。

示例

活动通用参数非常有用。 例如，可以使用 PSComputerName 参数，以便仅在一部分目标计算机上运行特定活动。

或者，可以使用 PSConnectionRetryCount 和 PSConnectionRetryIntervalSec 参数来调整特定活动的重试值。

以下示例演示如何使用 PSComputerName 活动通用参数，以便仅在特定域中的计算机上运行 Get-EventLog 活动。

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

    if ($Log)
    {
        # Do Work Here.
    }
}

另请参阅