共用方式為


about_CommonParameters

適用於: Windows PowerShell 2.0, Windows PowerShell 3.0

在此插入簡介。

主題

about_CommonParameters

簡短描述

描述可以與任何 Cmdlet 搭配使用的參數。

詳細描述

常見的參數是一組您可用來與任何 Cmdlet 搭配使用的 Cmdlet 參數。其由 Windows PowerShell® 實作,而非 Cmdlet 開發人員,而且會自動提供給任何 Cmdlet。

您可以將一般參數與任何 Cmdlet 搭配使用,但是參數可能無法在所有 Cmdlet 上皆產生作用。例如,如果 Cmdlet 未輸出任何詳細資訊,則使用 Verbose 通用參數並不會有任何作用。

一般參數在使用 CmdletBinding 屬性或 Parameter 屬性的進階功能上,以及在所有工作流程上都可以使用。

數個常見的參數會覆寫系統預設值或您使用 Windows PowerShell 喜好設定變數來設定的喜好設定。與喜好設定變數不同,一般參數只會對使用它們的命令造成影響。

除了一般參數之外,許多 Cmdlet 還會提供 WhatIf 和 Confirm 風險降低參數。會牽涉到系統或使用者資料之風險的 Cmdlet 通常會提供這些參數。

下列清單顯示常見的參數。其別名列在括號中。

       -Debug (db)
       -ErrorAction (ea)
       -ErrorVariable (ev)
       -OutVariable (ov)
       -OutBuffer (ob)
       -PipelineVariable (pv)
       -Verbose (vb) 
       -WarningAction (wa)
       -WarningVariable (wv

風險降低參數如下:

-WhatIf (wi)
       -Confirm (cf)

如需有關喜好設定變數的詳細資訊,請輸入:

help about_Preference_Variables

一般參數說明

-DEBUG[:{$TRUE | $FALSE}]

Alias:db

顯示與命令執行之作業有關的程式設計師層級詳細資料。此參數只有在命令產生偵錯訊息時才適用。例如,此參數在命令包含 Write-Debug Cmdlet 時適用。

Debug 參數會覆寫目前命令的 $DebugPreference 變數值,而將 $DebugPreference 的值設為 Inquire。由於 $DebugPreference 變數的預設值是 SilentlyContinue,因此預設不會顯示偵錯訊息。

有效值:

$true (-Debug:$true). Has the same effect as -Debug.

$false (-Debug:$false). Suppresses the display of debugging
            messages when the value of the $DebugPreference is not
            SilentlyContinue (the default).

-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]

Alias:ea

判斷 Cmdlet 如何回應命令的非終止錯誤。此參數只有在命令產生非終止錯誤 (例如來自 Write-Error Cmdlet 的錯誤) 時才適用。

ErrorAction 參數會覆寫目前命令的 $ErrorActionPreference 變數值。由於 $ErrorActionPreference 變數的預設值為 Continue,因此除非您使用 ErrorAction 參數,否則便會顯示錯誤訊息並繼續執行。

ErrorAction 參數對於會防止命令順利完成的終止錯誤 (例如遺失資料、無效的參數或沒有足夠的權限) 沒有任何影響。

有效值:

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

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

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

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

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

Suspend。這個值只在 Windows PowerShell 工作流程中提供。當工作流程遭遇終止錯誤時,這個動作優先會自動暫停工作以便進一步調查。經過調查之後,就可以繼續工作流程。

-ERRORVARIABLE [+]<VARIABLE-NAME>

Alias:ev

在指定的變數和 $Error 自動變數中儲存命令的錯誤訊息。如需詳細資訊,請輸入下列命令:

get-help about_Automatic_Variables

根據預設,新的錯誤訊息會覆寫已儲存在變數中的錯誤訊息。若要將錯誤訊息附加至變數內容,請在變數名稱之前輸入加號 (+)。

例如,下列命令會建立 $a 變數,然後將任何錯誤儲存於其中:

Get-Process -Id 6 -ErrorVariable a

下列命令會將任何錯誤訊息加入 $a 變數中:

Get-Process -Id 2 -ErrorVariable +a

下列命令會顯示 $a 的內容:

$a

