通过

关于 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)
  • 详细 (vb)
  • WarningAction (wa)
  • WarningVariable (wv)

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

名称 值
挂起 5
忽略 4
查询 3
继续 2
Stop 1
SilentlyContinue 0

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

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

风险缓解参数包括：

  • WhatIf (wi)
  • 确认 (cf)

常见参数说明

调试

显示有关命令所执行的操作的程序员级详细信息。 仅当命令生成调试消息时，此参数才有效。 例如，当命令包含 cmdlet 时， Write-Debug 此参数有效。

Type: SwitchParameter
Aliases: db

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

默认情况下，不会显示调试消息，因为变量的 $DebugPreference 值为 SilentlyContinue。

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

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

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

ErrorAction

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

Type: ActionPreference
Aliases: ea
Accepted values: 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 参数对终止错误 (没有影响，例如缺少数据、无效参数或权限不足) 导致命令无法成功完成。

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

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

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

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

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

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

注意

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

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: 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:Stop 在命令出现 Write-Information 时停止命令或脚本。

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

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

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

-InformationAction:Suspend PowerShell Core 不支持，因为它仅适用于工作流。

-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 处理使用 Write-Host cmdlet 的块。 显示以 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 将当前管道元素的值存储为变量，用于流经管道的任何命名命令。

Type: String
Aliases: pv

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

有效值为字符串，与任何变量名称相同。

下面是 PipelineVariable 工作原理的示例。 在此示例中， PipelineVariable 参数添加到命令中， Foreach-Object 以将命令的结果存储在变量中。 数字范围（1 到 10）通过管道传递到第一 Foreach-Object 个命令中，其结果存储在名为 Left 的变量中。

第一个 Foreach-Object 命令的结果通过管道传递到第二 Foreach-Object 个命令中，这将筛选第一个 Foreach-Object 命令返回的对象。 第二个命令的结果存储在名为 Right 的变量中。

在第三 Foreach-Object 个命令中，前两 Foreach-Object 个管道命令的结果（由变量 Left 和 Right 表示）使用乘法运算符进行处理。 命令指示左变量和右变量中存储的对象相乘，并指定结果应显示为“左范围成员 * 右范围成员 = 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
...

详细

显示有关命令执行的操作的详细信息。 此信息类似于跟踪或事务日志中的信息。 仅当命令生成详细消息时，此参数才有效。 例如，当命令包含 cmdlet 时， Write-Verbose 此参数有效。

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 如何响应来自 命令的警告。 Continue 是默认值。 仅当命令生成警告消息时，此参数才有效。 例如，当命令包含 cmdlet 时， Write-Warning 此参数有效。

Type: ActionPreference
Aliases: wa
Accepted values: 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: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 行为。

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

Remove-Item Date.csv -WhatIf

PowerShell 不会删除项，而是列出它将执行的操作以及将受影响的项。 该命令生成以下输出：

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

确认

在执行命令前提示您进行确认。

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 禁止自动确认，当 的值 $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) ： 不要执行该操作。
No 到 All (L) ： 不执行任何操作并禁止后续确认
查询此命令。
挂起 (S) ： 暂停命令并创建临时会话。
帮助 (？) 显示这些选项的帮助。

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

另请参阅

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose