如何在PowerShell中编写基于注释的帮助？
在PowerShell中，当您创建复杂的脚本或函数时，必须为最终用户创建帮助以轻松理解您的脚本功能，这一点至关重要。最后，编写基于注释的帮助或基于XML的帮助与cmdlet或函数（在线帮助版本）的Get-Help语法相似。
例如，只需打开PowerShell控制台并运行以下命令。
Get-Help Get-WmiObject
并且您可以在输出中看到各个帮助部分，例如NAME，SYNOPSIS，SYNTAX，DESCRIPTION，PARAMETER，LINK。这些称为关键字。我们可以将它们全部手动包含在函数脚本中以获取帮助。每当我们使用help关键字时，都需要在其之前使用点(.)关键字。
当我们编写基于注释的帮助时，它应该在多行注释框<＃..＃>中。您也可以使用单行注释＃，但对于容易阅读和理解的用户，建议将其放在多行注释框中。
不必使用大写字母的语法，而是再次为了用户的可读性并区分关键字，我们将它们放入CAPS字母中。
以下是基于命令的帮助的结构。
<#
.HELP Keyword
HELP content
#>让我们一一理解一些必要的关键字。
.SYNOPSIS-功能或脚本的简要说明。在帮助部分，此关键字只能使用一次。
.DESCRIPTION-函数或脚本的详细描述。在帮助部分，此关键字只能使用一次。
.PARAMETER-用于参数的简要说明。您需要为每个参数编写一个新的parameter关键字。首先，您需要编写parameter关键字，并在参数的名称和下一行的内容中用空格隔开。
.Example-描述功能或脚本的示例命令。您还可以包括示例输出。每个新的Example关键字可以添加多个示例。
.Notes-有关函数或脚本的附加信息。
.Inputs-输入对象的描述。
.Outputs-输出对象的描述。
上面包含的关键字是常见的关键字，它们可以帮助用户对功能或与脚本相关的帮助有足够的了解。您还可以包括许多其他关键字。要获取有关关键字的更多信息，请使用about_comment-based_help的帮助部分。
get-help about_comment-based_help
示例
function Get-ColoredService{
<#
.SYNOPSIS
Gets the colored output of the Services based on Status
.DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green
.
#>
}当您检查以上功能的帮助时，您将获得以下输出。
PS C:\WINDOWS\system32> Get-Help Get-ColoredService NAME Get-ColoredService SYNOPSIS Gets the colored output of the Services based on Status SYNTAX Get-ColoredService [] DESCRIPTION Get-ColoredService will provide the colorful output based on the status of the service. If the Service is in Stopped status - Output will be Red If the service is in Running status - Output will be in Green . RELATED LINKS REMARKS To see the examples, type: "get-help Get-ColoredService -examples". For more information, type: "get-help Get-ColoredService -detailed". For technical information, type: "get-help Get-ColoredService -full".
您会看到一些帮助关键字（名称，语法，描述，相关链接，备注）是默认的。
现在，我们将使用其他关键字（例如参数，输入，输出，示例等）来创建帮助。无论您在param块中将其声明为参数如何，都将为其显示语法，如以下示例中所述。
function Get-ColoredService{
<#
.SYNOPSIS
Gets the colored output of the Services based on Status
.DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green
.PARAMETER ServiceName
Specifies the path to the CSV-based input file.
.EXAMPLE
Get-ColoredService -ServiceName Spooler,WinRM
.EXAMPLE
Get-ColoredService -ServiceName *
.INPUTS
Input single or multiple services names
.OUTPUTS
Output of the services information in the table format
#>
[cmdletbinding()]
param(
[string[]]$ServiceName
)
}当您检查上述功能的帮助时，可以在语法中看到变量名称。
PS C:\WINDOWS\system32> Get-Help Get-ColoredService -Full
NAME
Get-ColoredService
SYNOPSIS
Gets the colored output of the Services based on Status
SYNTAX
Get-ColoredService [[-ServiceName] <String[]>] [<CommonParameters>]
DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green
PARAMETERS
-ServiceName <String[]>
Specifies the path to the CSV-based input file.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information,
see
about_CommonParameters
(https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
Input single or multiple services name
OUTPUTS
Output of the services information in the table format
-------------------------- EXAMPLE 1 --------------------------
PS C:\>Get-ColoredService -ServiceName Spooler,WinRM
-------------------------- EXAMPLE 2 --------------------------
PS C:\>Get-ColoredService -ServiceName *
RELATED LINKS