如何在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