共用方式為

about_ActivityCommonParameters

  • 發行項

簡短描述

描述 Windows PowerShell 工作流程新增至活動的參數。

LONG DESCRIPTION

Windows PowerShell 工作流程會將活動通用參數新增至衍生自 PSActivity 基類的活動。 此類別包含 InlineScript 活動和 Windows PowerShell Cmdlet，這些 Cmdlet 會實作為活動，例如 Get-Process 和 Get-WinEvent。

活動通用參數在 和 Checkpoint-Workflow 活動上Suspend-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
}

偵錯 <SwitchParameter>

顯示命令所執行作業的程式設計人員層級詳細數據。 Debug 參數會覆寫目前命令的$DebugPreference變數值。 只有當命令產生偵錯訊息時，此參數才有效。 此參數也是 Windows PowerShell 通用參數。

DisplayName <字串>

指定活動的易記名稱。 當工作流程執行時，DisplayName 值會出現在進度列中，並在工作流程作業的 Progress 屬性值中出現。 當命令中也包含 PSProgressMessage 參數時，進度列內容會以<DisplayName>:<PSProgressMessage>格式顯示。

ErrorAction <ActionPreference>

決定活動如何從 命令回應非終止錯誤。 它不會影響終止錯誤。 只有當命令產生非終止錯誤時，此參數才有效，例如 Cmdlet 中的 Write-Error 錯誤。 ErrorAction 參數會覆寫目前命令的$ErrorActionPreference變數值。 此參數也是 Windows PowerShell 通用參數。

有效值：

  • Continue. 顯示錯誤訊息，並繼續執行 命令。 Continue 為預設值。

  • Ignore. 隱藏錯誤訊息，並繼續執行 命令。 不同於 SilentlyContinue， Ignore 不會將錯誤訊息新增至 $Error 自動變數。 此值 Ignore 會在 Windows PowerShell 3.0 中引進。

  • Inquire. 顯示錯誤訊息，並在繼續執行之前提示您確認。 這個值很少使用。

  • Suspend. 自動暫停工作流程工作，以允許進一步調查。 調查之後，可以繼續工作流程。

  • SilentlyContinue. 隱藏錯誤訊息，並繼續執行 命令。

  • Stop. 顯示錯誤訊息，並停止執行 命令。

Input <物件[]>

將物件的集合提交至活動。 這是一次一個管線物件的替代方法。

MergeErrorToOutput <Boolean>

的值 $True 會將錯誤新增至輸出數據流。 的值 $False 沒有作用。 使用此參數搭配 Parallel 和 ForEach -Parallel 關鍵詞，從單一集合中的多個平行命令收集錯誤和輸出。

PSActionRetryCount <Int32>

如果第一次嘗試失敗，請重複嘗試執行活動。 預設值 0， 不會重試。

PSActionRetryIntervalSec <Int32>

判斷動作重試之間的間隔，以秒為單位。 預設值 0，會立即重試動作。 只有在命令中也使用 PSActionRetryCount 參數時，此參數才有效。

PSActionRunningTimeoutSec <Int32>

決定活動可以在每個目標計算機上執行的時間長度。 如果活動在逾時到期前未完成，Windows PowerShell 工作流程會產生終止錯誤，並停止處理受影響目標電腦上的工作流程。

PSAllowRedirection <Boolean>

的值 $True 允許將連線重新導向至目標計算機。 的值 $False 沒有作用。 此活動通用參數也是工作流程通用參數。

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

您也可以設定喜好設定變數的 $PSSessionOption Maximum 連線 ionRedirectionCount 屬性，或建立會話之 Cmdlet 之 SessionOption 參數值的 Maximum 連線 ionRedirectionCount 屬性值，來限制聯機重新導向的次數。 預設值是 5。

PSApplicationName <字串>

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

預設值是目標電腦上的喜好設定變數值 $PSSessionApplicationName 。 如果未定義此喜好設定變數，預設值為 WSMAN。 此值適用於大部分使用。 如需詳細資訊，請參閱 about_Preference_Variables。

WinRM 服務會使用應用程式名稱來選取接聽程式以服務連線要求。 此參數的值應該符合 遠端電腦上接聽程式的 URLPrefix 屬性值。

PSAuthentication <AuthenticationMechanism>

指定連線到目標計算機時，用來驗證使用者認證的機制。 有效值為 Default、、Basic、、CredSSP、DigestKerberos、Negotiate、 和 NegotiateWithImplicitCredential。 預設值是 Default。 此活動通用參數也是工作流程通用參數。

如需此參數值的相關信息，請參閱 PowerShell SDK 中的 System.Management.Automation.Runspaces.AuthenticationMechanism 列舉描述。

警告

認證安全性服務提供者 （CredSSP） 驗證，其中使用者認證會傳遞至要驗證的遠端電腦，其設計目的是需要對多個資源進行驗證的命令，例如存取遠端網路共用。 此機制會增加遠端作業的安全性風險。 如果遠端電腦遭到入侵，傳遞給它的認證可用來控制網路會話。

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 <字串>

指定用來在目標計算機上建立會話的會話組態。 在目標計算機上輸入會話組態的名稱（不在執行工作流程的計算機上）。 預設值為 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 變數。 如果您只輸入使用者名稱，系統會提示您輸入密碼。

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

在活動之後取得檢查點。 此檢查點除了工作流程中指定的任何檢查點之外。 此活動通用參數也是工作流程通用參數。

「檢查點」或「持續性點」是工作流程狀態的快照集，以及工作流程執行時所擷取的數據，並儲存至磁碟上的持續性存放區。 Windows PowerShell 工作流程會使用已儲存的數據，從最後一個持續性點繼續暫停或中斷的工作流程，而不是重新啟動工作流程。

有效值：

  • （預設值）如果您省略此參數，則不會新增檢查點。 檢查點是根據工作流程的設定來取得。

  • $True. 在活動完成後採取檢查點。 此檢查點除了工作流程中指定的任何檢查點之外。

  • $False. 未新增檢查點。 只有在工作流程中指定時，才會採取檢查點。

PSPort <Int32>

指定目標電腦上的網路埠。 默認埠為 5985 （適用於 HTTP 的 WinRM 連接埠） 和 59'86 （適用於 HTTPS 的 WinRM 連接埠）。 此活動通用參數也是工作流程通用參數。

除非您必須，否則請勿使用 PSPort 參數。 命令中設定的埠會套用至執行命令的所有電腦或會話。 替代埠設定可能會防止命令在所有計算機上執行。 使用替代埠之前，您必須在遠端電腦上設定 WinRM 接聽程式，以在該埠接聽。

PSProgress <PSDataCollection[ProgressRecord]>

將活動中的進度訊息新增至指定的進度記錄集合，而不是將進度訊息寫入主控台或工作流程作業的 Progress 屬性值。 您可以將來自多個活動的進度訊息新增至相同的進度記錄集合物件。

PSProgressMessage <字串>

指定活動的易記描述。 工作流程執行時，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 物件，例如您使用 Cmdlet 建立的物件New-PSSessionOption。 此活動通用參數也是工作流程通用參數。

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

如需會話選項的描述，包括預設值，請參閱 New-PSSessionOption Cmdlet New-PSSessionOption 的說明主題。

如需喜好設定變數的詳細資訊 $PSSessionOption ，請參閱 about_Preference_Variables。

PSUseSSL <布爾值>

的值 $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 參數，只對目標計算機的子集執行特定活動。

或者，您可以使用 PS 連線 ionRetryCount 和 PS 連線 ionRetryIntervalSec 參數來調整特定活動的重試值。

下列範例示範如何使用 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.
    }
}

另請參閱