about_CommonParameters
簡短描述
描述可與任何 Cmdlet 搭配使用的參數。
完整描述
常見的參數是一組 Cmdlet 參數，您可以搭配任何 Cmdlet 使用。 它們是由 PowerShell 實作，而不是由 Cmdlet 開發人員實作，而且會自動提供給任何 Cmdlet 使用。
您可以將通用參數與任何 Cmdlet 搭配使用，但是它們可能不會對所有 Cmdlet 造成影響。 例如，如果 Cmdlet 不會產生任何詳細信息輸出，則使用 Verbose Common 參數沒有任何作用。
使用 CmdletBinding 屬性或 Parameter 屬性的進階函式也提供通用參數。
數個常見的參數會覆寫您使用 PowerShell 喜好設定變數所設定的系統預設值或喜好設定。 不同於喜好設定變數，一般參數只會影響它們所使用的命令。
如需詳細資訊，請參閱 about_Preference_Variables。
下列清單會顯示一般參數。 其別名會列在括弧中。
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Verbose (vb)
- WarningAction (wa)
- WarningVariable (wv)
Action 參數是 ActionPreference 類型值。 ActionPreference 是具有下列值的列舉：
| 名稱 | 值 |
|---|---|
Break |
6 |
Suspend |
5 |
Ignore |
4 |
Inquire |
3 |
Continue |
2 |
Stop |
1 |
SilentlyContinue |
0 |
您可以搭配 參數使用名稱或值。
除了一般參數之外，許多 Cmdlet 還提供風險風險降低參數。 涉及系統或用戶數據風險的 Cmdlet 通常會提供這些參數。
風險降低參數如下：
- WhatIf (wi)
- Confirm (cf)
一般參數描述
-Debug
顯示命令所完成之作業的程式設計人員層級詳細數據。 此參數只適用於命令產生偵錯訊息時。 例如，當命令包含 Write-Debug Cmdlet 時，此參數可運作。
Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
根據預設，不會顯示偵錯訊息，因為變數的值 $DebugPreference 是 SilentlyContinue。
在互動式模式中 Debug ，參數會覆寫目前命令的 $DebugPreference 變數值，並將的值 $DebugPreference 設定為 查詢。
在非互動式模式中 Debug ，參數會覆寫目前命令的 $DebugPreference 變數值，並將的值 $DebugPreference 設定為 Continue。
-Debug:$true 的效果與 -Debug相同。 當 不是 SilentlyContinue 時，使用 -Debug:$false 來隱藏偵錯訊息$DebugPreference的顯示，這是預設值。
-ErrorAction
決定 Cmdlet 如何從 命令回應非終止錯誤。
只有當命令產生非終止錯誤時，此參數才適用，例如 Cmdlet 中的 Write-Error 錯誤。
Type: ActionPreference
Aliases: ea
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
ErrorAction 參數會覆寫目前命令的$ErrorActionPreference變數值。 因為變數的 $ErrorActionPreference 預設值是 Continue，所以除非您使用 ErrorAction 參數，否則會顯示錯誤訊息並繼續執行。
ErrorAction 參數不會影響終止錯誤 (，例如遺失的數據、無效的參數，或許可權不足) ，以防止命令順利完成。
-ErrorAction:Break 發生錯誤或引發例外狀況時，輸入調試程式。
-ErrorAction:Continue 會顯示錯誤訊息並繼續執行 命令。 Continue 是預設值。
-ErrorAction:Ignore 隱藏錯誤訊息並繼續執行 命令。 不同於 SilentlyContinue，Ignore 不會將錯誤訊息新增至 $Error自動變數。 忽略值是在PowerShell 3.0中引進。
-ErrorAction:Inquire 會顯示錯誤訊息，並在繼續執行之前提示您確認。 這個值很少使用。
-ErrorAction:SilentlyContinue 隱藏錯誤訊息並繼續執行 命令。
-ErrorAction:Stop 會顯示錯誤訊息並停止執行命令。
-ErrorAction:Suspend 僅適用於PowerShell 6和更新版本中不支援的工作流程。
注意
ErrorAction 參數會覆寫，但在命令中使用 參數來執行腳本或函式時，不會取代喜好設定變數的值$ErrorAction。
-ErrorVariable
ErrorVariable 會將命令的相關錯誤訊息儲存在指定的變數和自動變數中 $Error 。 如需詳細資訊，請參閱 about_Automatic_Variables
Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
根據預設，新的錯誤訊息會覆寫已儲存在變數中的錯誤訊息。 若要將錯誤訊息附加至變數內容，請在變數名稱之前輸入加號 (+) 。
例如，下列命令會 $a 建立 變數，然後將任何錯誤儲存在其中：
Get-Process -Id 6 -ErrorVariable a
下列命令會將任何錯誤訊息新增至 $a 變數：
Get-Process -Id 2 -ErrorVariable +a
下列命令會顯示的內容 $a：
$a
您可以使用此參數來建立變數，該變數只包含來自特定命令的錯誤訊息，且不會影響自動變數的行為 $Error 。 自動 $Error 變數包含會話中所有命令的錯誤訊息。 您可以使用數位表示法，例如 $a[0] 或 $error[1,2] 來參考儲存在變數中的特定錯誤。
注意
自定義錯誤變數包含命令所產生的所有錯誤，包括從呼叫巢狀函式或腳本的錯誤。
-InformationAction
PowerShell 5.0 中引進。 在所使用的命令或腳本內， InformationAction 通用參數會覆寫喜好設定變數的值 $InformationPreference ，預設會設定為 SilentlyContinue。 當您 Write-Information 搭配 InformationAction 在腳本中使用時， Write-Information 會根據 InformationAction 參數的值來顯示值。 如需 的詳細資訊 $InformationPreference，請參閱 about_Preference_Variables。
Type: ActionPreference
Aliases: ia
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
-InformationAction:Break 在命令出現 Write-Information 時輸入調試程式。
-InformationAction:Stop 在發生 Write-Information 命令時停止命令或腳本。
-InformationAction:Ignore 隱藏參考訊息，並繼續執行 命令。 不同於 SilentlyContinue， 忽略 完全忘記參考訊息;它不會將參考訊息新增至信息數據流。
-InformationAction:Inquire 會顯示您在命令中指定的 Write-Information 參考訊息，然後詢問您是否要繼續。
-InformationAction:Continue 會顯示參考訊息，並繼續執行。
-InformationAction:Suspend PowerShell 6 和更新版本不支援，因為它僅適用於工作流程。
-InformationAction:SilentlyContinue 沒有作用，因為資訊訊息不會 (顯示預設) ，而且腳本會繼續而不會中斷。
注意
InformationAction 參數會覆寫，但在命令中使用 參數來執行腳本或函式時，不會取代喜好設定變數的值$InformationAction。
-InformationVariable
PowerShell 5.0 中引進。 在所使用的命令或腳本內， InformationVariable 通用參數會儲存在您藉由新增 Write-Information 命令所指定的字串變數中。 Write-Information 值會根據 InformationAction 一般參數的值來顯示;如果您未新增 InformationAction 通用參數， Write-Information 則會根據喜好設定變數的值 $InformationPreference 來顯示字串。 如需 的詳細資訊 $InformationPreference，請參閱 about_Preference_Variables。
注意
資訊變數包含命令所產生的所有資訊訊息，包括來自呼叫巢狀函式或腳本的資訊訊息。
Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-OutBuffer
決定在透過管線傳送任何物件之前，在緩衝區中累積的物件數目。 如果您省略此參數，則會在產生物件時傳送物件。
Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
此資源管理參數是專為進階用戶所設計。 當您使用此參數時，PowerShell 會將數據傳送至批次中的 OutBuffer + 1下一個 Cmdlet。
下列範例會在 之間顯示 ，以 ForEach-Object 處理使用 Cmdlet 的 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
除了沿著管線傳送輸出之外，還會將命令的輸出物件儲存在指定的變數中。
Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
若要將輸出新增至變數，而不是取代可能儲存在該處的任何輸出，請在變數名稱之前輸入加號 + () 。
例如，下列命令會 $out 建立 變數，並將進程物件儲存在其中：
Get-Process PowerShell -OutVariable out
下列命令會將行程物件新增至 $out 變數：
Get-Process iexplore -OutVariable +out
下列命令會顯示變數的內容 $out ：
$out
注意
OutVariable 參數所建立的變數為 [System.Collections.ArrayList]。
-PipelineVariable
PipelineVariable 允許使用此參數的命令存取傳入下一個管線區段的最新值。 管線中的任何命令都可以使用名為 PipelineVariable 來存取值。 當值傳遞至下一個管線區段時，該值會指派給變數。 這可讓 PipelineVariable 比特定暫存變數更容易使用，這可能需要在多個位置指派。
不同於 $_ 或 $PSItem，使用 PipelineVariable 可讓任何管線命令存取 (傳遞並儲存) 的管線值，而不是緊接在上述命令以外的命令。 管線命令可以在處理通過管線的下一個專案時，存取從 傳送的最後一個值。 這可讓命令將其輸出 摘要回 先前的命令， (或本身) 。
注意
進階函式最多可以有三個腳本區塊： begin、 process和 end。 搭配進階函式使用 PipelineVariable 參數時，只有第一個已定義腳本區塊的值會指派給變數，因為函式會執行。 如需詳細資訊，請參閱 進階函式。 PowerShell 7.2 會更正此行為。
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
有效值為字串，與任何變數名稱相同。
警告
PipelineVariable 的範圍設定為叫用管線的管線。 管線外部使用相同名稱的變數會在執行管線之前移除。 管線終止時，PipelineVariable 超出範圍。 如果管線內的多個命令指定相同的 PipelineVariable ，則只有一個共用變數。 該變數會使用指定變數之命令的最新管線輸出來更新。
某些 封鎖 命令會在產生任何輸出之前收集所有管線專案，例如 Sort-Object 或 Select-Object -Last。 在這類封鎖命令之前，在命令中指派的任何 PipelineVariable 一律會在封鎖命令之後用於命令時，包含上述命令的最終管線專案。
以下是 PipelineVariable 運作方式的範例。 在此範例中， PipelineVariable 參數會新增至 Foreach-Object 命令，以將命令的結果儲存在變數中。 數位範圍 1 到 5 會以管線傳送至第一 Foreach-Object 個命令，結果會儲存在名為 $temp的變數中。
第一個Foreach-Object命令的結果會以管線傳送至第二Foreach-Object個命令，以顯示 和$_的目前值$temp。
# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created is not available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
Write-Output $_
} | ForEach-Object {
Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp
Name Value
---- -----
temp 8
Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
Step2[PROCESS]:$temp=5 - $_=5
Get-Variable: Cannot find a variable with the name 'temp'.
-Verbose
顯示命令所完成之作業的詳細資訊。 這項信息類似於追蹤或事務歷史記錄中的資訊。 只有當命令產生詳細資訊訊息時，此參數才適用。 例如，當命令包含 Write-Verbose Cmdlet 時，此參數可運作。
Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
參數 Verbose 會覆寫目前命令的 $VerbosePreference 變數值。 由於變數的 $VerbosePreference 預設值為 SilentlyContinue，因此預設不會顯示詳細資訊訊息。
-Verbose:$true 的效果與相同 -Verbose
-Verbose:$false 隱藏詳細資訊訊息的顯示。 當 的值 $VerbosePreference 不是 SilentlyContinue (預設) 時，請使用此參數。
-WarningAction
決定 Cmdlet 如何回應命令中的警告。 Continue 是預設值。 只有當命令產生警告訊息時，此參數才適用。 例如，當命令包含 Write-Warning Cmdlet 時，此參數可運作。
Type: ActionPreference
Aliases: wa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
WarningAction 參數會覆寫目前命令的$WarningPreference變數值。 因為變數的 $WarningPreference 預設值是 Continue，所以除非您使用 WarningAction 參數，否則會顯示警告並繼續執行。
-WarningAction:Break 當發生警告時，會輸入調試程式。
-WarningAction:Continue 會顯示警告訊息並繼續執行 命令。 Continue 是預設值。
-WarningAction:Inquire 會顯示警告訊息，並在繼續執行之前提示您確認。 這個值很少使用。
-WarningAction:SilentlyContinue 隱藏警告訊息並繼續執行 命令。
-WarningAction:Stop 會顯示警告訊息，並停止執行 命令。
注意
WarningAction 參數會覆寫，但在命令中使用 參數來執行腳本或函式時，不會取代喜好設定變數的值$WarningAction。
-WarningVariable
將命令的相關警告儲存在指定的變數中。
Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
即使警告未向用戶顯示，所有產生的警告仍會儲存在變數中。
若要將警告附加至變數內容，而不是取代可能儲存在該處的任何警告，請在變數名稱之前輸入加號 (+) 。
例如，下列命令會 $a 建立 變數，然後將任何警告儲存在其中：
Get-Process -Id 6 -WarningVariable a
下列命令會將任何警告新增至 $a 變數：
Get-Process -Id 2 -WarningVariable +a
下列命令會顯示的內容 $a：
$a
您可以使用此參數來建立只包含來自特定命令之警告的變數。 您可以使用數位表示法，例如 $a[0] 或 $warning[1,2] 來參考儲存在變數中的特定警告。
注意
警告變數包含命令所產生的所有警告，包括來自呼叫巢狀函式或腳本的警告。
風險管理參數描述
-WhatIf
顯示描述命令效果的訊息，而不是執行命令。
Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
WhatIf 參數會覆寫目前命令的$WhatIfPreference變數值。 因為變數的 $WhatIfPreference 預設值是 0 (停用) ， 所以 WhatIf 行為不會在沒有 WhatIf 參數的情況下完成。 如需詳細資訊，請參閱 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
在執行命令之前提示您確認。
Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
參數 Confirm 會覆寫目前命令的 $ConfirmPreference 變數值。 預設值為 true。 如需詳細資訊，請參閱 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 選項如下所示：
| 回應 | 結果 |
|---|---|
Yes (Y) |
執行動作。 |
Yes to All (A) |
執行所有動作並隱藏後續 Confirm 查詢 |
| 針對此命令。 | |
No (N): |
請勿執行動作。 |
No to All (L): |
請勿執行任何動作並隱藏後續動作 Confirm |
| 查詢此命令。 | |
Suspend (S): |
暫停命令並建立暫存會話。 |
Help (?) |
顯示這些選項的說明。 |
[暫停] 選項會保留命令，並建立暫存巢狀會話，您可以在其中工作，直到您準備好選擇Confirm選項為止。 巢狀會話的命令提示字元有兩個額外的插入號 () >> ，表示它是原始父命令的子作業。 您可以在巢狀會話中執行命令和腳稿。 若要結束巢狀會話，並返回 Confirm 原始命令的選項，請輸入 「exit」。。
在下列範例中，當使用者檢查命令參數的說明時，會使用 [暫停 ] 選項 (S) 暫時停止命令。 取得所需的信息之後，使用者輸入「結束」結束巢狀提示，然後選取 [是] (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 (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