在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