Draft - Creating Cmdlet Help

NOTE: This content is also included as an RTF attachment as well.

Creating Cmdlet Help

When creating your own cmdlet, you can also create Help content that Windows PowerShell can display using the Get-Help cmdlet. The Help content that describes your cmdlet can include a description of the cmdlet, the syntax used by your cmdlet, parameter descriptions, examples, and other related notes.

Caution:

The following XML shows the major sections that are in the cmdlet Help file and some of the possible values for the XML elements. This example is not exhaustive, so it is highly recommended that you look at the XML files installed with Windows PowerShell to see examples of the XML for the cmdlets provided by Windows PowerShell. For an example of of these files, see Microsoft.PowerShell.Commands.Management.dll-Help.

Creating the Help XML file

Create a text file with a name similar to the assembly that contains the snap-in that registers your cmdlet. For standard snap-ins, the snap-in and the cmdlet reside in the same assembly. However, for custom snap-ins the cmdlet can reside in another assembly.

The name of the Help file must be in the following format:

MySnapinAssemblyName.dll-Help.xml

Open the Help file in a text editor and add the following XML. Notice that the XML used for cmdlet Help is based on the MAML schema. Currently there are no tools provided by Windows PowerShell to validate your Help file against the MAML schema.

<?xml version=”1.0″ encoding=”utf-8″ ?>

Add a Command node for each of your cmdlets that are registered by your snap-in.

<command:command xmlns:maml=”http://schemas.microsoft.com/maml/2004/10″ xmlns:command=”http://schemas.microsoft.com/maml/dev/command/2004/10″ xmlns:dev=”http://schemas.microsoft.com/maml/dev/2004/10″>

</command:command>

In each Command node, add a Command-Details node to provide meta-information, such as the cmdlet name and a short cmdlet description.

<command:details>

<command:name>Verb-Noun</command:name>

<maml:description>

<maml:para>Cmdlet description.</maml:para>

</maml:description>

<maml:copyright>

<maml:para></maml:para>

</maml:copyright>

<command:verb>Cmdlet verb name</command:verb>

<command:noun>Cmdlet Noun name</command:noun>

<dev:version></dev:version>

</command:details>

In each Command node, add a description node that contains a detailed cmdlet description.

<maml:description>

<maml:para>Detailed description of cmdlet.</maml:para>

</maml:description>

In each Command node, add a Command-Syntax node. If multiple parameter sets are used, add a Command-SyntaxItem node for each parameter set. The following example shows a Command-SyntaxItem node that contains a positional and named parameter.

<command:syntax>

<command:syntaxItem>

<maml:name>Verb-Noun name of cmdlet</maml:name>

<command:parameter required=”true” position=”1″>

<maml:name>Parameter1 name</maml:name>

<maml:description>

<maml:para>Descrition of parameter1.</maml:para>

</maml:description>

<command:parameterValue>value type</command:parameterValue>

</command:parameter>

<command:parameter required=”false” position=”named”>

<maml:name>Parameter2 name</maml:name>

<maml:description>

<maml:para>Descrition of parameter2.</maml:para>

</maml:description>

<command:parameterValue>value type</command:parameterValue>

</command:parameter>

</command:syntaxItem>

</command:syntax>

In each Command node, add a Command-Parameters node. The Command-Parameters node must contain a Command-Parameter node for each cmdlet parameter.

<command:parameters>

<command:parameter required=”true” position=”1″>

<maml:name>Parameter name</maml:name>

<maml:description>

<maml:para>Parameter description.</maml:para>

</maml:description>

<command:parameterValue required=”true”>

Paremeter value type.

</command:parameterValue>

<dev:type>

<maml:name></maml:name>

<maml:uri/>

</dev:type>

<dev:defaultValue></dev:defaultValue>

</command:parameter>

<command:parameter required=”true” position=”1″>

<maml:name>Parameter name</maml:name>

<maml:description>

<maml:para>Parameter description.</maml:para>

</maml:description>

<command:parameterValue required=”true”>

Paremeter value type.

</command:parameterValue>

<dev:type>

<maml:name></maml:name>

<maml:uri/>

</dev:type>

<dev:defaultValue></dev:defaultValue>

</command:parameter>

</command:parameters>

In each command node, add a Command-InputTypes node.

<command:inputTypes>

<command:inputType>

<dev:type>

<maml:name>Type name.</maml:name>

<maml:uri/>

<maml:description>