about_ActivityCommonParameters

適用於: Windows PowerShell 3.0

主題

about_ActivityCommonParameters

簡短描述

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

詳細描述

Windows PowerShell 工作流程會將活動一般參數新增至衍生自 PSActivity 基底類別的活動。此類別包括 InlineScript 活動，以及以活動 (例如 Get-Process 和 Get-WinEvent) 形式實作的 Windows PowerShell cmdlet。

活動一般參數在 Suspend-Workflow 和 Checkpoint-Workflow 活動上無效，而且不會新增至 Windows PowerShell 工作流程在 InlineScript 指令碼區塊或類似活動中自動執行的 cmdlet 或運算式。活動一般參數可用於 InlineScript 活動，但不能用於 InlineScript 指令碼區塊中的命令。

有數個活動一般參數同時也是工作流程一般參數或 Windows PowerShell 一般參數。其他活動一般參數則專用於活動。

如需工作流程一般參數的相關資訊，請參閱 about_WorkflowCommonParameters。如需 Windows PowerShell 一般參數的相關資訊，請參閱 about_CommonParameters。

活動一般參數清單

    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

參數描述

本節說明活動一般參數。

-Appendoutput <布林值>

$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 <切換參數>

顯示與命令執行之作業有關的程式設計師層級詳細資料。Debug 參數會覆寫目前命令的 $DebugPreference 變數值。唯有當命令產生偵錯訊息時，此參數才生效。此參數同時也是 Windows PowerShell 一般參數。

-DisplayName <字串>

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

-ErrorAction <動作喜好設定>

判斷活動如何回應命令所產生的非終止錯誤。其對於終止錯誤沒有任何作用。此參數只有在命令產生非終止錯誤 (例如來自 Write-Error Cmdlet 的錯誤) 時才適用。ErrorAction 參數會覆寫目前命令的 $ErrorActionPreference 變數值。此參數同時也是 Windows PowerShell 一般參數。

有效值：

Continue。顯示錯誤訊息，並繼續執行命令。"Continue" 是預設值。

Ignore。隱藏錯誤訊息，並繼續執行命令。不同於 SilentlyContinue，Ignore 不會將錯誤訊息加入 $Error 自動變數中。Windows PowerShell 3.0 中引入 Ignore 值。

Inquire。顯示錯誤訊息，並提示您確認之後再繼續執行。此值很少使用。

Suspend。自動暫止工作流程工作，以便進一步調查。經過調查之後，就可以繼續工作流程。

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

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

-Input <物件[]>

將物件集合提交給活動。這可以替代以管線將物件一次一個傳送給活動的方式。

-MergeErrorToOutput <布林值>

$True 值會將錯誤新增至輸出資料流。$False 值則沒有任何作用。將此參數與 Parallel 和 ForEach -Parallel 關鍵字搭配使用，將多個平行命令所產生的錯誤和輸出收集在單一集合中。

-PSActionRetryCount <Int32>

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

-PSActionRetryIntervalSec <Int32>

決定重試動作的間隔 (秒)。預設值為 0，表示立即重試動作。唯有當命令中也使用 PSActionRetryCount 參數時，此參數才有效。

-PSActionRunningTimeoutSec <Int32>

決定活動可以在每部目標電腦上執行多久。如果活動沒有在逾時過期前完成，Windows PowerShell 工作流程會產生終止錯誤，並停止處理受影響之目標電腦上的工作流程。

-PSAllowRedirection <布林值>

$True 值允許將目標電腦的連線重新導向。$False 值則沒有任何作用。此活動一般參數同時也是工作流程一般參數。

使用 PSConnectionURI 參數時，遠端目的地可傳回重新導向至不同 URI 的指示。Windows PowerShell 預設不會將連線重新導向，不過您可以使用 PSAllowRedirection 參數搭配 $True 值，允許將目標電腦的連線重新導向。

此外，若要限制將連線重新導向的次數，您可以設定 $PSSessionOption 喜好設定變數的 MaximumConnectionRedirectionCount 屬性，或是用以建立工作階段之 cmdlet 的 SSessionOption 參數值的 MaximumConnectionRedirectionCount 屬性。預設值為 5。

-PSApplicationName <字串>

指定用以連線到目標電腦之連線 URI 的應用程式名稱區段。當您沒有在命令中使用 ConnectionURI 參數時，請使用這個參數來指定應用程式名稱。此活動一般參數同時也是工作流程一般參數。

