about_CommonParameters

简短说明

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

长说明

常见参数是一组 cmdlet 参数,可用于任何 cmdlet。 它们由 PowerShell 实现,而不是由 cmdlet 开发人员实现,并且它们会自动提供给任何 cmdlet。

可以将通用参数用于任何 cmdlet,但它们可能对所有 cmdlet 没有影响。 例如,如果 cmdlet 不生成任何详细输出,则 Verbose 使用通用参数不起作用。

公共参数也可用于使用 CmdletBinding 属性或 Parameter 属性的高级函数。

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

有关详细信息,请参阅 about_Preference_Variables

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

  • Debug (db)
  • ErrorAction (ea)
  • ErrorVariable (ev)
  • InformationAction (infa)
  • InformationVariable (iv)
  • OutVariable (ov)
  • OutBuffer (ob)
  • PipelineVariable (pv)
  • Verbose (vb)
  • WarningAction (wa)
  • WarningVariable (wv)

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

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

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

除了常见参数之外,许多 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

默认情况下,不显示调试消息,因为变量的值 $DebugPreferenceSilentlyContinue

在交互模式下,参数 Debug 将替代当前命令的变量值 $DebugPreference ,并将值 $DebugPreference 设置为 “查询”。

在非交互式模式下,参数 Debug 将替代当前命令变量的值 $DebugPreference ,并将值 $DebugPreference 设置为 “继续”。

-Debug:$true 的效果 -Debug与 . 用于-Debug:$false在不是 SilentlyContinue$DebugPreference禁止显示调试消息,这是默认值。

-ErrorAction

确定 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 默认值为 “继续”,因此除非使用 ErrorAction 参数,否则会显示错误消息并继续执行。

ErrorAction 参数对终止错误 (没有影响,例如缺少数据、参数无效或权限不足) 阻止命令成功完成。

-ErrorAction:Break 当发生错误或引发异常时,输入调试器。

-ErrorAction:Continue 显示错误消息并继续执行命令。 Continue 是默认值。

-ErrorAction:Ignore 禁止显示错误消息并继续执行命令。 与 SilentlyContinue 不同, Ignore 不会将错误消息添加到 $Error 自动变量。 PowerShell 3.0 中引入了 Ignore 值。

-ErrorAction:Inquire 显示错误消息,并在继续执行之前提示你进行确认。 此值很少使用。

-ErrorAction:SilentlyContinue 禁止显示错误消息并继续执行命令。

-ErrorAction:Stop 显示错误消息并停止执行命令。

-ErrorAction:Suspend 仅适用于 PowerShell 6 及更高版本不支持的工作流。

备注

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

-ErrorVariable

ErrorVariable 将有关命令的错误消息存储在指定变量和自动变量中 $Error 。 有关详细信息,请参阅 about_Automatic_Variables

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。 在Write-Information包含 InformationAction 的脚本中使用时,Write-Information将根据 InformationAction 参数的值显示值。 有关详细信息 $InformationPreference,请参阅 about_Preference_Variables

Type: ActionPreference
Aliases: ia
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

-InformationAction:Break 在命令出现 Write-Information 时输入调试器。

-InformationAction:Stop 在命令出现 Write-Information 时停止命令或脚本。

-InformationAction:Ignore 取消信息性消息并继续运行命令。 与 SilentlyContinue 不同, 忽略 完全忘记信息性消息;它不会将信息性消息添加到信息流。

-InformationAction:Inquire 显示你在命令中指定的 Write-Information 信息性消息,然后询问是否要继续。

-InformationAction:Continue 显示信息性消息,并继续运行。

-InformationAction:Suspend PowerShell 6 及更高版本不支持,因为它仅适用于工作流。

-InformationAction:SilentlyContinue 由于信息性消息未 (默认) 显示,因此不会造成任何影响,并且脚本不会中断。

备注

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

-InformationVariable

PowerShell 5.0 中引入。 在使用该命令的命令或脚本中, InformationVariable 通用参数存储在通过添加 Write-Information 命令指定的字符串的变量中。 Write-Information 根据 InformationAction 公共参数的值显示值;如果未添加 InformationAction 通用参数, Write-Information 则根据首选项变量的值 $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 + 1cmdlet。

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

备注

OutVariable 参数创建的变量是一个 [System.Collections.ArrayList]

-PipelineVariable

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

与管道变量不同 $_ ,或者 $PSItem,使用 PipelineVariable 允许任何管道命令访问通过 (传递的管道值,并通过命令以外的命令) 保存。 管道命令可以访问通过管道传递的下一项时通过管道传递的最后一个值。 这样,命令就可以 (或本身) 将其输出源回 上一个命令。

备注

高级函数最多可以有三个脚本块:beginprocess,以及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 ,则只有一个共享变量。 该变量使用指定变量的命令的最新管道输出进行更新。

某些 阻止 命令在生成任何输出之前收集所有管道项,例如 Sort-ObjectSelect-Object -Last。 在此类阻塞命令之前在命令中分配的任何 PipelineVariable 始终包含在阻止命令后在命令中使用时,上述命令的最终管道项。

下面是 PipelineVariable 的工作原理示例。 在此示例中, PipelineVariable 参数将添加到 Foreach-Object 命令中,以将命令的结果存储在变量中。 A range of numbers, 1 to 5, are piped into the first Foreach-Object command, the results of which are stored in a variable named $temp.

第一 Foreach-Object 个命令的结果通过管道传递到第二 Foreach-Object 个命令中,该命令显示当前值 $temp$_

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

Get-Variable: Cannot find a variable with the name 'temp'.

-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 参数,否则会显示警告并继续执行。

-WarningAction:Break 出现警告时输入调试器。

-WarningAction:Continue 显示警告消息并继续执行命令。 Continue 是默认值。

-WarningAction:Inquire 显示警告消息,并在继续执行之前提示你进行确认。 此值很少使用。

-WarningAction:SilentlyContinue 禁止显示警告消息并继续执行命令。

-WarningAction: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] 引用存储在变量中的特定警告。

备注

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

风险管理参数说明

-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

-WhatIf:$true 的效果 -WhatIf与 .

-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

-Confirm:$true 的效果 -Confirm与 .

-Confirm:$false 取消自动确认,该值小于或等于 cmdlet 的估计风险时 $ConfirmPreference 发生。

例如,以下命令将 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 (?) 显示这些选项的帮助。

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

在以下示例中,当用户检查命令参数的帮助时,S) 的 Suspend (选项用于暂时停止命令。 获取所需信息后,用户键入“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

关键字

about_Common_Parameters

另请参阅