閱讀英文

共用方式為


關於 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 目前命令之變數的值,將的值設定 $DebugPreferenceContinue。 因為變數的預設值 $DebugPreferenceSilentlyContinue,所以預設不會顯示偵錯工具訊息。

-Debug:$true與具有相同的效果 -Debug-Debug:$false$DebugPreferenceSilentlyContinue(這是預設值)時,請使用來隱藏調試訊息的顯示。

ErrorAction

ErrorAction的別名是ea

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

ErrorAction參數會覆寫 $ErrorActionPreference 目前命令的變數值。 因為變數的預設值 $ErrorActionPreferenceContinue,所以會顯示錯誤訊息,並繼續執行,除非您使用ErrorAction參數。

ErrorAction參數不會影響導致命令無法順利完成的終止錯誤(例如遺漏資料、不正確參數或許可權不足)。

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

-ErrorAction:Ignore抑制錯誤訊息,並繼續執行命令。 不同于SilentlyContinueIgnore不會將錯誤訊息加入至 $Error 自動變數。 在 PowerShell 3.0 中引進了忽略值。

-ErrorAction:Inquire會顯示錯誤訊息,並在繼續執行之前提示您確認。 此值很少使用。

-ErrorAction:SilentlyContinue抑制錯誤訊息,並繼續執行命令。

-ErrorAction:Stop顯示錯誤訊息並停止執行命令。

-ErrorAction:SuspendPowerShell Core 不支援,因為它僅適用于工作流程。

注意

ErrorAction $ErrorAction 當命令中使用參數來執行腳本或函式時,ErrorAction 參數會覆寫,但不會取代喜好設定變數的值。

ErrorVariable

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

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:SuspendPowerShell Core 不支援,因為它僅適用于工作流程。

-InformationAction:SilentlyContinue沒有任何作用,因為未顯示參考用訊息(預設值),而且腳本會繼續執行而不中斷。

注意

InformationAction $InformationAction 當命令中使用參數來執行腳本或函式時,InformationAction 參數會覆寫,但不會取代喜好設定變數的值。

InformationVariable

InformationVariable的別名是iv

在 PowerShell 5.0 中引進。 在使用它的命令或腳本中, InformationVariable一般參數會在變數中儲存您藉由新增命令所指定的字串 Write-InformationWrite-Information系統會根據InformationAction一般參數的值顯示值。如果您未新增InformationAction一般參數,則 Write-Information 會根據喜好設定變數的值來顯示字串 $InformationPreference 。 如需的詳細資訊 $InformationPreference ,請參閱about_Preference_Variables

OutBuffer

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

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 會使用乘法運算子來處理前兩個輸送命令的結果(由LeftRight所表示)。 此命令會指示儲存在左右變數中的物件相乘 ,並指定結果應顯示為「左範圍成員 * 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 目前命令的變數值。 因為變數的預設值 $VerbosePreferenceSilentlyContinue,所以預設不會顯示詳細訊息。

-Verbose:$true的效果與-Verbose

-Verbose:$false隱藏詳細資訊訊息的顯示。 當的值 $VerbosePreference 不是SilentlyContinue (預設)時,請使用此參數。

WarningAction

WarningAction的別名是wa

決定 Cmdlet 如何回應來自命令的警告。 [繼續] 是預設值。 只有在命令產生警告訊息時,此參數才有效。 例如,當命令包含 Cmdlet 時,此參數會運作 Write-Warning

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

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

-WarningAction:Inquire顯示警告訊息,並在繼續執行之前提示您確認。 此值很少使用。

-WarningAction:SilentlyContinue抑制警告訊息,並繼續執行命令。

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

注意

WarningAction $WarningAction 當命令中使用參數來執行腳本或函式時,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-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

另請參閱

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose