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