about_WorkflowCommonParameters

發行項
03/19/2024

簡短描述

本主題描述所有 Windows PowerShell 工作流程命令上有效的參數。因為 Windows PowerShell 引擎會將這些參數新增至工作流程，所以您可以在任何工作流程上使用這些參數，而且這些參數會自動啟用您撰寫的工作流程。

LONG DESCRIPTION

Windows PowerShell 工作流程一般參數是一組 Cmdlet 參數，您可以搭配所有 Windows PowerShell 工作流程和活動使用。它們是由 Windows PowerShell 工作流程引擎所新增，而不是由工作流程作者所新增，而且它們會自動在工作流程和活動上使用。不過，巢狀三層深度的工作流程不支援任何常見的參數，包括工作流程通用參數。

所有工作流程參數都是選擇性的，且命名為（不是位置）。它們不會從管線取得輸入。

大部分的工作流程通用參數都有前置 PS 詞，例如 PSComputerName 和 PSCredential。 PS 前置詞參數會設定目標計算機的連線和執行環境，也稱為「遠端節點」。

許多工作流程通用參數，例如 PSAllowRedirection 和 AsJob，其名稱類似於 Windows PowerShell 遠端處理和背景作業中使用的參數。這些參數的運作方式與類似命名的遠端處理和作業參數相同，因此您可以使用您在遠端處理和作業中開發的知識來管理工作流程。

工作流程是在 Windows PowerShell 3.0 中引進的。

參數描述

本節描述工作流程的一般參數。

-AsJob <SwitchParameter>

以工作流程作業的形式執行工作流程。工作流程命令會立即傳回代表父作業的物件。父作業包含在每個目標計算機上執行的子作業。若要管理作業，請使用作業 Cmdlet。若要取得作業結果，請使用 Receive-Job。

-JobName <字串>

指定工作流程作業的易記名稱。根據預設，作業會命名 Job<n>為，其中 <n> 是序數。

如果您在工作流程命令中使用 JobName 參數，工作流程會以作業的形式執行，而且工作流程命令會傳回作業物件，即使您未 在命令中包含 AsJob 參數也一樣。

如需 Windows PowerShell 背景工作的詳細資訊，請參閱 about_Jobs。

-PSAllowRedirection <SwitchParameter>

允許將連線重新導向至目標計算機。

當您使用 PS 連線 ionURI 參數時，遠端目的地可以傳回指示以重新導向至不同的 URI。根據預設，Windows PowerShell 不會重新導向連線，但您可以使用 PSAllowRedirection 參數來允許將連線重新導向至目標計算機。

您也可以設定喜好設定變數的 $PSSessionOption Maximum 連線 ionRedirectionCount 屬性，或 PSSessionOption 參數值的 Maximum 連線 ionRedirectionCount 屬性，來限制連接重新導向的次數。預設值是 5。如需詳細資訊，請參閱 PSSessionOption 參數和 New-PSSessionOption 的描述。

-PSApplicationName <String>

指定用來連線到目標電腦之連線 URI 的應用程式名稱區段。當您不使用 命令中的連線 ionURI 參數時，請使用此參數來指定應用程式名稱。

預設值是本機電腦上的喜好設定變數值 $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 <字串>

指定具有執行此動作許可權之用戶帳戶的數位公鑰憑證（X509）。輸入憑證的憑證指紋。

憑證將用於用戶端憑證式驗證。它們只能對應至本機用戶帳戶;它們不適用於網域帳戶。

若要取得憑證，請使用 Windows PowerShell Cert: 磁碟驅動器中的 Get-Item 或 Get-ChildItem Cmdlet。

-PSComputerName <String[]>

指定工作流程目標節點的計算機清單。工作流程中的命令或活動會在使用此參數所指定的計算機上執行。預設是本機電腦。

在逗號分隔清單中，輸入一或多部計算機的NETBIOS名稱、IP 位址或完整域名。若要指定本機計算機，請輸入計算機名稱、 localhost或點（.）。

若要在 PSComputerName 參數的值中包含本機計算機，請使用 [以系統管理員身分執行] 選項開啟 Windows PowerShell。

如果此命令省略此參數，或是值為 $null 或空字串，則工作流程目標為本機計算機，且不會使用 Windows PowerShell 遠端處理來執行命令。

若要在 ComputerName 參數的值中使用 IP 位址，命令必須包含 PSCredential 參數。此外，計算機必須針對 HTTPS 傳輸進行設定，或遠端電腦的 IP 位址必須包含在本機電腦上的 WinRM TrustedHosts 清單中。如需將計算機名稱新增至 TrustedHosts 清單的指示，請參閱 about_Remote_Troubleshooting 中的。

-PSConfigurationName <String>

指定用來在目標計算機上設定會話的會話組態。在目標計算機上輸入會話組態（而非工作流程伺服器計算機）。預設值為 Microsoft.PowerShell.Workflow。

-PS 連線 ionRetryCount <UInt>

指定第一次連線嘗試失敗時，連線到每個目標計算機的嘗試次數上限。輸入介於 1 到 4,294,967,295 之間的數位（UInt.MaxValue）。預設值零（0），表示沒有重試嘗試。

-PS 連線 ionRetryIntervalSec <UInt>

指定連線重試嘗試之間的延遲，以秒為單位。預設值為零（0）。只有當 PS 連線 ionRetryCount 的值至少1為時，此參數才有效。

-PS 連線 ionURI <System.Uri>

指定統一資源識別碼（URI），定義目標計算機上的工作流程連線端點。 URI 必須完整。

此字串格式如下所示：

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

預設值是 http://localhost:5985/WSMAN。

如果您未指定 PS 連線 ionURI，您可以使用 PSUseSSL、PSComputerName、PSPort 和 PSApplicationName 參數來指定 PS 連線 ionURI 值。

URI 傳輸區段的有效值為 HTTP 和 HTTPS。如果您指定具有傳輸區段的連線 URI，但未指定埠，則會使用標準埠建立會話： 80 用於 HTTP 和 443 HTTPS。若要使用 Windows PowerShell 遠端處理的預設埠，請指定 HTTP 或 5986 HTTPS 的埠5985。

-PSCredential <PSCredential>

指定有權在目標計算機上執行工作流程的用戶帳戶。預設為目前使用者。只有在命令中包含 PSComputerName 參數時，此參數才有效。

輸入使用者名稱，例如 User01 或 Domain01\User01，或輸入包含 PSCredential 物件的變數，例如 Cmdlet 傳回的 Get-Credential 變數。如果您只輸入使用者名稱，系統會提示您輸入密碼。

-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 <布爾值>

除了工作流程中指定的任何檢查點之外，也會將檢查點新增至工作流程。

此參數無法隱藏工作流程中的檢查點，例如使用 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 物件，例如您使用 Cmdlet 建立的物件New-PSSessionOption。

如果已設定，會話選項的 $PSSessionOption 預設值取決於喜好設定變數的值。否則，會話會使用會話組態中指定的值。

如需會話選項的描述，包括預設值，請參閱 New-PSSessionOption。如需喜好設定變數的相關信息 $PSSessionOption ，請參閱 about_Preference_Variables。

-PSUseSSL <SwitchParameter>

使用安全套接字層（SSL）通訊協定來建立目標電腦的連線。預設不會使用 SSL。

WS-Management 會加密透過網路傳輸的所有 Windows PowerShell 內容。 UseSSL 是額外的保護，可跨 HTTPS 傳送數據，而不是 HTTP。如果您使用此參數，但在用於命令的埠上無法使用 SSL，則命令會失敗。