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