您可以使用此參數來建立只包含來自特定命令之錯誤訊息的變數。$Error 自動變數包含來自工作階段中所有命令的錯誤訊息。您可以使用陣列標記法 (例如 $a[0] 或 $error[1,2]) 來指稱儲存在變數中的特定錯誤。

-OUTBUFFER <INT32>

Alias:ob

決定在任何物件透過管線傳送之前,要在緩衝區中累計的物件數目。如果您省略這個參數,物件便會以產生出來的狀態傳送。

此資源管理參數專為進階使用者設計。當您使用這個參數時,Windows PowerShell 會等到產生的物件數目等於 OutBuffer + 1 時,才會呼叫管線中的下一個 Cmdlet。此後,其會將所有物件以產生出來的狀態傳送。

-OUTVARIABLE [+]<VARIABLE-NAME>

Alias:ov

將來自命令的輸出物件儲存在指定的變數中,並將其顯示在命令列。

若要將輸出加入到變數中,而非取代任何可能已儲存在該處的輸出,請在變數名稱之前輸入加號 (+)。

比方說,下列命令會建立 $out 變數並將程序物件儲存於其中:

Get-Process PowerShell -OutVariable out

下列命令會將程序物件加入 $out 變數中:

Get-Process iexplore -OutVariable +out

下列命令會顯示 $out 變數的內容:

$out

-PIPELINEVARIABLE <STRING>

Alias:pv

PipelineVariable 會將目前的管線元素值儲存為變數,在其流經管線時供任何具名命令使用。

有效值為字串,與任何的變數名稱相同。

以下是 PipelineVariable 運作方式的範例。在此範例中,PipelineVariable 參數會加入 Foreach-Object 命令中,以將命令的結果儲存在變數中。範圍為 1 到 10 的數字會透過管線傳遞給第一個 Foreach-Object 指令,而其結果會儲存在名為 Left 的變數中。

第一個 Foreach-Object 命令的結果會透過管線傳遞給第二個 Foreach-Object 命令,而後者會篩選第一個 Foreach-Object 命令所傳回的物件。第二個命令的結果會儲存在名為 Right 的變數中。

在第三個 Foreach-Object 命令中,以變數 Left 和 Right 呈現之頭兩個 Foreach-Object 管線命令的結果會使用乘法運算子來處理。這個命令會指示儲存在 Left 和 Right 變數中的物件要相乘,並指定其結果顯示為「Left 範圍成員 * Right 範圍成員 = 乘積」。

1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
              >>    Foreach-Object -PV Right -Process { 1..10 } |
              >>    Foreach-Object -Process { "$Left * $Right = " + ($Left * $Right) }
              >>
              1 * 1 = 1
              1 * 2 = 2
              1 * 3 = 3
              1 * 4 = 4
              1 * 5 = 5

-VERBOSE[:{$TRUE | $FALSE}]

Alias:vb

顯示命令所執行之作業的相關詳細資訊。此資訊類似追蹤或交易記錄檔中的資訊。此參數只有在命令產生詳細訊息時才適用。例如,此參數在命令包含 Write-Verbose Cmdlet 的情況下適用。

Verbose 參數會覆寫目前命令的 $VerbosePreference 變數值。由於 $VerbosePreference 變數的預設值是 SilentlyContinue,因此依預設不會顯示詳細訊息。

有效值:

$true (-Verbose:$true) has the same effect as -Verbose.

$false (-Verbose:$false) suppresses the display of verbose
            messages. Use this parameter when the value of $VerbosePreference
            is not SilentlyContinue (the default).

-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]

Alias:wa

決定 Cmdlet 應如何回應來自命令的警告。"Continue" 是預設值。此參數只有在命令產生警告訊息時才適用。例如,此參數在命令包含 Write-Warning Cmdlet 的情況下適用。

WarningAction 參數會覆寫目前命令的 $WarningPreference 變數值。由於 $WarningPreference 變數的預設值為 Continue,因此除非您使用 WarningAction 參數,否則會顯示警告並繼續執行。

有效值:

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

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

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

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

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

-WARNINGVARIABLE [+]<VARIABLE-NAME>

Alias:wv

將關於命令的警告儲存在指定的變數中。

即使警告沒有顯示給使用者看到,所有產生的警告依然會儲存在變數中。

若要將警告附加至變數內容,而非取代任何可能已經儲存在該處的警告,請在變數名稱之前輸入加號 (+)。

