如何获得针对我的 Powershell 脚本参数显示的帮助消息？答案

【问题标题】：How do I get help messages to appear for my Powershell script parameters?如何获得针对我的 Powershell 脚本参数显示的帮助消息？
【发布时间】：2011-07-11 09:33:15
【问题描述】：

我有一个 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[]>

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

【问题讨论】：

标签： powershell powershell-2.0

【解决方案1】：

您在文件顶部放置了某种样式的注释，可以被 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。

【讨论】：

我明白了。所以Parameter 属性上的HelpMessage 属性实际上被PowerShell 帮助系统忽略。这并不令人困惑。 ://
是的，这有点令人困惑。但是，参数上的 HelpMessage 属性 not 被忽略。当您调用命令而不指定强制参数时使用它。此时会提示您输入该参数的值。如果您指定 HelpMessage，则该文本将显示为该提示的一部分。
但只有当你输入“！？”当 PowerShell 提示输入该强制参数的值时。这是鲜为人知的。
@JasonMArcher - ISE 无需额外努力即可显示帮助消息。
显然，这仅在使用上面的参数块样式声明您的参数时才有效（对我来说，这非常冗长和繁琐）。我有像常规编程函数一样编写的函数，get-help 不适用于上述文档块。

【解决方案2】：

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

<#
.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.

【讨论】：

或者，您可以将注释放在参数之前的行中，这对于更长的描述和更长的参数名称可能会更好。
为什么不将目标参数放在描述参数的部分，例如。 G。之前或之后.PARAMETER Path
在 PS3 中，get-help -detailed 会得到不同的（更好的）结果：显示所有参数和 .PARAMETER 中的描述。

【解决方案3】：

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

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

（与PS 5.1.14409.1018核对）

【讨论】：

很奇怪，如果我使用上面的“完整”选项，它给我的输出会比只用这一行的少...我喜欢它！