关于 CommonParameters

  • 项目

简短说明

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

详细说明

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

可以将通用参数与任何 cmdlet 一起使用，但它们可能不会对所有 cmdlet 产生影响。 例如，如果 cmdlet 未生成任何详细输出，则使用 Verbose 通用参数不起作用。

使用 CmdletBinding 属性或 Parameter 属性的高级函数以及所有工作流上也提供了通用参数。

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

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

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

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

风险缓解参数包括：

  • WhatIf (wi)
  • 确认 (cf)

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

常见参数说明

调试

Debug 的别名为 db。

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

Debug 参数替代当前命令的$DebugPreference变量的值，并将 的值$DebugPreference设置为 Continue。 由于变量的 $DebugPreference 默认值为 SilentlyContinue，因此默认情况下不会显示调试消息。

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

ErrorAction

ErrorAction 的别名为 ea。

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

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 Core 不支持，因为它仅适用于工作流。

注意

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

ErrorVariable

ErrorVariable 的别名为 ev。

ErrorVariable 将有关命令的错误消息存储在指定的变量和自动变量中 $Error 。 有关详细信息，请键入以下命令：

Get-Help about_Automatic_Variables

默认情况下，新的错误消息将覆盖已存储在 变量中的错误消息。 若要将错误消息追加到变量内容，请在变量名称前键入加号 (+) 。

例如，以下命令创建 变量， $a 然后将任何错误存储在其中：

Get-Process -Id 6 -ErrorVariable a

以下命令将任何错误消息添加到 $a 变量：

Get-Process -Id 2 -ErrorVariable +a

以下命令显示 的内容 $a：

$a

可以使用此参数创建一个变量，该变量仅包含来自特定命令的错误消息。 自动 $Error 变量包含来自会话中所有命令的错误消息。 可以使用数组表示法（如 $a[0] 或 $error[1,2] ）来引用存储在变量中的特定错误。

InformationAction

InformationAction 的别名为 ia。

在 PowerShell 5.0 中引入。 在使用它的命令或脚本中， InformationAction 公共参数将覆盖首选项变量的值 $InformationPreference ，默认情况下，首选项变量设置为 SilentlyContinue。 在Write-Information脚本中使用 InformationAction 时，Write-Information根据 InformationAction 参数的值显示值。 有关 的详细信息 $InformationPreference，请参阅 about_Preference_Variables。

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

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

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

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

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

-InformationAction:SilentlyContinue 没有影响，因为信息性消息不会 (默认) 显示，并且脚本继续不中断。

注意

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

InformationVariable

InformationVariable 的别名为 iv。

在 PowerShell 5.0 中引入。 在使用它的命令或脚本中， InformationVariable 通用参数在变量中存储一个通过添加 Write-Information 命令指定的字符串。 Write-Information 值根据 InformationAction 通用参数的值显示;如果未添加 InformationAction 通用参数， Write-Information 则会根据首选项变量的值 $InformationPreference 显示字符串。 有关 的详细信息 $InformationPreference，请参阅 about_Preference_Variables。

OutBuffer

OutBuffer 的别名为 ob，采用 System.Int32 值。

确定在通过管道发送任何对象之前，缓冲区中要累积的对象数。 如果省略此参数，则会在生成对象时发送对象。

此资源管理参数专为高级用户设计。 使用此参数时，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

OutVariable 的别名为 ov。

除了沿管道发送输出外，还将命令的输出对象存储在指定的变量中。

若要将输出添加到变量，而不是替换可能已存储在那里的任何输出，请在变量名称之前键入加号 (+) 。

例如，以下命令创建 变量并将 $out 进程对象存储在其中：

Get-Process PowerShell -OutVariable out

以下命令将进程对象添加到 $out 变量：

Get-Process iexplore -OutVariable +out

以下命令显示 变量的内容 $out ：

$out

注意

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

PipelineVariable

PipelineVariable 的别名为 pv，采用字符串值。

PipelineVariable 将当前管道元素的值存储为变量，用于流经管道的任何命名命令。

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

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

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

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

详细

Verbose 的别名为 vb。

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

Verbose 参数替代当前命令的 $VerbosePreference 变量的值。 由于变量的 $VerbosePreference 默认值为 SilentlyContinue，因此默认情况下不会显示详细消息。

-Verbose:$true 效果与 -Verbose

-Verbose:$false 禁止显示详细消息。 如果 的值 $VerbosePreference 不是 SilentlyContinue (默认) ，请使用此参数。

WarningAction

WarningAction 的别名为 wa。

确定 cmdlet 如何响应命令中的警告。 Continue 是默认值。 仅当命令生成警告消息时，此参数才有效。 例如，当命令包含 cmdlet 时， Write-Warning 此参数有效。

WarningAction 参数替代当前命令的 $WarningPreference 变量的值。 由于变量的 $WarningPreference 默认值为 Continue，因此除非使用 WarningAction 参数，否则将显示警告并继续执行。

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

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

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

-WarningAction:Stop 显示警告消息并停止执行命令。

注意

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

WarningVariable

WarningVariable 的别名为 wv。

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

即使未向用户显示警告，所有生成的警告也会保存在 变量中。

若要将警告追加到变量内容，而不是替换可能已存储在那里的任何警告，请在变量名称之前键入加号 (+) 。

例如，以下命令创建 变量， $a 然后在其中存储任何警告：

Get-Process -Id 6 -WarningVariable a

以下命令将任何警告添加到 $a 变量：

Get-Process -Id 2 -WarningVariable +a

以下命令显示 的内容 $a：

$a

可以使用此参数创建一个仅包含来自特定命令的警告的变量。 可以使用数组表示法（如 $a[0] 或 $warning[1,2] ）来引用存储在变量中的特定警告。

注意

WarningVariable 参数不会捕获函数或脚本中嵌套调用的警告。

风险管理参数说明

WhatIf

WhatIf 的别名为 wi。

显示描述命令效果的消息，而不是执行命令。

WhatIf 参数替代当前命令的 $WhatIfPreference 变量的值。 由于变量的 $WhatIfPreference 默认值为 0 (禁用) ， 因此如果没有 WhatIf 参数，则不会执行 WhatIf 行为。 有关详细信息，请键入以下命令：

Get-Help 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".

确认

Confirm 的别名为 cf。

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

Confirm 参数替代当前命令的 $ConfirmPreference 变量的值。 默认值为 true。 有关详细信息，请键入以下命令：

Get-Help 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