共用方式為

關於_常見參數

簡短描述

描述可與任何 Cmdlet 搭配使用的參數。

完整描述

常見的參數是一組 Cmdlet 參數，您可以搭配任何 Cmdlet 使用。 它們是由PowerShell實作，而不是由 Cmdlet 開發人員實作，而且它們會自動提供給任何 Cmdlet。

您可以將通用參數與任何 Cmdlet 搭配使用，但是它們可能不會對所有 Cmdlet 造成影響。 例如，如果 Cmdlet 不會產生任何詳細資訊輸出，則使用 Verbose 一般參數沒有任何作用。

您也可以在使用 CmdletBinding 屬性或 Parameter 屬性的進階函式上使用通用參數。 當您使用這些屬性時，PowerShell 會自動新增 Common Parameters。 您無法建立任何使用與一般參數相同名稱的參數。

數個常見的參數會覆寫您使用 PowerShell 喜好設定變數所設定的系統預設值或喜好設定。 與喜好設定變數不同，通用參數只會影響所使用的命令。

如需詳細資訊，請參閱 about_Preference_Variables。

下列清單會顯示一般參數。 其別名會列在括弧中。

  • Debug （db）
  • ErrorAction （個）
  • ErrorVariable （ev）
  • InformationAction （發酵）
  • InformationVariable （四）
  • OutVariable （ov）
  • OutBuffer （觀察）
  • PipelineVariable （PV）
  • ProgressAction （宣傳片）
  • Verbose （vb）
  • WarningAction （瓦）
  • WarningVariable （西維吉尼亞州）

動作參數是ActionPreference類型值。 ActionPreference 是具有下列值的列舉：

名稱 值
Break 6
Suspend 5
Ignore 4
Inquire 3
Continue 2
Stop 1
SilentlyContinue 0

您可以使用名稱或值搭配 參數。

除了一般參數之外，許多 Cmdlet 還提供風險風險降低參數。 牽涉到系統或用戶數據風險的 Cmdlet 通常會提供這些參數。

風險風險降低參數包括：

  • WhatIf （威斯康星州）
  • 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 值設定為 Continue。

-Debug:$true 的效果與 -Debug相同。 用 -Debug:$false 來隱藏偵錯訊息 $DebugPreference 的顯示，而 不是 SilentlyContinue，這是預設值。

-錯誤作

決定 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 參數不會影響終止導致命令成功完成的錯誤 （例如遺漏資料、無效參數或權限不足）。

  • Break 當發生錯誤或引發例外狀況時，輸入調試程式。
  • Continue 會顯示錯誤訊息，並繼續執行 命令。 Continue 是預設值。
  • Ignore 會隱藏錯誤訊息，並繼續執行 命令。 與 不同SilentlyContinueIgnore，不會將錯誤訊息$Error新增至自動變數。 此 Ignore 值是在 PowerShell 3.0 中引進的。
  • Inquire 會顯示錯誤訊息，並在繼續執行之前提示您確認。 這個值很少使用。
  • SilentlyContinue 會隱藏錯誤訊息，並繼續執行 命令。
  • Stop 會顯示錯誤訊息，並停止執行 命令。
  • Suspend 僅適用於PowerShell 6和更新版本不支援的工作流程。

注意

參數 ErrorAction 會覆寫，但不會取代變數的 $ErrorActionPreference 值，當參數在命令中使用來執行指令碼或函式時。

-錯誤變數

錯誤記錄會自動儲存在自動變數中 $Error 。 如需詳細資訊，請參閱 about_Automatic_Variables。

當您在命令上使用參數 ErrorVariable 時，PowerShell 也會將命令發出的錯誤記錄儲存在參數指定的變數中。

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] 來參考儲存在變數中的特定錯誤。

注意

自定義錯誤變數包含命令所產生的所有錯誤，包括從呼叫巢狀函式或腳本的錯誤。

-資訊作

PowerShell 5.0 中引進。 在使用它的命令或腳本中， InformationAction common 參數會覆寫喜好設定變數的 $InformationPreference 值，預設會設定為 SilentlyContinue。 當您 Write-Information 在指令碼 InformationAction中使用 時， Write-Information 會根據參數的 InformationAction 值顯示值。 如需 的詳細資訊 $InformationPreference，請參閱 about_Preference_Variables。

Type: ActionPreference
Aliases: infa
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
  • Break 在命令出現時 Write-Information 輸入調試程式。
  • Stop 在命令出現 Write-Information 時停止命令或腳本。
  • Ignore 會隱藏參考訊息，並繼續執行 命令。 與 不同 SilentlyContinue，完全 Ignore 忘記資訊訊息;它不會將資訊訊息新增至資訊串流。
  • Inquire 會顯示您在命令中指定的 Write-Information 參考訊息，然後詢問是否要繼續。
  • Continue 會顯示參考訊息，並繼續執行。
  • Suspend PowerShell 6 和更新版本不支援，因為它僅適用於工作流程。
  • SilentlyContinue 當資訊訊息未顯示時，不會有任何作用，而且腳本會繼續而不會中斷。

注意

InformationAction參數會覆寫，但不會取代偏好設定變數的$InformationAction值，當參數在命令中用於執行指令碼或函式時。

-資訊變數

PowerShell 5.0 中引進。 當您使用 InformationVariable 一般參數時，資訊記錄會儲存在參數指定的變數中。 PowerShell Cmdlet 可以將資訊記錄寫入 Information 資料流程。 您也可以使用 Write-Information Cmdlet 來寫入信息記錄。

信息記錄預設會顯示為控制台中的訊息。 您可以使用一般參數來 InformationAction 控制資訊記錄的顯示。 您也可以使用 $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。

下列範例會以處理使用 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 （輸出變數）

