数据结构
网络
关系型数据库管理系统
操作系统
Java
MS Excel
iOS
HTML
CSS
Android
Python
C 编程
C++
C#
MongoDB
MySQL
Javascript
PHP
物理学
化学
生物学
数学
英语
经济学
心理学
社会学
时尚研究
法律研究如何在 PowerShell 中编写基于注释的帮助？
在 PowerShell 中，当您创建复杂的脚本或函数时，应该为最终用户创建帮助，以便他们轻松理解您的脚本功能。编写基于注释的帮助或基于 XML 的帮助，最终与 cmdlet 或函数的 **Get-Help** 语法类似，它是帮助的在线版本。
例如，只需打开 PowerShell 控制台并运行以下命令。
Get-Help Get-WmiObject
您可以在输出中看到各种帮助部分，例如 **NAME、SYNOPSIS、SYNTAX、DESCRIPTION、PARAMETER、LINK**。这些称为 **关键字**。我们可以手动将它们全部包含在脚本或函数中以获取帮助。每当我们使用帮助关键字时，都需要在它前面使用点 (.) 关键字。
当我们编写基于注释的帮助时，它应该位于多行注释框 **<# .. #>** 内。您也可以使用单行注释 #，但对于用户来说，更容易阅读和理解的是将它们放在多行注释框内。
没有必要用大写字母使用语法，但为了用户的可读性和区分 **关键字**，我们将它们放入 **大写** 字母中。
以下是基于命令的帮助的结构。
<# .HELP Keyword HELP content #>
让我们逐一了解一些必要的关键字。
**.SYNOPSIS** - 函数或脚本的简要描述。此关键字只能在帮助部分中使用一次。
**.DESCRIPTION** - 函数或脚本的详细描述。此关键字只能在帮助部分中使用一次。
**.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".
您可以看到一些帮助关键字 **(名称、语法、描述、相关链接、备注)** 是默认的。
我们现在将使用其他关键字（如 **parameter、inputs、outputs、example** 等）创建帮助。在 **param** 块中声明为 **parameter** 的任何内容，都会显示其语法，如下例所示。
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
469 次查看
