about_WorkflowCommonParameters

项目
10/20/2023

简短说明

本主题介绍对所有 Windows PowerShell 工作流命令有效的参数。由于 Windows PowerShell 引擎会将这些参数添加到工作流，因此你可以在任何工作流中使用它们，而它们会在你创建的工作流中自动启用。

详细说明

Windows PowerShell 工作流通用参数是一组可用于所有 Windows PowerShell 工作流和活动的 cmdlet 参数。它们是由 Windows PowerShell 工作流引擎而不是由工作流创建者添加的，并且它们在工作流和活动中自动可用。但是，深度为三个嵌套级别的工作流不支持任何通用参数，包括工作流通用参数。

所有工作流参数都是可选的且已命名（不是位置参数）。它们不会从管道获取输入。

大多数工作流通用参数都带有 PS 前缀，例如 PSComputerName 和 PSCredential。以 PS 为前缀的参数配置目标计算机（也称为“远程节点”）的连接和执行环境。

许多工作流通用参数（例如 PSAllowRedirection 和 AsJob）的名称与 Windows PowerShell 远程处理和后台作业中使用的参数类似。这些参数的工作方式与名称相似的远程处理和作业参数相同，因此你可以运用远程处理和作业方面的知识来管理工作流。

Windows PowerShell 3.0 中引入了工作流。

参数说明

本部分介绍工作流通用参数。

-AsJob <SwitchParameter>

将工作流作为工作流作业运行。工作流命令立即返回一个代表父作业的对象。父作业包含每台目标计算机上运行的子作业。若要管理作业，请使用 Job cmdlet。若要获取作业结果，请使用 Receive-Job。

-JobName <String>

为工作流作业指定一个友好名称。默认情况下，作业命名为 Job<n>，其中 <n> 为序号。

如果你在工作流命令中使用 JobName 参数，则工作流将作为作业运行，并且工作流命令将返回一个作业对象，即使你未在工作流命令中包含 AsJob 参数也是如此。

有关 Windows PowerShell 后台作业的详细信息，请参阅 about_Jobs。

-PSAllowRedirection <SwitchParameter>

允许将连接重定向到目标计算机。

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

还可以通过设置 $PSSessionOption 首选项变量的 MaximumConnectionRedirectionCount 属性，或设置 PSSessionOption 参数值的 MaximumConnectionRedirectionCount 属性，来限制连接的重定向次数。默认值是 5。有关详细信息，请参阅 PSSessionOption 参数和 New-PSSessionOption 的介绍。

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

-PSAuthenticationLevel <AuthenticationLevel>

指定与目标计算机的连接的身份验证级别。默认值为 Default。

有效值为：

名称	描述
`Unchanged`	身份验证级别与前一个命令相同。
`Default`	Windows 身份验证。
`None`	无 COM 身份验证。
`Connect`	连接级 COM 身份验证。
`Call`	调用级 COM 身份验证。
`Packet`	数据包级 COM 身份验证。
`PacketIntegrity`	数据包完整性级 COM 身份验证。
`PacketPrivacy`	数据包隐私级 COM 身份验证。

-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 返回的变量）。如果仅输入用户名，则系统会提示你输入密码。

-PSElapsedTimeoutSec <UInt32>

确定工作流和所有相关资源在系统中保留多长时间。如果超时已过，将删除工作流，即使它仍在处理中。输入 10 和 4,294,967,295 之间的值。默认值 0（零）表示没有超时。

-PSParameterCollection <Hashtable[]>

为不同的目标计算机指定不同的工作流通用参数值。

输入以逗号分隔的哈希表列表，每台目标计算机各有一个哈希表。在每个哈希表中，第一个键是 PSComputerName，其值是目标计算机的名称。计算机名中允许使用通配符。对于哈希表中的其余键，键是参数名称，值是参数值。

例如：

-PSParameterCollection @{PSComputerName="*"; PSElapsedTimeoutSec=20},
@{PSComputerName="Server02"},
@{PSComputerName="Server03"},
@{PSComputerName="Server01"; PSElapsedTimeoutSec=10}

在上面的示例中，所有连接的默认 PSElapsedTimeoutSec 为 20 秒，但 Server01 除外，它通过指定自己的 10 秒超时来重写默认值。

-PSPersist <Boolean>

将检查点添加到工作流，作为对工作流中指定的任何检查点的补充。

此参数无法抑制工作流中的检查点，例如使用 PSPersist 活动通用参数、Checkpoint-Workflow 活动或 $PSPersistPreference 变量指定的检查点。

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

有效值：

（默认）如果省略此参数，则还会将一个检查点添加到工作流的开头和结尾，作为对工作流中指定的任何检查点的补充。
$True。在工作流的开头和结尾添加一个检查点，并在每个活动之后添加一个检查点，作为对工作流中指定的任何检查点的补充。
$False。不会添加检查点。仅当在工作流中指定时才会创建检查点。

-PSPort <Int32>

指定目标计算机上的网络端口。默认端口为 5985（HTTP 的 WinRM 端口）和 5986（HTTPS 的 WinRM 端口）。

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

-PSPrivateMetadata <Hashtable>

为工作流作业提供自定义信息。输入哈希表。键和值是针对每个工作流自定义的。有关工作流的专用元数据的信息，请参阅工作流的帮助主题。

Windows PowerShell 工作流引擎不会处理此参数。引擎会将哈希表直接传递给工作流。

-PSRunningTimeoutSec <UInt32>

指定工作流的运行时间（以秒为单位），不包括工作流处于暂停状态的任何时间。如果该时间过后工作流执行未完成，Windows PowerShell 工作流引擎将强制停止该工作流的执行。

-PSSessionOption <PSSessionOption>

将会话的高级选项设置为目标计算机。输入 PSSessionOption 对象，例如使用 New-PSSessionOption cmdlet 创建的对象。

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

有关会话选项（包括默认值）的说明，请参阅 New-PSSessionOption。有关 $PSSessionOption 首选项变量的信息，请参阅 about_Preference_Variables。

-PSUseSSL <SwitchParameter>

使用安全套接字层 (SSL) 协议来建立与目标计算机的连接。默认情况下，不使用 SSL。

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