添加基于注释的帮助中断动态参数的Get-Help

时间:2017-07-11 19:51:56

标签: powershell powershell-v4.0 dynamicparameters

如果我有一个带动态参数的函数,我该如何添加基于注释的帮助,以便当用户运行Get-Help时它仍会显示动态参数?
例如这是我的功能,没有任何基于评论的帮助

function Test-DynamicParam{
  [CmdletBinding(PositionalBinding=$false)]
  param(
      [Parameter(Mandatory=$false)][string]$NamedStaticParam1,
      [Parameter(Mandatory=$false)][string]$NamedStaticParam2
  )
  dynamicparam {
      $paramDictionary = new-object -Type System.Management.Automation.RuntimeDefinedParameterDictionary

      $paramname = "NamedDynamicParam1"
      $values = 'foo','bar' #would normally get these dynamically
      $attributes = new-object System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "__AllParameterSets"
      $attributes.Mandatory = $true
      $attributeCollection = new-object -Type System.Collections.ObjectModel.Collection[System.Attribute]
      $attributeCollection.Add($attributes)
      $ValidateSet = new-object System.Management.Automation.ValidateSetAttribute($values)
      $attributeCollection.Add($ValidateSet)
      $dynParam = new-object -Type System.Management.Automation.RuntimeDefinedParameter($paramname, [string], $attributeCollection)

      $paramDictionary.Add($paramname, $dynParam)
      return $paramDictionary
  }

  process{
     $PSBoundParameters.NamedDynamicParam1
     $PSBoundParameters.NamedStaticParam1
     $PSBoundParameters.NamedStaticParam2
  }  
}  

如果我运行Get-Help Test-DynamicParam -Full它会给我

NAME
    Test-DynamicParam
SYNTAX
    Test-DynamicParam -NamedDynamicParam1 {foo | bar} [-NamedStaticParam1 <string>] [-NamedStaticParam2 <string>]  [<CommonParameters>]
PARAMETERS
    -NamedDynamicParam1 <string>

        Required?                    true
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     true

    -NamedStaticParam1 <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -NamedStaticParam2 <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see 
        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
    None
OUTPUTS
    System.Object
ALIASES
    None
REMARKS
    None  

但如果我像这样添加基于评论的帮助:

function Test-DynamicParam{
    <#
    .SYNOPSIS
        A test for the dynamic parameter list populating
    .DESCRIPTION
        Using this for Stack Overflow
    .NOTES
        Adding comment-based help breaks the parameter and syntax help
    #>
    ...  

正在运行Get-Help Test-DynamicParam -Full仅显示 SYNTAX 部分和 PARAMETERS 部分中的静态参数:

NAME
    Test-DynamicParam

SYNOPSIS
    A test for the dynamic parameter list populating


SYNTAX
    Test-DynamicParam [-NamedStaticParam1 <String>] [-NamedStaticParam2 <String>] [<CommonParameters>]


DESCRIPTION
    Using this for Stack Overflow


PARAMETERS
    -NamedStaticParam1 <String>

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -NamedStaticParam2 <String>

        Required?                    false
        Position?                    named
        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 (http://go.microsoft.com/fwlink/?LinkID=113216). 

INPUTS

OUTPUTS

NOTES


        Adding comment-based help breaks the parameter and syntax help


RELATED LINKS

我还尝试将.PARAMETER NamedDynamicParam1添加到基于评论的帮助中,但结果相同。有趣的是,这不会影响函数的使用,只影响Get-Help部分。我认为这是一个错误,因为添加帮助在功能上删除帮助没有任何意义

1 个答案:

答案 0 :(得分:3)

所以,我发送了a message to June Blender on Twitter pointing her to this question, and she responded

Unsurprisingly she already has an entire article written about this!

简短的回答是:这已经破了。

她的解决方法是在.DESCRIPTION部分为参数添加一个看似官方的帮助条目:

  

为了描述它,我添加了一个“DYNAMIC PARAMETERS”部分,其中包含一个条目   RequiredVersion,到.DESCRIPTION部分的结尾   基于注释的帮助或XML帮助的<maml:description>部分。

现在由PowerShell团队决定如何解决这个问题。