得到帮助！在 PowerShell 脚本中使用基于注释的帮助

当然，您已经在 PowerShell 脚本中使用了注释，并且您肯定也对未注释的脚本感到恼火。

PowerShell 脚本中的注释使得可以直接在代码中记录某些流程。此外，可以在代码片段中添加额外的注释 - 例如，如果要通过其他功能来扩展某个功能。

但除了这些纯粹的信息内容之外，PowerShell 中的注释如果使用得当，还可以用于有关您的函数的帮助文章。在本文中，我将向您展示如何使用元数据通过 Get-Help获取脚本信息。

基于评论的帮助关键字

我们项目的神奇词是基于注释的帮助。

顾名思义，这种方法允许我们通过注释生成帮助信息。这些注释必须正确排列和格式化 - 您将在本节中准确了解如何排列和格式化。

原则上，我们可以区分两种类型： 函数和脚本。前者更深入一层，从函数开始，我们希望为函数提供元数据。但是，如果您的代码未在函数中准备，也可以提供包含此信息的整个脚本。

在我们查看它们的确切用法之前，我在此处列出了基于注释的帮助的所有关键字：

功能

脚本或函数的简短描述

代码详细说明

使用的参数的描述。关键字使用多次（每个参数 1 次）。参数必须在关键字之后另外命名！

可以通过管道传递到函数中的可能对象的描述。

函数的输出值

有关代码的附加信息

相应在线帮助的 URL（如果有）

为了不超出本文的范围，我将列出最常用的关键字。您可以在 Microsoft Docs 中找到更多关键字。

注意：脚本头信息对于ScriptRunner软件平台中脚本的使用也起着重要作用。您可以在此处阅读有关它的更多信息：用于 ScriptRunner 的 PowerShell 脚本标头和参数。

使用基于注释的帮助

上面列出的关键字在代码中以特定格式表示。这看起来像下面这样：

PowerShell 脚本标头中帮助关键字和内容的表示法

关键字以句点开头 - 相应的文本位于关键字下方。关键字块使用“”进行注释。

基于注释的脚本和函数的不同之处在于注释块的放置方式不同。对于函数，最好将块放在函数名称下。其他可能性是将块直接放置在函数前面（没有空行）或函数体的末尾。

如果要为脚本配备信息，则直接设置注释块在代码的开头 - 从逻辑上讲，这还包含有关整个脚本的信息，而不是有关部分部分的信息。

基于注释的帮助的示例和用法

下面，我们将展示如何在实践中使用基于注释的帮助，通过输出特定目录的所有目录和文件对象到特定层次结构深度的函数。

PowerShell 已经提供了此功能 - 以下示例仅用于理解。

示例函数

现在的目标是通过帮助文章中的描述、示例和参数信息来描述功能。

函数头中的元数据

在此代码中，现已编写了整体帮助注释。在对此信息进行 Get-Help 调用时，我们现在在控制台中获得以下输出：

Get-Help Get-ChildItemDepth 的输出

-Examples 参数也可用于输出所有可用示例：

存储在脚本中的示例的输出

提示：有关根据 PowerShell 最佳实践构建的脚本的更多示例，请查看我们的 ScriptRunner ActionPack。

结论

原则上，可以说基于注释的帮助为 IT 部门带来了巨大的好处。不仅你自己可以快速了解自建功能，而且同事也不必费尽心思通过无数行代码来猜测基本功能。

由于长度有限，脚本名称只能粗略地指示脚本的功能，而无法提供详细信息。这种创建帮助的方式还节省了对代码外部文档的需求。

如果有明确要求使用这些帮助部分的基本政策或行为准则，我可以强烈推荐 Pester 模块。可以将其配置为在每次发布之前检查代码是否存在帮助文章。您甚至可以检查每个参数是否都有描述。