关于通用参数

简短描述

描述可与任何 cmdlet 一起使用的参数。

详细描述

通用参数是一组可与任何 cmdlet 一起使用的 cmdlet 参数。它们由 PowerShell 实现，而不是由 cmdlet 开发人员实现，并且它们自动可供任何 cmdlet 使用。

您可以对任何 cmdlet 使用通用参数，但它们可能不会对所有 cmdlet 产生影响。例如，如果 cmdlet 不生成任何详细输出，则使用 Verbose 通用参数无效。

使用 CmdletBinding 属性或 Parameter 属性的高级函数也可以使用通用参数。当您使用这些属性时，PowerShell 会自动添加通用参数。您不能创建任何与公共参数使用相同名称的参数。

几个常见参数会覆盖系统默认值或您使用 PowerShell 首选项变量设置的首选项。与首选项变量不同，公共参数仅影响使用它们的命令。

有关详细信息，请参阅 about_Preference_Variables。

以下列表显示了常用参数。他们的别名列在括号中。

• 调试 (db)
• 错误操作 (ea)
• 错误变量 (ev)
• 信息操作 (infa)
• 信息变量 (iv)
• 输出变量 (ov)
• 输出缓冲区 (ob)
• 管道变量 (pv)
• ProgressAction（proga）
• 详细 (vb)
• 警告操作 (wa)
• 警告变量 (wv)

Action 参数是 ActionPreference 类型值。 ActionPreference 是一个具有以下值的枚举：

6

5

4

3

2

1

0

您可以将名称或值与参数一起使用。

除了通用参数之外，许多 cmdlet 还提供风险缓解参数。涉及系统或用户数据风险的 cmdlet 通常会提供这些参数。

风险缓解参数为：

• 假设 (wi)
• 确认（参见）

常用参数说明

-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 效果相同。当 $DebugPreference 不是默认值 SilentlyContinue 时，使用 -Debug:$false 禁止显示调试消息。

-ErrorAction

确定 cmdlet 如何响应命令中的非终止错误。仅当命令生成非终止错误（例如来自 Write-Error cmdlet 的错误）时，此参数才有效。

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 显示错误消息并继续执行命令。 继续 是默认值。
• Ignore 抑制错误消息并继续执行命令。与SilentlyContinue不同，Ignore不会将错误消息添加到$Error自动变量中。 忽略值是在 PowerShell 3.0 中引入的。
• Inquire 显示错误消息并提示您确认后再继续执行。该值很少使用。
• SilentlyContinue 抑制错误消息并继续执行命令。
• Stop 显示错误消息并停止执行命令。
• 挂起 仅适用于 PowerShell 6 及更高版本不支持的工作流。

笔记

当在命令中使用参数来运行脚本或函数时，ErrorAction 参数会覆盖但不替换 $ErrorActionPreference 变量的值。

-ErrorVariable

错误记录自动存储在$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] 来引用变量中存储的特定错误。

笔记

自定义错误变量包含命令生成的所有错误，包括调用嵌套函数或脚本产生的错误。

-InformationAction

在 PowerShell 5.0 中引入。在使用它的命令或脚本中，InformationAction 公共参数会覆盖 $InformationPreference 首选项变量的值，该变量默认设置为 SilentlyContinue。当您在带有 InformationAction 的脚本中使用 Write-Information 时，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 显示信息性消息，并继续运行。
• PowerShell 6 及更高版本不支持 Suspend，因为它仅适用于工作流。
• SilentlyContinue 没有效果，因为未显示信息性消息（默认），并且脚本会继续执行而不会中断。

笔记

当在命令中使用参数来运行脚本或函数时，InformationAction 参数会覆盖但不替换 $InformationAction 首选项变量的值。

-InformationVariable

在 PowerShell 5.0 中引入。当使用InformationVariable公共参数时，信息记录存储在该参数指定的变量中。 PowerShell cmdlet 可以将信息记录写入信息流。您还可以使用Write-Information cmdlet 写入信息记录。

默认情况下，信息记录在控制台中显示为消息。您可以通过InformationAction公共参数来控制信息记录的显示。您还可以使用 $InformationPreference 首选项变量更改行为。有关 $InformationPreference 的详细信息，请参阅 about_Preference_Variables。

笔记

information 变量包含命令生成的所有信息消息，包括调用嵌套函数或脚本的信息消息。

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。

以下示例在使用 Write-Host cmdlet 的 ForEach-Object 进程块之间交替显示。显示以 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 和 $temp 的当前值。代码>$_。

# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created isn't 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

Name                           Value
----                           -----
temp

-ProgressAction

确定 PowerShell 如何响应脚本、cmdlet 或提供程序生成的进度更新，例如 Write-Progress cmdlet 生成的进度条。 Write-Progress cmdlet 创建显示命令状态的进度条。 PowerShell 7.4 中添加了 ProgressAction 参数。

ProgressAction 参数采用 ActionPreference 枚举值之一：SilentlyContinue、Stop、Continue、查询、忽略、暂停或中断。

有效值如下：

• Break 在出现 Write-Progress 命令时进入调试器。
• Stop：不显示进度条。相反，它会显示一条错误消息并停止执行。
• 查询：不显示进度条。提示允许继续。如果您回复 Y 或 A，则会显示进度条。
• 继续：（默认）显示进度条并继续执行。
• 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（默认值）时使用此参数。

-WarningAction

确定 cmdlet 如何响应命令的警告。 继续是默认值。该参数仅在命令生成警告消息时起作用。例如，当命令包含 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 显示警告消息并继续执行命令。 继续 是默认值。
• Inquire 显示警告消息并提示您确认后再继续执行。该值很少使用。
• SilentlyContinue 抑制警告消息并继续执行命令。
• 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] 来引用存储在变量中的特定警告。

笔记

warning 变量包含命令生成的所有警告，包括调用嵌套函数或脚本的警告。

风险管理参数说明

-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 行为。

例如，以下命令在 Remove-Item 命令中使用 -WhatIf 参数：

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"):

确认响应选项如下：

执行该操作。

执行所有操作并抑制后续确认

查询此命令。

不要执行该操作。

不执行任何操作并抑制后续操作

确认此命令的查询。

暂停命令并创建临时会话。

显示这些选项的帮助。

暂停选项会暂停命令并创建一个临时嵌套会话，您可以在其中工作，直到准备好选择确认选项。嵌套会话的命令提示符有两个额外的插入符 (>>)，以指示它是原始父命令的子操作。您可以在嵌套会话中运行命令和脚本。要结束嵌套会话并返回到原始命令的确认选项，请键入“exit”。

在以下示例中，挂起选项 (S) 用于在用户检查命令参数的帮助时暂时停止命令。获得所需信息后，用户键入“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_Preference_Variables
• Write-Debug
• Write-Error
• Write-Verbose
• Write-Warning