預設值是目標電腦上 $PSSessionApplicationName 喜好設定變數的值。若未定義此喜好設定變數，則預設值是 WSMAN。這個值適用於大部分用途。如需詳細資訊，請參閱 about_Preference_Variables (https://go.microsoft.com/fwlink/?LinkID=113248)。

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

-PSAuthentication <驗證機制>

指定連線到目標電腦時，用來驗證使用者認證的機制。有效值為 Default、Basic、Credssp、Digest、Kerberos、Negotiate 與 NegotiateWithImplicitCredential。預設值為 Default。此活動一般參數同時也是工作流程一般參數。

如需此參數值的資訊，請參閱 MSDN 中 System.Management.Automation.Runspaces.AuthenticationMechanism 列舉的說明。

注意：使用者認證會傳遞至要驗證之遠端電腦的「認證安全性服務提供者 (CredSSP)」驗證，是設計用於需要在一個以上資源進行驗證的命令，例如存取遠端網路共用。此機制會使得遠端作業的安全性風險變高。若遠端電腦遭到入侵，傳遞給它的認證便可用來控制網路工作階段。

-PSCertificateThumbprint <字串>

對於具有執行此動作之權限的使用者帳戶，指定其數位公開金鑰憑證 (X509)。請輸入憑證的憑證指紋。此活動一般參數同時也是工作流程一般參數。

憑證將用於用戶端憑證式驗證。這些憑證只能對應至本機使用者帳戶，無法用於網域帳戶。

若要取得憑證，請在 Windows PowerShell Cert: 磁碟機中使用 Get-Item (https://go.microsoft.com/fwlink/?LinkID=113319) 或 Get-ChildItem (https://go.microsoft.com/fwlink/?LinkID=113308) cmdlet。

-PSComputerName <字串[]>

指定要執行活動的目標電腦。預設是本機電腦。此活動一般參數同時也是工作流程一般參數。

請輸入 NETBIOS 名稱、IP 位址或是一部或多部電腦的完整網域名稱 (以逗號分隔的清單方式)。若要指定本機電腦，請輸入電腦名稱、"localhost" 或句點 (.)。

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

如果命令中省略此參數，或其值為 $null 或空字串，則工作流程目標為本機電腦，且不會使用 Windows PowerShell 遠端功能來執行命令。

若要在 ComputerName 參數的值中使用 IP 位址，則命令必須包含 PSCredential 參數。此外，必須將電腦設定為使用 HTTPS 傳輸，或必須在本機電腦的 WinRM TrustedHosts 清單中包含遠端電腦的 IP 位址。如需將電腦名稱新增到 TrustedHosts 清單的指示，請參閱 about_Remote_Troubleshooting (https://go.microsoft.com/fwlink/?LinkID=135188) 中的＜如何將電腦新增到信任的主機清單＞。

-PSConfigurationName <字串>

指定用以在目標電腦上建立工作階段的工作階段組態。輸入目標電腦 (而非執行工作流程的電腦) 上的工作階段組態名稱。預設值為 Microsoft.PowerShell。此活動一般參數同時也是工作流程一般參數。

-PSConnectionRetryCount <UInt>

指定第一個連線嘗試失敗時，嘗試連線到每部目標電腦的次數上限。輸入介於 1 和 4,294,967,295 (UInt.MaxValue) 之間的數字。預設值零 (0) 代表無重試次數。此活動一般參數同時也是工作流程一般參數。

-PSConnectionRetryIntervalSec <UInt>

指定嘗試重新連線之間的延遲秒數。預設值為零 (0)。唯有當 PSConnectionRetryCount 的值至少為 1 時，此參數才有效。此活動一般參數同時也是工作流程一般參數。

-PSConnectionURI <System.Uri>

指定統一資源識別項 (URI)，以針對目標電腦上的活動定義連線端點。此 URI 必須是完整的 URI。此活動一般參數同時也是工作流程一般參數。

這個字串的格式如下所示：

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

預設值為 https://localhost:5985/WSMAN。

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

URI 的 Transport 區段有效值為 HTTP 與 HTTPS。若指定含傳輸區段的連線 URI，但未指定連接埠，將會以標準連接埠建立工作階段：HTTP 使用 80，HTTPS 使用 443。若要使用預設連接埠來執行 Windows PowerShell 遠端功能，請為 HTTP 指定連接埠 5985，或是為 HTTPS 指定連接埠 5986。

-PSCredential <PS 認證>

指定有權在目標電腦上執行活動的使用者帳戶。預設為目前使用者。只有當命令中包含 PSComputerName 參數時，此參數才有效。此活動一般參數同時也是工作流程一般參數。

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

-PSDebug <PS 資料集合[偵錯記錄]>

將活動產生的偵錯訊息新增至指定的偵錯記錄集合，而不是將偵錯訊息寫入主控台，或工作流程工作的 Debug 屬性值。您可以將多個活動產生的偵錯訊息新增至相同的偵錯記錄集合物件。

若要使用此活動一般參數，請使用 New-Object Cmdlet 來建立具有一種 DebugRecord 類型的 PSDataCollection 物件，並將物件儲存在變數中。然後，將該變數用作一或多個活動的 PSDebug 參數值，如下列範例所示。

工作流程 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 <布林值>

指示該活動要將「即時」(非序列化) 物件傳回工作流程。所產生的物件具有方法與屬性，但是在取得檢查點時，無法將其儲存。

-PSDisableSerializationPreference <布林值>

將 PSDisableSerialization 參數的對等參數套用至整個工作流程，而不只是活動。通常不建議新增此參數，因為無法繼續執行或留存不會將其物件序列化的工作流程。

有效值：

-- (預設值) 如果省略，而且您也沒有將 PSDisableSerialization 參數新增至活動，就會將物件序列化。

-- $True。指示工作流程中的所有活動傳回「即時」(非序列化) 物件。所產生的物件具有方法與屬性，但是在取得檢查點時，無法將其儲存。

-- $False。工作流程物件會序列化。

-PSError <PS 資料集合[錯誤記錄]>

將活動產生的錯誤訊息新增至所指定的錯誤記錄集合，而不是將錯誤訊息寫入主控台或工作流程工作的 Error 屬性值。您可以將多個活動產生的錯誤訊息新增至相同的錯誤記錄集合物件。

若要使用此活動一般參數，請使用 New-Object Cmdlet 來建立具有一種 ErrorRecord 類型的 PSDataCollection 物件，並將物件儲存在變數中。然後，將該變數用作一或多個活動的 PSError 參數值，如下列範例所示。

工作流程 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 <布林值>

在活動之後取得檢查點。這個檢查點是除了工作流程中指定的任何檢查點之外，附加的檢查點。此活動一般參數同時也是工作流程一般參數。

「檢查點」或「持續點」是在工作流程執行時，所擷取之工作流程狀態和資料的快照，會儲存至磁碟上的持續性存放區。Windows PowerShell 工作流程會使用所儲存的資料，從上次的持續點繼續已暫止或中斷的工作流程，而不是重新啟動工作流程。

有效值：

-- (預設值) 如果您省略此參數，就不會新增任何檢查點。檢查點是根據工作流程的設定來取得。

-- $True。在活動完成之後取得檢查點。這個檢查點是除了工作流程中指定的任何檢查點之外，附加的檢查點。

-- $False。不會新增任何檢查點。僅接受在工作流程中指定的檢查點。

-PSPort <Int32>

指定目標電腦上的網路連接埠。預設連接埠是 5985 (用於 HTTP 的 WinRM 連接埠) 和 5986 (用於 HTTPS 的 WinRM 連接埠)。此活動一般參數同時也是工作流程一般參數。

除非必要，否則請勿使用 PSPort 參數。命令中設定的連接埠會套用到命令執行所在的所有電腦或工作階段。替代的連接埠設定可能使得命令無法在全部電腦上執行。使用替代連接埠之前，必須先將遠端電腦上的 WinRM 接聽程式設定為在該連接埠進行接聽。

-PSProgress <PS 資料集合[進度記錄]>

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

-PSProgressMessage <字串>

指定活動的易記描述。當工作流程執行時，PSProgressMessage 值會出現在進度列中。當 DisplayName 也包含在命令中時，進度列內容會以 <DisplayName>:<PSProgressMessage> 格式出現。

此參數特別適用於在 ForEach -Parallel 指令碼區塊中識別活動。若沒有此訊息，所有平行分支中的活動都會以相同名稱來識別。

-PSRemotingBehavior <遠端行為>

指定當活動在目標電腦上執行時，要如何管理遠端。PowerShell 為預設值。

有效值為：

None：活動不在遠端電腦上執行。

PowerShell：Windows PowerShell 遠端可用來在目標電腦上執行活動。

自訂：活動可支援其本身的遠端類型。當以活動形式實作的 cmdlet 將 RemotingCapability 屬性值設為 SupportedByCommand，而且命令包含 ComputerName 參數時，此值有效。

-PSRequiredModules <字串[]>

先匯入指定的模組，再執行命令。輸入模組名稱。模組必須安裝在目標電腦上。

在第一次使用模組中的任何命令時，會自動匯入在 PSModulePath 環境變數所指定路徑中安裝的模組。您可以使用此參數來匯入不是位於 PSModulePath 位置中的模組。

因為工作流程中的每個活動都是在其本身的工作階段中執行，所以 Import-Module 命令只會將模組匯入其執行所在的工作階段中。它不會將模組匯入其他活動執行所在的工作階段中。

-PSSessionOption <PS 工作階段選項>

為連線到目標電腦的工作階段設定進階選項。輸入 PSSessionOption 物件，例如使用 New-PSSessionOption Cmdlet 所建立的物件。此活動一般參數同時也是工作流程一般參數。

工作階段選項的預設值取決於 $PSSessionOption 喜好設定變數的值 (如果有設定)。否則，工作階段會使用工作階段組態中指定的值。

如需工作階段選項 (包括預設值) 的說明，請參閱 New-PSSessionOption Cmdlet 的說明主題 (https://go.microsoft.com/fwlink/?LinkID=144305)。

如需 $PSSessionOption 喜好設定變數的相關詳細資訊，請參閱 about_Preference_Variables (https://go.microsoft.com/fwlink/?LinkID=113248)。

-PSUseSSL <布林值>

$True 的值會使用安全通訊端層 (SSL) 通訊協定來建立目標電腦的連線。預設不會使用 SSL。$False 值則沒有任何作用。此活動一般參數同時也是工作流程一般參數。

WS-Management 會加密透過網路傳輸的所有 Windows PowerShell 內容。UseSSL 是額外的保護，可透過 HTTPS (而非 HTTP) 傳送資料。若您使用此參數，但是命令所用的連接埠上無法使用 SSL，則命令會失敗。

-PSVerbose <PS 資料集合[詳細記錄]>

將活動產生的詳細訊息新增至所指定的詳細記錄集合，而不是將詳細訊息寫入主控台或工作流程工作的 Verbose 屬性值。您可以將多個活動產生的詳細訊息新增至相同的詳細記錄集合物件。

-PSWarning <PS 資料集合[警告記錄]>

將活動產生的警告訊息新增至所指定的警告記錄集合，而不是將警告訊息寫入主控台或工作流程工作的 Warning 屬性值。您可以將多個活動產生的警告訊息新增至相同的警告記錄集合物件。

-RESULT

此參數只在 XAML 工作流程中有效。

-UseDefaultInput <布林值>

依值接受所有工作流程輸入做為活動的輸入。

例如，下列範例工作流程中的 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 <切換參數>

顯示命令所執行之作業的相關詳細資訊。此資訊類似追蹤或交易記錄檔中的資訊。Verbose 參數會覆寫目前命令的 $VerbosePreference 變數值。此參數只有在命令產生詳細訊息時才適用。此參數同時也是 Windows PowerShell 一般參數。

-WarningAction <動作喜好設定>

決定活動如何回應警告。"Continue" 是預設值。WarningAction 參數會覆寫目前命令的 $WarningPreference 變數值。此參數只有在命令產生警告訊息時才適用。此參數同時也是 Windows PowerShell 一般參數。

有效值：

SilentlyContinue。隱藏警告訊息，並繼續執行命令。

Continue。顯示警告訊息，並繼續執行命令。"Continue" 是預設值。

Inquire。顯示警告訊息，並提示您確認之後再繼續執行。此值很少使用。

Stop。顯示警告訊息，並停止執行命令。

注意：在命令中使用 WarningAction 參數來執行指令碼或函式時，此參數不會覆寫 $WarningAction 喜好設定變數的值。

範例

活動一般參數非常有用。例如，您可以使用 PSComputerName 參數，只在目標電腦的子集上執行特定活動。

或者，您可能會使用 PSConnectionRetryCount 和 PSConnectionRetryIntervalSec 參數來調整特定活動的重試值。

下列範例示範如何使用 PSComputerName 活動一般參數，只在特定網域的電腦上執行 Get EventLog 活動。

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

關鍵字

about_Activity_Common_Parameters

about_Activity_Parameters

about_ActivityParameters

另請參閱

about_Workflows

about_WorkflowCommonParameters