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>

<maml:para>Description of type.</maml:para>

</maml:description>

</dev:type>

</command:inputType>

</command:inputTypes>

In each command node, add a Command-ReturnValue node. This information identies the object type passed through the command line. If the cmdlet does not pass an object through the pipeline, that information should be entered here as well.

<command:returnValues>

<command:returnValue>

<dev:type>

<maml:name>Output object type.</maml:name>

<maml:uri />

<maml:description>

<maml:para>

Object type description

</maml:para>

</maml:description>

</dev:type>

</command:returnValue>

</command:returnValues>

If applicable, add Command-TerminatingErrors and Command-NonTerminatingErrors nodes.

<command:terminatingErrors />

<command:nonTerminatingErrors />

If applicable, add a MAML-AlertSet node for notes about the cmdlet. This content is displayed in the Remarks section of the cmdlet Help. Although it is possible to but all remarks in a single Alert node (each paragraph element can contain one or more new line characters), it is better authoring style to separate Remarks into their own Alert node.

<maml:alertSet>

<maml:title></maml:title>

<maml:alert>

<maml:para>Add content for Remark1.</maml:para>

</maml:alert>

<maml:alert>

<maml:para>Add content for Remark2.</maml:para>

</maml:alert>

</maml:alertSet>

If applicable, add a Command:Examples node for examples of how the cmdlet can be called. Add a Command-Example node for each cmdlet example.

<command:examples>

<command:example>

<maml:title>

------------------------ EXAMPLE 1 ------------------------

</maml:title>

<maml:introduction>

<maml:para>Description of example.</maml:para>

</maml:introduction>

<dev:code>Example code.</dev:code>

<dev:remarks>

<maml:para>Remarks about the example.</maml:para>

</dev:remarks>

</command:example>

</command:examples>

If applicable, add a MAML-RelatedLinks node for cross references to other online content. The content added lists what the related topics are. It does not provide a way to vavigae to those topics.

<maml:relatedLinks>

<maml:navigationLink>

<maml:linkText>TopicTitle</maml:linkText>

<maml:uri/>

</maml:navigationLink>

<maml:navigationLink>

<maml:linkText>TopicTitle</maml:linkText>

<maml:uri/>

</maml:navigationLink>

</maml:relatedLinks>

Example

<?xml version="1.0" encoding="utf-8" ?>

<command:details>

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

<maml:description>

<maml:para> Short description of what cmdlet does.</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>

<maml:description>

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

</maml:description>

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

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

<command:inputTypes>

<command:inputType>

<dev:type>

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

<maml:uri/>

<maml:description>

<maml:para>Description of type.</maml:para>

</maml:description>

</dev:type>

</command:inputType>

</command:inputTypes>

<command:returnValues>

<command:returnValue>

<dev:type>

<maml:name>Output object type.</maml:name>

<maml:uri />

<maml:description>

<maml:para>

Object type description

</maml:para>

</maml:description>

</dev:type>

</command:returnValue>

</command:returnValues>

<command:terminatingErrors />

<command:nonTerminatingErrors />

<maml:alertSet>

<maml:title></maml:title>

<maml:alert>

<maml:para>Add content for Remark1.</maml:para>

</maml:alert>

<maml:alert>

<maml:para>Add content for Remark2.</maml:para>

</maml:alert>

</maml:alertSet>

<command:examples>

<command:example>

<maml:title>

------------------------ EXAMPLE 1 ------------------------

</maml:title>

<maml:introduction>

<maml:para>Description of example.</maml:para>

</maml:introduction>

<dev:code>Example code.</dev:code>

<dev:remarks>

<maml:para>Remarks about the example.</maml:para>

</dev:remarks>

</command:example>

</command:examples>

<maml:relatedLinks>

<maml:navigationLink>

<maml:linkText>TopicTitle</maml:linkText>

<maml:uri/>

</maml:navigationLink>

<maml:navigationLink>

<maml:linkText>TopicTitle</maml:linkText>

<maml:uri/>

</maml:navigationLink>

</maml:relatedLinks>

</command:command

Steve Nelson
Windows PowerShell SDK Programmer Writer
Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

Published Thursday, September 14, 2006 5:44 PM by PowerShellTeam

Filed under: DOCUMENTATION, Help file, Maml

Attachment(s): Creating Cmdlet Help.rtf

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

# re: Draft - Creating Cmdlet Help

Do you have a XSD schema for this file.. that would really help in building our help files?

Friday, September 15, 2006 12:08 PM by Karl prosser

# re: Draft - Creating Cmdlet Help

This is the Windows Vista MAML help format. Here is some documentation on the structure, although there is tons out there: http://www.help-info.de/en/Help_Info_AP_Help/longhorn_maml_example.htm

Friday, September 15, 2006 12:45 PM by Lee

# re: Draft - Creating Cmdlet Help

It seems like it might be useful for a user to be able to say: get-help <snapin-name>. Is there a section in the xml file where we can put general information about the snap-in itself that is not specific to the individual cmdlets included in the snapin?

Friday, November 03, 2006 10:02 AM by Lance Robinson

# re: Draft - Creating Cmdlet Help

I would also be really nice to have a converter .Net XML doc ==> CmdLet XML doc.

I have listed a few PowerShell suggestions on my blog on this matter.

http://blog.vermorel.com/?p=37

Thanks anyway, PowerShell looks great.

Joannès

Wednesday, November 08, 2006 3:43 AM by Joannes Vermorel

Title (required)
Name required
Your URL
Comments (required)
Remember Me?

Windows PowerShell Blog

This Blog

Syndication

Search

Tags

Archives

Draft - Creating Cmdlet Help

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

Creating Cmdlet Help

Comment Notification

Comments

# re: Draft - Creating Cmdlet Help

# re: Draft - Creating Cmdlet Help

# re: Draft - Creating Cmdlet Help

# re: Draft - Creating Cmdlet Help

Leave a Comment