關於 CommonParameters
描述可以搭配任何 Cmdlet 使用的參數。
一般參數是一組您可以搭配任何 Cmdlet 使用的 Cmdlet 參數。 它們是由 PowerShell 所執行,而不是由 Cmdlet 開發人員所實行,而且會自動提供給任何 Cmdlet 使用。
您可以使用一般參數搭配任何 Cmdlet,但它們可能不會影響所有 Cmdlet。 例如,如果 Cmdlet 不會產生任何詳細資訊輸出,使用verbose一般參數就不會有任何作用。
一般參數也適用于使用CmdletBinding屬性或參數屬性的 advanced 函數,以及所有工作流程上的。
有數個常見的參數會覆寫您使用 PowerShell 喜好設定變數所設定的系統預設值或喜好設定。 與喜好設定變數不同的是,一般參數只會影響其使用的命令。
除了一般參數之外,許多 Cmdlet 都會提供WhatIf並確認風險降低參數。 牽涉到系統或使用者資料風險的 Cmdlet 通常會提供這些參數。
下列清單會顯示一般參數。 其別名會列在括弧中。
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- 詳細資訊(vb)
- WarningAction (wa)
- WarningVariable (wv)
風險降低的參數包括:
- WhatIf (wi-fi)
- 確認(cf)
如需詳細資訊,請參閱about_Preference_Variables。
Debug的別名為db。
顯示命令所完成之作業的程式設計人員層級詳細資料。 這個參數只有在命令產生調試訊息時才會運作。 例如,當命令包含 Cmdlet 時,此參數會運作 Write-Debug
。
Debug參數會覆寫 $DebugPreference
目前命令之變數的值,將的值設定 $DebugPreference
為Continue。 因為變數的預設值 $DebugPreference
是SilentlyContinue,所以預設不會顯示偵錯工具訊息。
-Debug:$true
與具有相同的效果 -Debug
。 -Debug:$false
當 $DebugPreference
不SilentlyContinue(這是預設值)時,請使用來隱藏調試訊息的顯示。
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 $ErrorAction
當命令中使用參數來執行腳本或函式時,ErrorAction 參數會覆寫,但不會取代喜好設定變數的值。
ErrorVariable的別名是ev。
ErrorVariable會將有關命令的錯誤訊息儲存在指定的變數和 $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
在腳本中使用InformationAction時, Write-Information
會根據InformationAction參數的值顯示值。 如需的詳細資訊 $InformationPreference
,請參閱about_Preference_Variables。
-InformationAction:Stop
在命令出現時停止命令或腳本 Write-Information
。
-InformationAction:Ignore
抑制參考用訊息,並繼續執行命令。 不同于SilentlyContinue,[忽略] 會完全忘記參考用訊息;它不會將參考用訊息新增至資訊資料流程。
-InformationAction:Inquire
顯示您在命令中指定的參考用訊息 Write-Information
,然後詢問您是否要繼續。
-InformationAction:Continue
會顯示參考用訊息,並繼續執行。
-InformationAction:Suspend
PowerShell Core 不支援,因為它僅適用于工作流程。
-InformationAction:SilentlyContinue
沒有任何作用,因為未顯示參考用訊息(預設值),而且腳本會繼續執行而不中斷。
注意
InformationAction $InformationAction
當命令中使用參數來執行腳本或函式時,InformationAction 參數會覆寫,但不會取代喜好設定變數的值。
InformationVariable的別名是iv。
在 PowerShell 5.0 中引進。 在使用它的命令或腳本中, InformationVariable一般參數會在變數中儲存您藉由新增命令所指定的字串 Write-Information
。 Write-Information
系統會根據InformationAction一般參數的值顯示值。如果您未新增InformationAction一般參數,則 Write-Information
會根據喜好設定變數的值來顯示字串 $InformationPreference
。 如需的詳細資訊 $InformationPreference
,請參閱about_Preference_Variables。
OutBuffer的別名是ob ,並採用 system.string值。
決定在透過管線傳送任何物件之前,要在緩衝區中累積的物件數目。 如果您省略此參數,物件會在產生時傳送。
此資源管理參數是針對先進的使用者所設計。 當您使用此參數時,PowerShell 會以批次方式將資料傳送至下一個 Cmdlet OutBuffer + 1
。
下列範例替代 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的別名是ov。
除了透過管線傳送輸出外,還會將命令中的輸出物件儲存在指定的變數中。
若要將輸出新增至變數,而不是取代任何可能已經儲存在該處的輸出,請在變數名稱前面輸入一個加號( +
)。
例如,下列命令 $out
會建立變數,並將處理常式物件儲存在其中:
Get-Process PowerShell -OutVariable out
下列命令會將處理常式物件新增至 $out
變數:
Get-Process iexplore -OutVariable +out
下列命令會顯示變數的內容 $out
:
$out
注意
OutVariable參數所建立的變數是 [System.Collections.ArrayList]
。
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所表示)。 此命令會指示儲存在左右變數中的物件相乘 ,並指定結果應顯示為「左範圍成員 * Right range 成員 = 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。
顯示命令所完成之作業的詳細資訊。 這項資訊與追蹤或交易記錄中的資訊類似。 只有在命令產生詳細資訊訊息時,此參數才有效。 例如,當命令包含 Cmdlet 時,此參數會運作 Write-Verbose
。
Verbose參數會覆寫 $VerbosePreference
目前命令的變數值。 因為變數的預設值 $VerbosePreference
是SilentlyContinue,所以預設不會顯示詳細訊息。
-Verbose:$true
的效果與-Verbose
-Verbose:$false
隱藏詳細資訊訊息的顯示。 當的值 $VerbosePreference
不是SilentlyContinue (預設)時,請使用此參數。
WarningAction的別名是wa。
決定 Cmdlet 如何回應來自命令的警告。 [繼續] 是預設值。 只有在命令產生警告訊息時,此參數才有效。 例如,當命令包含 Cmdlet 時,此參數會運作 Write-Warning
。
WarningAction參數會覆寫 $WarningPreference
目前命令的變數值。 因為變數的預設值 $WarningPreference
會繼續,所以會顯示警告,並繼續執行,除非您使用WarningAction參數。
-WarningAction:Continue
顯示警告訊息,並繼續執行命令。 Continue
是預設值。
-WarningAction:Inquire
顯示警告訊息,並在繼續執行之前提示您確認。 此值很少使用。
-WarningAction:SilentlyContinue
抑制警告訊息,並繼續執行命令。
-WarningAction:Stop
顯示警告訊息,並停止執行命令。
注意
WarningAction $WarningAction
當命令中使用參數來執行腳本或函式時,WarningAction 參數會覆寫,但不會取代喜好設定變數的值。
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的別名是「 wi-fi」。
顯示描述命令效果的訊息,而不是執行命令。
WhatIf參數會覆寫 $WhatIfPreference
目前命令的變數值。 由於變數的預設值 $WhatIfPreference
為0(已停用),因此不會在沒有whatif參數的情況下完成whatif行為。 如需詳細資訊,請輸入下列命令:
Get-Help about_Preference_Variables
-WhatIf:$true
與具有相同的效果 -WhatIf
。
-WhatIf:$false
抑制當變數的值為1時,所產生的自動 WhatIf 行為 $WhatIfPreference
。
例如,下列命令會 -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"):
[確認回應] 選項如下所示:
回應 | 結果 |
---|---|
是(Y) | 執行動作。 |
全部皆是(A) | 執行所有動作,並隱藏後續的確認查詢 |
適用于此命令。 | |
否(N): | 請勿執行此動作。 |
全部皆否(L): | 請勿執行任何動作,並隱藏後續的確認 |
查詢此命令。 | |
暫停(秒): | 暫停命令,並建立暫時會話。 |
說明(?) | 顯示這些選項的說明。 |
[暫停] 選項會放置命令,並建立暫時的嵌套會話,您可以在其中工作,直到您準備好選擇 [確認] 選項為止。 此嵌套會話的命令提示字元有兩個額外的插入號(>>),表示它是原始父命令的子作業。 您可以在此嵌套會話中執行命令和腳本。 若要結束此嵌套會話並返回原始命令的 Confirm 選項,請輸入 "exit"。
在下列範例中,當使用者檢查命令參數的說明時,會使用暫停選項暫時停止命令。 取得所需的資訊之後,使用者必須輸入 "exit" 結束嵌套提示,然後選取 [是(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