-Confirm、-Force 和 -WhatIf 的 PowerShell 指南

Question

Microsoft 是否有关于何时将 -Confirm、-Force 和 -WhatIf 参数添加到自定义 PowerShell cmdlet 的任何官方指南？关于何时/如何使用这些参数似乎没有明确的共识。例如this issue。

在没有正式指南的情况下，是否有最佳实践或经验法则可供使用？以下是更多背景信息，以及我目前（可能有缺陷）的理解：

-假设

-WhatIf 标志显示 cmdlet 会做什么而不实际执行任何操作。这对于潜在不稳定操作的空运行很有用，可以查看实际结果。如果 cmdlet 的 Cmdlet 属性将 SupportsShouldProcess 属性设置为 true，则会自动添加该参数。

如果您要添加或删除资源，您似乎应该添加-WhatIf（但我希望在这里看到更多官方指导）。 （例如删除文件。）更新现有资源的操作可能不会从中受益。对吧？

-强制

-Force 开关用于声明“我知道我在做什么，并且我确定我想这样做”。例如，在复制文件（Copy-File）时，-Force 参数表示：

允许 cmdlet 复制无法更改的项目，例如复制只读文件或别名。

所以对我来说，当您遇到 cmdlet 可能会失败但可以确信完成行动。

例如，如果您正在创建一个新资源，它将破坏现有的同名资源。 cmdlet 的默认行为将报告错误并失败。但是如果您添加-Force，它将继续（并覆盖现有资源）。对吧？

-确认

如果 cmdlet 将 SupportsShouldProcess 设置为 true，则会自动添加 -Confirm 标志，如 -WhatIf。在 cmdlet 中，如果您调用 ShouldProcess，则会提示用户执行操作。并且如果添加了-Confirm标志，则不会有提示。 （即通过 cmdlet 调用添加确认。）

因此，只要 cmdlet 对系统产生重大影响，-Confirm 就应该可用。就像-WhatIf 一样，每当添加或删除资源时都应该添加它。

考虑到我可能不正确的理解，以下是一些我想具体回答的问题：

• 什么时候需要添加-WhatIf/-Confirm？
• 什么时候需要添加-Force？
• 同时支持-Confirm 和-Force 是否有意义？

Answer 1

我没有研究文档是否如此详细，但以下是基于我的观察：

1. 您应该使用-WhatIf 进行任何更改。更新是可以从-WhatIf 中受益的更改（例如，如果您想进行大量更新怎么办？）。

2. -Force 表示“强制覆盖现有项目”或“覆盖只读文件系统属性”。在任何一种情况下，操作的成功都取决于具有权限的用户。

3. -Confirm 和 -Force 不相互排斥。例如，您可以确认写入文件的操作，但该文件可能受到只读属性的保护。在这种情况下，除非您还指定 -Force，否则操作将失败。

Answer 2

如果您想验证这些常用参数的实现是否符合指南（例如，Set-Xxx cmdlet 应该具有 -Confirm 和 -WhatIf），那么您可以使用出色的 PsScriptAnalyzer 模块（即基于代码分析）。

确保模块已安装：

PS E:\> Install-Module -Name 'PsScriptAnalyzer'

然后运行PowerShell代码分析如下：

PS E:\> Invoke-ScriptAnalyzer -Path . | FL

RuleName : PSUseShouldProcessForStateChangingFunctions
Severity : Warning 
Line     : 78 
Column   : 10 
Message  : Function 'Update-something' has verb that could change system state. 
           Therefore, the function has to support 'ShouldProcess'.

文档（和来源）可以在 GitHub 上找到： https://github.com/PowerShell/PSScriptAnalyzer

Answer 3

作为补充观察，-Force 不应推翻 -WhatIf。或者换句话说：-WhatIf 优先于 -Force。

如果你使用：

Get-ChildItem -Recurse | Remove-Item -Recurse -Force -WhatIf

这将导致以下输出：

如果：对目标“E:\some directory\”执行“删除目录”操作。

即使指定了-Force，它也不会真正删除项目。

这意味着你永远不应该写：

if($Force -or $Pscmdlet.ShouldProcess($)) {
    ...
}