如何获取有关 Powershell 脚本参数的帮助消息？

Question

我有一个 powershell 脚本 (setup.ps1)，我们将其用作开发环境设置脚本的入口点。它需要一个参数：

param(
    [Parameter(Position=0,HelpMessage="The targets to run.")]
    [Alias("t")]
    [string[]]
    $Targets = "Help"
)

当我

PS > get-help .\setup.ps1 -detailed

在参数部分运行时，我的帮助消息不会出现：

PARAMETERS
    -Targets <String[]>

我需要做什么才能显示我的参数帮助消息？

Answer 1

行间距至关重要。请参阅 https://learn.microsoft.com/en-us/powershell/scripting/developer/help/placing-comment-based-help-in-scripts?view=powershell-7.4

如果脚本主体中的第一项（帮助之后）是函数声明，则脚本帮助末尾和函数声明之间必须至少有两个空行。否则，帮助将被解释为函数的帮助，而不是脚本的帮助。

Answer 2

您将某种风格的注释放在文件顶部，PowerShell 帮助系统可以对其进行解码。下面是一个示例：

<#
.SYNOPSIS
    .
.DESCRIPTION
    .
.PARAMETER Path
    The path to the .
.PARAMETER LiteralPath
    Specifies a path to one or more locations. Unlike Path, the value of 
    LiteralPath is used exactly as it is typed. No characters are interpreted 
    as wildcards. If the path includes escape characters, enclose it in single
    quotation marks. Single quotation marks tell Windows PowerShell not to 
    interpret any characters as escape sequences.
.EXAMPLE
    C:\PS> 
    <Description of example>
.NOTES
    Author: Keith Hill
    Date:   June 28, 2010    
#>
function AdvFuncToProcessPaths
{
    [CmdletBinding(DefaultParameterSetName="Path")]
    param(
        [Parameter(Mandatory=$true, Position=0, ParameterSetName="Path", 
                   ValueFromPipeline=$true, 
                   ValueFromPipelineByPropertyName=$true,
                   HelpMessage="Path to ...")]
        [ValidateNotNullOrEmpty()]
        [string[]]
        $Path,

        [Alias("PSPath")]
        [Parameter(Mandatory=$true, Position=0, ParameterSetName="LiteralPath", 
                   ValueFromPipelineByPropertyName=$true,
                   HelpMessage="Path to ...")]
        [ValidateNotNullOrEmpty()]
        [string[]]
        $LiteralPath
    )
    ...

有关详细信息，请参阅帮助主题 - man about_comment_based_help。

Answer 3

显然，如果您定义了帮助标头，则只需在参数后面使用注释 (#)（在本例中：#要运行的目标。）：

<#
.SYNOPSIS
    .
.DESCRIPTION
    .
.PARAMETER Path
    The path to the .
.PARAMETER LiteralPath
    Specifies a path to one or more locations. Unlike Path, the value of 
    LiteralPath is used exactly as it is typed. No characters are interpreted 
    as wildcards. If the path includes escape characters, enclose it in single
    quotation marks. Single quotation marks tell Windows PowerShell not to 
    interpret any characters as escape sequences.
#>

Param(
    [String]$Targets = "Help"   #The targets to run.
)

结果为：

PS C:\> Get-help .\Setup.ps1 -Detailed

NAME
    C:\Setup.ps1

SYNOPSIS
    .


SYNTAX
    C:\Setup.ps1 [[-Targets] <String>] [<CommonParameters>]


DESCRIPTION
    .


PARAMETERS
    -Targets <String>
        The targets to run.

Answer 4

只需要文件顶部的 <# .SYNOPSIS #> 部分即可使其正常工作，并且您可以很好地内联注释您的参数：（

<# .SYNOPSIS #>
param(
   [String]$foo   ## my 1st cool param
  ,[Switch]$bar  ## my 2nd crazy switch
)
...

使用PS 5.1.14409.1018检查）