about_CommonParameters

简短说明

介绍可与任何 cmdlet 一起使用的参数。

详细说明

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

可以将通用参数与任何 cmdlet 结合使用，但它们可能不会对所有 cmdlet 都产生效果。 例如，如果 cmdlet 不生成任何详细输出，则使用 Verbose 公共参数不起作用。

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

多个通用参数会重写使用 PowerShell 首选项变量设置的系统默认值或首选项。 与首选项变量不同，通用参数仅影响使用它们的命令。

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

以下列表显示通用参数。 它们的别名列在括号中。

• Debug （db）
• ErrorAction （ea）
• ErrorVariable （ev）
• InformationAction （infa）
• InformationVariable （四）
• OutVariable （ov）
• OutBuffer （ob）
• PipelineVariable （pv）
• ProgressAction （proga）
• Verbose （vb）
• WarningAction （wa）
• WarningVariable （wv）

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

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

除了通用参数之外，许多 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。

该参数将替代当前命令变量的值，并将值设置为 < a0/>。

-Debug:$true 的效果与 -Debug 相同。 用于-Debug:$false禁止显示调试消息（$DebugPreferenceSilentlyContinue不是默认值）。

-错误作

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

-错误变量

错误记录自动存储在自动变量中 $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 中引入。 在使用该命令或脚本的命令或脚本中， 通用参数将替代首选项变量的值 ，该变量默认设置为 < a0/>。 在 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 不起作用，因为（默认）不会显示信息性消息，并且脚本将继续执行而不会中断。

-信息变量

在 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。

以下示例交替显示使用 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

-管道变量

PipelineVariable 允许使用此参数的命令访问传入下一个管道段的最新值。 管道中的任何命令都可以使用命名 PipelineVariable值访问该值。 当变量传递到下一个管道段时，该值将赋给变量。 这比 PipelineVariable 特定的临时变量更容易使用，这可能需要在多个位置分配。

与上述命令不同 $_ ，或者 $PSItem，使用 PipelineVariable 允许任何管道命令访问前面命令以外的命令传递的管道值（并保存）。 管道命令可以访问在处理通过管道传递的下一项时通过管道传递的最后一个值。 这样，命令就可以 将输出源回 上一个命令（或本身）。

Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

有效值为字符串，对于任何变量名称也是如此。

以下示例演示了工作 PipelineVariable 原理。 在此示例中，五个数字通过管道传递到第一个 ForEach-Object 命令中。 管道中的每个项都存储在名为 <a0/a0> 的管道变量中。

第 Process 一个 ForEach-Object 命令的块将管道项传递给下游 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

问题 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 生成的进度栏。 Write-Progress cmdlet 创建显示命令状态的进度栏。 参数 ProgressAction 已添加到 PowerShell 7.4 中。

该ProgressAction参数采用枚举ActionPreference值之一：SilentlyContinue、、Stop、Continue、Inquire、Ignore、或SuspendBreak。

有效值如下：

• 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 显示警告消息并停止执行命令。

-警告变量

将有关命令的警告记录存储在指定的变量中。

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 响应选项如下所示：

该 Suspend 选项将命令置于保留状态，并创建一个临时嵌套会话，你可以在其中工作，直到你准备好选择一个选项 Confirm 。 嵌套会话的命令提示符有两个额外的插入点 (>>)，指示它是原始父命令的子操作。 可以在嵌套会话中运行命令和脚本。 若要结束嵌套会话并返回到原始命令的 Confirm 选项，请键入“exit”。

在以下示例中， Suspend 选项（S）用于在用户检查命令参数的帮助时暂时停止命令。 获取所需信息后，用户键入“exit”以结束嵌套提示，然后对 Confirm 查询选择“是”(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
• 写-Debug
• 写入错误
• 写-Verbose
• 写入警告