例如,下列命令會建立 $a 變數,然後將任何警告儲存於其中:

Get-Process -Id 6 -WarningVariable a

下列命令會將任何警告加入 $a 變數中:

Get-Process -Id 2 -WarningVariable +a

下列命令會顯示 $a 的內容:

$a

您可以使用此參數來建立只包含來自特定命令之警告的變數。您可以使用陣列標記法 (例如 $[0] 或 $warning[1,2]) 來參考儲存在變數中的特定警告。

注意:WarningVariable 參數不會擷取來自函式或指令碼中巢狀呼叫的警告。

風險管理參數的說明

-WHATIF[:{$TRUE | $FALSE}]

Alias:wi

顯示描述命令效果而非執行命令的訊息。

WhatIf 參數會覆寫目前命令的 $WhatIfPreference 變數值。由於 $WhatIfPreference 變數的預設值為 0 (停用),因此需要有 WhatIf 參數才會執行 WhatIf 行為。如需詳細資訊,請輸入下列命令:

Get-Help about_Preference_Variables

有效值:

$true (-WhatIf:$true). Has the same effect as -WhatIf.

$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
            that results when the value of the $WhatIfPreference variable 
            is 1.

例如,下列命令會在 Remove-Item 命令中使用 WhatIf 參數:

PS> Remove-Item Date.csv -WhatIf

Windows PowerShell 不會移除項目,而且還會列出要執行的作業以及會受到影響的項目。此命令會產生下列輸出:

What if: Performing operation "Remove File" on 
            Target "C:\ps-test\date.csv".

-CONFIRM[:{$TRUE | $FALSE}]

Alias:cf

執行命令之前先提示您確認。

Confirm 參數會覆寫目前命令的 $ConfirmPreference 變數值。預設值為 High。如需詳細資訊,請輸入下列命令:

Get-Help about_Preference_Variables

有效值:

$true (-Confirm:$true). Has the same effect as -Confirm.

$false(-Confirm:$false). Suppresses automatic confirmation,
            which occurs when the value of $ConfirmPreference is less than
            or equal to the estimated risk of the cmdlet.

例如,下列命令會將 Remove-Item 命令與 Confirm 參數搭配使用。在移除項目之前,Windows PowerShell 會列出要執行的作業以及會受到影響的項目,並要求核准。

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

此命令會產生下列輸出:

Confirm
            Are you sure you want to perform this action?
            Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  
            [?] Help (default is "Y"):

Confirm 回應選項如下所示:

Yes (Y)         Perform the action.
            Yes to All (A)  Perform all actions and suppress subsequent
                            Confirm queries for this command.
            No (N):         Do not perform the action.
            No to All (L):  Do not perform any actions and suppress subsequent
                            Confirm queries for this command.
            Suspend (S):    Pause the command and create a temporary session.
            Help (?)        Display help for these options.

Suspend 選項會保留命令並建立暫存巢狀工作階段,而在該處您可以一直進行處理,直到您準備好選擇 Confirm 選項為止。巢狀工作階段的命令提示字元具有兩個額外的插入點 (>>) ,可顯示其為原始父命令的子作業。您可以在巢狀工作階段中執行命令和指令碼。若要結束巢狀工作階段並回到原始命令的 Confirm 選項,請輸入 "exit"。

在下列範例中,Suspend 選項 (S) 在使用者查看命令參數的說明時,會用來暫時停止命令。在取得所需的資訊之後,使用者會輸入 "exit" 來結束巢狀提示,然後選擇 [是] (y) 來回應 Confirm 查詢。

PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

            Confirm
            Are you sure you want to perform this action?
            Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): s

            PS C:\ps-test>>> Get-Help New-Item -Parameter ItemType

            -ItemType <string>
                Specifies the provider-specified type of the new item.

                Required?                    false
                Position?                    named
                Default value
                Accept pipeline input?       true (ByPropertyName)
                Accept wildcard characters?  false


            PS C:\ps-test>>> exit

            Confirm
            Are you sure you want to perform this action?
            Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y


                Directory: C:\ps-test
            

            Mode                LastWriteTime     Length Name
            ----                -------------     ------ ----
            -a---         8/27/2010   2:41 PM          0 test.txt

關鍵字

about_Common_Parameters

另請參閱

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose