How to add dynamic parameters to a provider help topic
Note
Manual authoring of XML-based help is very difficult. The PlatyPS module allows you to write help in Markdown and then convert it to XML-based help. This makes it much easier to write and maintain help. PlatyPS can also create the Updateable Help packages for you. For more information, see Create XML-based help using PlatyPS.
This section explains how to populate the DYNAMIC PARAMETERS section of a provider help topic.
Dynamic parameters are parameters of a cmdlet or function that are available only under specified conditions.
The dynamic parameters that are documented in a provider help topic are the dynamic parameters that the provider adds to the cmdlet or function when the cmdlet or function is used in the provider drive.
Dynamic parameters can also be documented in custom cmdlet help for a provider. When writing both provider help and custom cmdlet help for a provider, include the dynamic parameter documentation in both documents.
If a provider doesn't implement any dynamic parameters, the provider help topic contains an empty
DynamicParameters
element.
To add dynamic parameters
In the
<AssemblyName>.dll-help.xml
file, within theproviderHelp
element, add aDynamicParameters
element. TheDynamicParameters
element should appear after theTasks
element and before theRelatedLinks
element.For example:
<providerHelp> <Tasks> </Tasks> <DynamicParameters> </DynamicParameters> <RelatedLinks> </RelatedLinks> </providerHelp>
If the provider doesn't implement any dynamic parameters, the
DynamicParameters
element can be empty.Within the
DynamicParameters
element, for each dynamic parameter, add aDynamicParameter
element.For example:
<DynamicParameters/> <DynamicParameter> </DynamicParameter> </DynamicParameters>
In each
DynamicParameter
element, add aName
andCmdletSupported
element.- Name - Specifies the parameter name
- CmdletSupported - Specifies the cmdlets in which the parameter is valid. Type a comma-separated list of cmdlet names.
For example, the following XML documents the
Encoding
dynamic parameter that the Windows PowerShell FileSystem provider adds to theAdd-Content
,Get-Content
,Set-Content
cmdlets.<DynamicParameters/> <DynamicParameter> <Name> Encoding </Name> <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported> </DynamicParameters>
In each
DynamicParameter
element, add aType
element. TheType
element is a container for theName
element which contains the .NET type of the value of the dynamic parameter.For example, the following XML shows that the .NET type of the
Encoding
dynamic parameter is the FileSystemCmdletProviderEncoding enumeration.<DynamicParameters/> <DynamicParameter> <Name> Encoding </Name> <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported> <Type> <Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name> <Type> ... </DynamicParameters>
Add the
Description
element, which contains a brief description of the dynamic parameter. When composing the description, use the guidelines prescribed for all cmdlet parameters in How to Add Parameter Information.For example, the following XML includes the description of the
Encoding
dynamic parameter.<DynamicParameters/> <DynamicParameter> <Name> Encoding </Name> <CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported> <Type> <Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name> <Type> <Description> Specifies the encoding of the output file that contains the content. </Description> ... </DynamicParameters>
Add the
PossibleValues
element and its child elements. Together, these elements describe the values of the dynamic parameter. This element is designed for enumerated values. If the dynamic parameter doesn't take a value, such as is the case with a switch parameter, or the values can't be enumerated, add an emptyPossibleValues
element.The following table lists and describes the
PossibleValues
element and its child elements.- PossibleValues - This element is a container. Its child elements are described below. Add one
PossibleValues
element to each provider help topic. The element can be empty. - PossibleValue - This element is a container. Its child elements are described below. Add one
PossibleValue
element for each value of the dynamic parameter. - Value - Specifies the value name.
- Description - This element contains a
Para
element. The text in thePara
element describes the value that's named in theValue
element.
For example, the following XML shows one
PossibleValue
element of theEncoding
dynamic parameter.<DynamicParameters/> <DynamicParameter> ... <Description> Specifies the encoding of the output file that contains the content. </Description> <PossibleValues> <PossibleValue> <Value> ASCII </Value> <Description> <para> Uses the encoding for the ASCII (7-bit) character set. </para> </Description> </PossibleValue> ... </PossibleValues> </DynamicParameters>
- PossibleValues - This element is a container. Its child elements are described below. Add one
Example
The following example shows the DynamicParameters
element of the Encoding
dynamic parameter.
<DynamicParameters/>
<DynamicParameter>
<Name> Encoding </Name>
<CmdletSupported> Add-Content, Get-Content, Set-Content </CmdletSupported>
<Type>
<Name> Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding </Name>
<Type>
<Description> Specifies the encoding of the output file that contains the content. </Description>
<PossibleValues>
<PossibleValue>
<Value> ASCII </Value>
<Description>
<para> Uses the encoding for the ASCII (7-bit) character set. </para>
</Description>
</PossibleValue>
<PossibleValue>
<Value> Unicode </Value>
<Description>
<para> Encodes in UTF-16 format using the little-endian byte order. </para>
</Description>
</PossibleValue>
</PossibleValues>
</DynamicParameters>