powershellpowershell-4.0dynamicparameters

Adding Comment-Based Help Breaks Get-Help for Dynamic Parameters


If I have a function with dynamic parameters, how can I add comment-based help so that when the user runs Get-Help it will still show the dynamic parameters?
e.g. Here is my function without any comment-based 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
  }  
}  

if I run Get-Help Test-DynamicParam -Full it gives me

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  

but if I add comment-based help like this:

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

Running Get-Help Test-DynamicParam -Full shows only the static parameters in both the SYNTAX section and the PARAMETERS section:

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

I have also tried adding .PARAMETER NamedDynamicParam1 to the comment-based help, but with the same result. Interestingly, this does not affect the use of the function, just the Get-Help portion. I am thinking this is a bug, as it does not make any sense that adding help would functionally remove help


Solution

  • So, I sent 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!

    The short answer is: this is broken.

    Her workaround is to just add an official-looking help entry for the parameter(s) in the .DESCRIPTION section:

    To describe it, I add a "DYNAMIC PARAMETERS" section with an entry for RequiredVersion, to the end of the .DESCRIPTION section of comment-based help or the <maml:description> section of XML help.

    It's up to the PowerShell team at this point to figure out how to fix this going forward.