除了沿著管線傳送輸出之外，也會將命令的輸出物件儲存在指定的變數中。

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 可能需要在多個位置指派的特定臨時變數更容易使用。

與 或 不同，$_使用 a $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 方式。 在此範例中，五個數字會透過管道傳送至第一個 ForEach-Object 命令。 管線中的每個項目都儲存在名為 $Temp的管線變數中。

第一個ForEach-Object指令的區塊會Process將管線項目管道傳送至下游ForEach-Object指令。 變數的狀態會顯示在每個步驟中。

# Create a variable named $Temp
$Temp = 8
Get-Variable Temp | Format-Table

$InformationPreference = 'Continue'
Write-Information '-------------------------------------------------'
111,222,333,444,555 | ForEach-Object -PipelineVariable Temp -Begin {

  # Note that the newly create $Temp variable doesn't contain the value 8
  # assigned before the pipeline started and that $PSItem is empty in
  # the Begin block.
  Write-Information "Upstream (Begin):   PSItem = '$PSItem', Temp = '$Temp'"

} -Process {

  Write-Information "Upstream (Process): PSItem = '$PSItem', Temp = '$Temp'"
  return $PSItem

} | ForEach-Object -Process {

  Write-Information "`tDownstream: PSItem = '$PSItem', Temp = '$Temp'"

}
Write-Information '-------------------------------------------------'

# The $Temp variable is deleted when the pipeline finishes
Get-Variable Temp | Format-Table

Name                           Value
----                           -----
Temp                           8

-------------------------------------------------
Upstream (Begin):   PSItem = '', Temp = ''
Upstream (Process): PSItem = '111', Temp = ''
        Downstream: PSItem = '111', Temp = '111'
Upstream (Process): PSItem = '222', Temp = '111'
        Downstream: PSItem = '222', Temp = '222'
Upstream (Process): PSItem = '333', Temp = '222'
        Downstream: PSItem = '333', Temp = '333'
Upstream (Process): PSItem = '444', Temp = '333'
        Downstream: PSItem = '444', Temp = '444'
Upstream (Process): PSItem = '555', Temp = '444'
        Downstream: PSItem = '555', Temp = '555'
-------------------------------------------------

Name                           Value
----                           -----
Temp

警告

在包含 CimCmdlet 或 CDXML Cmdlet 的管線中使用 PipelineVariable 參數有兩個已知問題。 在下列範例中， Get-Partition 是CDXML函式，而 Get-CimInstance 是 CimCmdlet。

問題 1：CDXML 函式使用 [CmdletBinding()]，允許 PipelineVariable 參數。

Get-Partition -pv pvar

不過，當您在 Windows PowerShell v5.1 中使用 PipelineVariable 時，您會收到下列錯誤。

Get-Partition : Cannot retrieve the dynamic parameters for the cmdlet.
Object reference not set to an instance of an object.

At line:1 char:1
+ get-partition -PipelineVariable pvar
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Get-Partition], ParameterBindingException
    + FullyQualifiedErrorId : GetDynamicParametersException,Get-Partition

問題 2：當上述命令 不是 CDXML 命令，且下游包含任一命令類型時， PipelineVariable 會保留為最後累積的物件。

Get-CimInstance Win32_DiskDrive -pv pvar |
    ForEach-Object {
        Write-Host "Upstream: Disk $($pvar.Index)"
        return [pscustomobject]@{ DiskNumber = $_.Index }
    } | Get-Partition | ForEach-Object {
        Write-Host "Downstream: Disk $($pvar.Index)"
    }

請注意，設定為第二個命令管線中最後一個$pvar物件的值ForEach-Object。

Upstream: Disk 1
Upstream: Disk 2
Upstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0
Downstream: Disk 0

-ProgressAction

決定 PowerShell 如何回應腳本、Cmdlet 或提供者所產生的進度更新，例如 Write-Progress Cmdlet 所產生的進度列。 Cmdlet Write-Progress 會建立進度列，以顯示命令的狀態。 此 ProgressAction 參數已新增至 PowerShell 7.4 中。

參數ProgressAction會採用ActionPreference其中一個列舉值：SilentlyContinue、Stop、Continue、InquireIgnoreSuspend或Break。

有效值如下：

  • Break 在命令出現時 Write-Progress 輸入調試程式。
  • Stop：不會顯示進度列。 相反地，它會顯示錯誤訊息並停止執行。
  • Inquire：不會顯示進度列。 提示輸入許可權以繼續。 如果您使用 或Y回復A，則會顯示進度列。
  • Continue:(預設值） 顯示進度列，並繼續執行。
  • SilentlyContinue：執行 命令，但不會顯示進度列。
Type: ActionPreference
Aliases: proga
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

-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 （預設值） 時，請使用此參數。

-警告作

決定 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 ，否則會顯示警告並繼續執行。

  • Break 當發生警告時，會輸入調試程式。
  • Continue 會顯示警告訊息，並繼續執行 命令。 Continue 是預設值。
  • Inquire 會顯示警告訊息，並在繼續執行之前提示您確認。 這個值很少使用。
  • SilentlyContinue 會隱藏警告訊息，並繼續執行 命令。
  • Stop 會顯示警告訊息，並停止執行 命令。

注意

WarningAction參數會覆寫，但不會取代偏好設定變數的$WarningAction值，當參數在命令中用於執行指令碼或函式時。

-警告變數

將命令的相關警告記錄儲存在指定的變數中。

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。

  • $true 的效果與 -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。

  • $true 的效果與 -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 （?） 顯示這些選項的說明。

此 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 (defau
lt is "Y"): y

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         8/27/2010   2:41 PM          0 test.txt

另請參閱

  • Last updated on