PowerShell 博客周：支持WhatIf 和Confirm

我们希望您喜欢社区博客中的这个实验。在今天的贡献中，我想演示如何向高级 PowerShell 函数添加对 WhatIf 和Confirm 的支持。这实际上非常简单，特别是如果您的函数只是调用其他已经支持 -Whatif 和 -Confirm 的 PowerShell 命令。推荐的最佳实践是，如果您的函数将执行任何更改操作，则它应该支持这些参数。就是这样。

在您的函数中，您需要使用 cmdletbinding 属性并指定 SupportsShouldProcess。

[cmdletbinding(SupportsShouldProcess)]

从 PowerShell 3.0 开始，这就是您所需要的，但您会看到脚本编写者明确将其设置为 $True。

[cmdletbinding(SupportsShouldProcess=$True)]

很好，尽管我个人认为这是多余的。如果列出了 SupportsShouldProcess，则默认情况下它为 True。无需显式将其设置为 $False。简单地省略它。添加此属性时，您将自动获取 -WhatIf 和 -Confirm 参数。最好的部分是，如果您的函数只是调用已经支持 -WhatIf 的 PowerShell cmdlet，它们将自动继承此设置。这是一个示例函数。

#requires -version 4.0

Function Remove-TempFile {
[cmdletbinding(SupportsShouldProcess)]

Param(
[Parameter(Position=0)]
[ValidateScript({Test-Path $_})]
[string]$Path = $env:temp
)

#get last bootup time
$LastBoot = (Get-CimInstance -ClassName Win32_OperatingSystem).LastBootUptime
Write-Verbose "Finding all files in $path modified before $lastboot"

(Get-Childitem -path $path -File).Where({$_.lastWriteTime -le $lastboot}) | Remove-Item

} #end function

该功能会删除 %TEMP% 文件夹中上次修改时间早于上次启动时间的所有文件。正如您在帮助中看到的，PowerShell 添加了必要的参数。

当我使用 -Whatif 运行该函数时，它被传递给 Remove-Item。

真的就是这么简单。我还会自动获得对 -Confirm 的支持。

当您想要为您的命令本身无法识别 SupportsShouldProcess 的函数支持 WhatIf 时，事情会变得有点棘手。对于任何 .NET 静态方法甚至您可能正在运行的命令行工具来说都是如此。仅举几个例子。要添加您自己的支持，您需要调用内置 $PSCmdlet 对象及其 ShouldProcess() 方法。这是一个简单的例子。

Function Set-Folder {
[cmdletbinding(SupportsShouldProcess)]

Param(
[Parameter(Position=0,
ValueFromPipeline,
ValueFromPipelineByPropertyName)]
[Alias("pspath")]
[ValidateScript({Test-Path $_})]
[string]$Path=".")

Process {
$Path = (Resolve-Path -Path $Path).ProviderPath
if ($PSCmdlet.ShouldProcess($Path)) {
#do the action
$Path.ToUpper()
}
} #Process

} #end function

假设这个函数将对文件夹执行一些操作，我只是以大写形式显示文件夹名称。重要的部分是 If 语句。这是您需要的最低限度。如果您指定 -WhatIf，系统会提示您。

该操作将是您的脚本或函数的名称。目标是 ShouldProcess 参数值，在我的示例中是路径。但是您可以通过为目标和操作指定 ShouldProcess 参数来提供更具体的信息。这是修改后的函数。

Function Set-Folder2 {
[cmdletbinding(SupportsShouldProcess)]

Param(
[Parameter(Position=0,
ValueFromPipeline,
ValueFromPipelineByPropertyName)]
[Alias("pspath")]
[ValidateScript({Test-Path $_})]
[string]$Path=".")

Process {
$Path = (Resolve-Path -Path $Path).ProviderPath
if ($PSCmdlet.ShouldProcess($Path,"Updating")) {
#do the action
$Path.ToUpper()
}
} #Process

} #end function

您必须拥有 ShouldProcess 的代码，否则即使您设置了 cmdletbinding 属性，PowerShell 也不会知道哪些命令需要 WhatIf。您还可以根据需要拥有任意数量的 ShouldProcess 语句。

当涉及到确认时，事情会变得有点棘手，这可能取决于您真正需要什么。正如您在上面看到的，任何支持 -Confirm 的 cmdlet 都应该自动继承该设置。这是有效的，因为还有另一个名为ConfirmImpact 的cmdlet 绑定属性，其默认值为Medium。其他选项有低和高。我的第一个函数也可以这样写：

[cmdletbinding(SupportsShouldProcess,ConfirmImpact="medium ")]

通过将ConfirmImpact 的值与默认值为High 的内置$ConfirmPreference 变量进行比较来进行确认。如果$ConfirmPreference的值等于或大于ConfirmImpact，PowerShell将提示确认。让我们测试一下。

Function Set-Folder6 {
[cmdletbinding(SupportsShouldProcess,ConfirmImpact="High")]

Param(
[Parameter(Position=0,
ValueFromPipeline,
ValueFromPipelineByPropertyName)]
[Alias("pspath")]
[ValidateScript({Test-Path $_})]
[string]$Path="."
)
Begin {
Write-Verbose "Starting $($MyInvocation.Mycommand)"
} #begin

Process {
$Path = (Resolve-Path -Path $Path).ProviderPath
Write-Verbose "Processing $path"
if ($PSCmdlet.ShouldProcess($Path,"Updating")) {
#do the action
$Path.ToUpper()
} #ShouldProcess
} #Process

End {
Write-Verbose "Ending $($MyInvocation.Mycommand)"
} #end

} #end function

请注意，我也使用 WhatIf。在此函数中，ConfirmImpact 设置为高，这意味着 PowerShell 将始终进行提示。

如果我编辑该函数并将ConfirmImpact更改为Medium或Low，那么PowerShell只会在我询问时才会确认。

您不必为 cmdlet 绑定指定任何内容。如果你知道你总是想要确认，你可以这样做：

Function Set-Folder4 {
[cmdletbinding()]

Param(
[Parameter(Position=0,
ValueFromPipeline,
ValueFromPipelineByPropertyName)]
[Alias("pspath")]
[ValidateScript({Test-Path $_})]
[string]$Path=".",
[switch]$Force
)

Process {
$Path = (Resolve-Path -Path $Path).ProviderPath
Write-Verbose "Processing $path"
if ($Force -OR $PSCmdlet.ShouldContinue("Do you want to continue modifying folder?",$path)) {
#do the action
$Path.ToUpper()
}
} #Process

} #end function

请注意 ShouldContinue 方法的使用。当我运行此函数时，PowerShell 将始终提示确认。

我还添加了一个名为 Force 的开关参数，这样如果指定了该参数，则不会提示用户进行确认。

这种方法的缺点是帮助无法显示任何内容。

也许在特殊情况下这就是您想要的。就我个人而言，我认为您最好使用 cmdletbinding 属性，就像我在 Set-Folder6 示例中所做的那样。

添加对WhatIf和Confirm的支持并不需要太多努力，它会将您的高级功能提升到一个新的水平。

这篇文章是有关 Windows PowerShell 高级功能的 PowerShell 博客周系列的一部分，这是一系列协调一致的文章，旨在提供特定主题的全面视图。

本系列的其他文章：

• 标准和高级功能 作者：Francois-Xavier Cat
• PowerShell 高级功能：我们可以更好地构建它们吗？作者：Mike F. Robbins
• Adam Bertram 的动态参数和参数验证
• 创建帮助和评论 作者： June Blender
• Try/Catch 和基本错误处理，作者：Boe Prox

我们希望您发现我们的工作值得您花时间。