如何为 PowerShell 脚本编写基于注释的帮助

本文演示了如何为脚本和函数编写基于注释的帮助主题。我们将使用特殊的帮助注释关键字来创建主题。

我们使用 Get-Help 命令来显示基于注释的帮助主题，这些主题类似于 XML 文件生成的主题。

PowerShell 中的基于注释的帮助

下面是基于注释的帮助的语法示例。

# .<help keyword>
# <help content>

或

<#
.<help keyword>
<help content>
#>

我们将基于注释的帮助主题写成一系列注释。要标记注释，我们可以在每个注释行的开头添加 # 符号，或者使用 <# 和 #> 创建注释块。

控制台将把注释块中的行注册为注释。

我们使用特殊关键字来定义基于注释的主题帮助的每个部分。关键字以 . 开头并且不区分大小写。

以下是一个示例：

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

在上面的示例中，.Description 关键字将注释标记为我们函数的描述。

注释块必须至少包含一个关键字。一些关键字只出现一次，而另一些则没有限制。

关键字的内容应在关键字后面的行开始，并且没有限制。

在为函数添加基于注释的帮助时，可以在下面讨论的三个位置中的任何一个添加。

1. 在函数主体的开始。
2. 在函数主体的末尾。
3. 在 function 关键字之前。相隔不超过一行空白。

示例：

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

或

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

或

<#
.<help keyword>
<content>
#>
function Get-Function { }

脚本的基于注释的帮助可以出现在脚本的开头或末尾。以下是一些示例：

<#
.<help keyword>
<content>
#>

function Get-Function { }

或

function Get-Function { }

<#
.<help keyword>
<content>
#>

PowerShell 中的基于注释的关键字

下面列出了有效的基于注释的帮助关键字。它们可以按任何顺序出现，并且不区分大小写。

.SYNOPSIS

这是对函数或脚本的简短描述。该关键字在每个主题中只应出现一次。

.DESCRIPTION

这是对函数或脚本的详细描述。我们在每个主题中仅使用一次。

.PARAMETER

这描述了您脚本或函数中的参数。我们为脚本或函数中的每个参数添加一个 .PARAMETER 关键字。

.PARAMETER <Parameter-Name>

参数关键字在注释块中不遵循严格的顺序。脚本或函数中参数的语法将决定帮助主题中的顺序。

您可以通过更改语法来更改顺序。

我们可以通过在函数或脚本中添加注释来指定参数关键字的内容。此注释应在参数变量名称之前。

PowerShell 优先考虑与参数关键字相关的描述，而不是在同时使用时的语法注释。

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

包括一个使用脚本或函数的示例命令。我们可以对脚本或函数中的所有示例包含此关键字。

.INPUTS

这些是我们可以传递给脚本或函数的 .NET 对象。我们可以对输入对象添加描述。

.OUTPUTS

这些是我们的 cmdlet 返回的 .NET 对象。我们可以对返回的对象添加描述。

.NOTES

这些是关于脚本或函数的任何附加信息。信息可以包括编写日期、函数名称或创建者的姓名。

.LINK

这些是相关主题。

以下是一个函数的基于注释的帮助示例：

总之，我们可以通过将基于注释的帮助放置在注释块中，在函数或脚本中添加基于注释的帮助。添加帮助主题时，请使用我们上述讨论的关键字，并记住将注释块放置在脚本和函数中的位置。