簡短描述
描述可與任何 Cmdlet 搭配使用的參數。
長描述
常見的參數是一組 Cmdlet 參數,您可以搭配任何 Cmdlet 使用。 它們是由PowerShell實作,而不是由 Cmdlet 開發人員實作,而且它們會自動提供給任何 Cmdlet。
您可以將通用參數與任何 Cmdlet 搭配使用,但是它們可能不會對所有 Cmdlet 造成影響。 例如,如果 cmdlet 未生成任何詳細輸出,則使用 Verbose common 參數不會產生任何影響。
通用參數也可用於使用 CmdletBinding 屬性或 Parameter 屬性的高級函數以及所有工作流。
幾個常用參數會覆蓋您使用PowerShell首選項變數設置的系統預設值或首選項。 與喜好設定變數不同,通用參數只會影響所使用的命令。
除了通用參數之外,許多 cmdlet 還提供 WhatIf 和 Confirm 風險緩解參數。 牽涉到系統或用戶數據風險的 Cmdlet 通常會提供這些參數。
下列清單會顯示一般參數。 其別名會列在括弧中。
- 偵錯 (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- 詳細 (vb)
- WarningAction (wa)
- WarningVariable (wv)
風險風險降低參數包括:
- WhatIf (wi)
- 確認 (cf)
如需詳細資訊,請參閱 about_Preference_Variables。
常用參數說明
除錯
Debug 的別名是 db。
顯示命令所完成作業的程式設計人員層級詳細數據。 只有當命令產生偵錯訊息時,此參數才有效。 例如,當命令包含 Write-Debug Cmdlet 時,這個參數會運作。
Debug 參數覆蓋當前命令的變數值$DebugPreference,將的值$DebugPreference設置為 Continue。 由於變數的 $DebugPreference 預設值為 SilentlyContinue,因此預設情況下不會顯示調試消息。
-Debug:$true 的效果與 -Debug相同。 當 不是 -Debug:$false 時$DebugPreference,使用 來隱藏偵錯訊息的顯示,這是預設值。
錯誤動作
ErrorAction 的別名是 ea。
決定 Cmdlet 如何回應命令中的非終止錯誤。
只有當命令產生非終止錯誤時,此參數才有效,例如 Cmdlet 中的 Write-Error 錯誤。
ErrorAction 參數會覆寫目前命令的$ErrorActionPreference變數值。 因為變數的 $ErrorActionPreference 預設值是 Continue,因此除非您使用 ErrorAction 參數,否則會顯示錯誤訊息並繼續執行。
ErrorAction 參數不會影響終止錯誤(例如遺漏的數據、無效的參數或許可權不足),而無法順利完成命令。
-ErrorAction:Continue 顯示錯誤訊息並繼續執行命令。
Continue 是預設值。
-ErrorAction:Ignore 會隱藏錯誤訊息,並繼續執行 命令。 與 SilentlyContinue 不同, Ignore 不會將錯誤訊息新增至 $Error 自動變數。
忽略值是在PowerShell 3.0中引進。
-ErrorAction:Inquire 會顯示錯誤訊息,並在繼續執行之前提示您確認。 這個值很少使用。
-ErrorAction:SilentlyContinue 會隱藏錯誤訊息,並繼續執行 命令。
-ErrorAction:Stop 會顯示錯誤訊息,並停止執行 命令。
-ErrorAction:Suspend 在 PowerShell Core 上不受支持,因為它僅適用於工作流。
備註
當 ErrorAction 參數在命令中用於運行腳本或函數時,該參數會覆蓋 preference 變數的值,但不會替換$ErrorAction該參數的值。
ErrorVariable 錯誤變數
ErrorVariable 的別名為 ev。
ErrorVariable 將有關命令的錯誤消息存儲在指定變數和 automatic 變數中 $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] 來參考儲存在變數中的特定錯誤。
資訊作
InformationAction 的別名是 ia。
PowerShell 5.0 中引進。 在所使用的命令或腳本內, InformationAction 一般參數會覆寫喜好設定變數的值 $InformationPreference ,預設會設定為 SilentlyContinue。 當您搭配 Write-Information 在腳本中使用時,Write-Information會根據 InformationAction 參數的值來顯示值。 如需 $InformationPreference的詳細資訊,請參閱 about_Preference_Variables。
-InformationAction:Stop 在命令出現 Write-Information 時停止命令或腳本。
-InformationAction:Ignore 會隱藏參考訊息,並繼續執行 命令。 與 SilentlyContinue 不同, Ignore 會完全忘記資訊訊息;它不會將參考訊息新增至信息數據流。
-InformationAction:Inquire 會顯示您在命令中指定的 Write-Information 參考訊息,然後詢問是否要繼續。
-InformationAction:Continue 會顯示參考訊息,並繼續執行。
-InformationAction:Suspend 在 PowerShell Core 上不受支持,因為它僅適用於工作流。
-InformationAction:SilentlyContinue 當資訊訊息未顯示時,不會有任何作用,而且腳本會繼續而不會中斷。
備註
當 InformationAction 參數在命令中用於運行腳本或函數時,該參數會覆蓋 preference 變數的值,但不會替換$InformationAction該變數的值。
資訊變數
InformationVariable 的別名為 iv。
PowerShell 5.0 中引進。 在使用它的命令或腳本中, InformationVariable 通用參數將您通過添加 Write-Information 命令指定的字串存儲在變數中。
Write-Information 根據 InformationAction 通用參數的值顯示值;如果不添加 InformationAction 通用參數, Write-Information 則根據 preference 變數的值 $InformationPreference 顯示字串。 如需 $InformationPreference的詳細資訊,請參閱 about_Preference_Variables。
OutBuffer 緩衝區
OutBuffer 的別名是 ob 並採用 System.Int32 值。
決定在透過管線傳送任何物件之前,要累積在緩衝區中的物件數目。 如果您省略此參數,則會在產生物件時傳送物件。
此資源管理參數是針對進階用戶所設計。 當您使用此參數時,PowerShell 會分批 OutBuffer + 1將數據傳送至下一個 Cmdlet。
下列範例會以處理使用 Cmdlet 的ForEach-Object區塊之間Write-Host顯示 。 顯示替代的批次為 2 或 OutBuffer + 1。
1..4 | ForEach-Object {
Write-Host "$($_): First"; $_
} -OutBuffer 1 | ForEach-Object {
Write-Host "$($_): Second" }
1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second
OutVariable (輸出變數)
OutVariable 的別名是 ov。
除了沿著管線傳送輸出之外,也會將命令的輸出物件儲存在指定的變數中。
若要將輸出新增至變數,而不是取代可能儲存在該處的任何輸出,請在變數名稱之前輸入加號 (+)。
例如,下列命令會 $out 建立 變數,並將進程物件儲存在其中:
Get-Process PowerShell -OutVariable out
下列命令會將行程物件新增至 $out 變數:
Get-Process iexplore -OutVariable +out
下列命令會顯示變數的內容 $out :
$out
備註
OutVariable 參數所建立的變數是 [System.Collections.ArrayList]。
PipelineVariable (管道變數)
PipelineVariable 的別名是 pv 並採用字串值。
PipelineVariable 將當前管道元素的值存儲為變數,用於流經管道的任何命名命令。
有效值為字串,與任何變數名稱相同。
以下是 PipelineVariable 運作方式的範例。 在此範例中, PipelineVariable 參數會新增至 Foreach-Object 命令,以將命令的結果儲存在變數中。 1 到 10 的數位範圍通過管道傳遞到第一個 Foreach-Object 命令中,其結果存儲在名為 Left 的變數中。
第一個 Foreach-Object 命令的結果通過管道傳輸到第二個 Foreach-Object 命令中,該命令篩選第一個 Foreach-Object 命令返回的物件。 第二個命令的結果存儲在名為 Right 的變數中。
在第三個 Foreach-Object 命令中,前兩個 Foreach-Object 管道命令的結果(由變數 Left 和 Right 表示)使用乘法運算符進行處理。 該命令指示對存儲在 Left 和 Right 變數中的物件進行乘法,並指定結果應顯示為 “Left range member * Right range member = product”。
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 的別名是 vb。
顯示命令所完成作業的詳細資訊。 這項信息類似於追蹤或事務歷史記錄中的資訊。 只有當命令生成詳細訊息時,此參數才有效。 例如,當命令包含 Write-Verbose Cmdlet 時,這個參數會運作。
Verbose 參數會覆寫目前命令的$VerbosePreference變數值。 因為 $VerbosePreference 變數的預設值是 SilentlyContinue,因此預設不會顯示詳細訊息。
-Verbose:$true 的效果與相同 -Verbose
-Verbose:$false 隱藏冗長訊息的顯示。 當 的值 $VerbosePreference 不是 SilentlyContinue 時,請使用此參數 (預設值)。
WarningAction作
WarningAction 的別名是 wa。
決定 Cmdlet 如何回應命令中的警告。
Continue 是預設值。 只有當命令產生警告訊息時,此參數才有效。 例如,當命令包含 Write-Warning Cmdlet 時,這個參數會運作。
WarningAction 參數會覆寫目前命令的$WarningPreference變數值。 因為變數的 $WarningPreference 預設值是 Continue,因此除非您使用 WarningAction 參數,否則會顯示警告並繼續執行。
-WarningAction:Continue 會顯示警告訊息,並繼續執行 命令。
Continue 是預設值。
-WarningAction:Inquire 會顯示警告訊息,並在繼續執行之前提示您確認。 這個值很少使用。
-WarningAction:SilentlyContinue 會隱藏警告訊息,並繼續執行 命令。
-WarningAction:Stop 會顯示警告訊息,並停止執行 命令。
備註
當 WarningAction 參數在命令中用於運行腳本或函數時,該參數會覆蓋 preference 變數的值,但不會替換 $WarningAction 該變數的值。
WarningVariable (警告變數)
WarningVariable 的別名是 wv。
將有關命令的警告存儲在指定的變數中。
所有產生的警告都會儲存在變數中,即使不會向用戶顯示警告也一樣。
若要將警告附加至變數內容,而不是取代可能儲存在該處的任何警告,請在變數名稱之前輸入加號 (+)。
例如,下列命令會 $a 建立 變數,然後將任何警告儲存在變數中:
Get-Process -Id 6 -WarningVariable a
下列命令會將任何警告新增至 $a 變數:
Get-Process -Id 2 -WarningVariable +a
下列命令會顯示的內容 $a:
$a
您可以使用此參數來建立只包含來自特定命令之警告的變數。 您可以使用數位表示法,例如 $a[0] 或 $warning[1,2] 來參考儲存在變數中的特定警告。
備註
WarningVariable 參數不會從函數或腳本中的嵌套調用中捕獲警告。
風險管理參數描述
Whatif
WhatIf 的別名是wi。
顯示描述命令效果的訊息,而不是執行命令。
WhatIf 參數會覆寫目前命令的$WhatIfPreference變數值。 因為變數的 $WhatIfPreference 預設值是 0(已停用), 因此 WhatIf 行為不會在沒有 WhatIf 參數的情況下完成。 有關更多資訊,請鍵入以下命令:
Get-Help about_Preference_Variables
-WhatIf:$true 的效果與 -WhatIf相同。
-WhatIf:$false 會隱藏變數值為 $WhatIfPreference 1 時所產生的自動 WhatIf 行為。
例如,下列命令會在 -WhatIf 命令中使用 Remove-Item 參數:
Remove-Item Date.csv -WhatIf
PowerShell 不會移除專案,而是列出其所要執行的作業,以及受影響的專案。 此命令會產生下列輸出:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
確認
Confirm 的別名是 cf。
在執行命令之前,提示您進行確認。
Confirm 參數將覆蓋當前命令的變數值$ConfirmPreference。 預設值為 True。 有關更多資訊,請鍵入以下命令:
Get-Help about_Preference_Variables
-Confirm:$true 的效果與 -Confirm相同。
-Confirm:$false 會隱藏自動確認,當的值 $ConfirmPreference 小於或等於 Cmdlet 的估計風險時,就會發生這種確認。
例如,以下命令將 Confirm 參數與 Remove-Item 命令一起使用。 拿掉專案之前,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 response 選項如下:
| 回應 | 結果 |
|---|---|
| 是 (Y) | 執行該動作。 |
| 所有是 (A) | 執行所有作並禁止後續 Confirm 查詢 |
| 對於此命令。 | |
| 否 (N): | 請勿執行該作。 |
| 否 (L): | 不執行任何作並禁止後續 Confirm |
| 此命令的查詢。 | |
| 暫停 (S): | 暫停命令並建立暫存會話。 |
| 說明 (?) | 顯示這些選項的說明。 |
Suspend (暫停) 選項將命令置於暫停狀態,並創建一個臨時嵌套會話,您可以在該會話中工作,直到準備好選擇 Confirm (確認) 選項為止。 巢狀會話的命令提示字元有兩個額外的插入號 (>>) 表示它是原始父命令的子作業。 您可以在巢狀會話中執行命令和腳稿。 要結束嵌套會話並返回到原始命令的 Confirm 選項,請鍵入 「exit」。
在下列範例中,當使用者檢查命令參數的說明時, 會使用 Suspend 選項 (S) 暫時停止命令。 獲取所需資訊后,使用者鍵入 「exit」 以結束嵌套提示,然後選擇對 Confirm 查詢的 Yes (y) 回應。
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 (defau
lt is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt
關鍵字
about_Common_Parameters