September 14th, 2006

Draft – Creating Cmdlet Help

PowerShell Team
PowerShell Team
PowerShell Team

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

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

  1. 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″ ?>

 

<helpItems xmlns=”http://msh” schema=”maml”>
  1. 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>
  1. 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>
  1. 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>
  1. 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>
  1. 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>
  1. 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>
  1. 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>
  1. If applicable, add Command-TerminatingErrors and Command-NonTerminatingErrors nodes.

 

 

<command:terminatingErrors />

 

<command:nonTerminatingErrors />
  1. 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>
  1. 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>
  1. 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

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.

 

 

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

 

<helpItems xmlns=”http://msh” schema=”maml”>

 

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

Creating Cmdlet Help.rtf

Category
PowerShell
Topics
DOCUMENTATIONHelp fileMaml

Author

PowerShell Team
PowerShell Team
PowerShell Team

PowerShell is a task-based command-line shell and scripting language built on .NET. PowerShell helps system administrators and power-users rapidly automate tasks that manage operating systems (Linux, macOS, and Windows) and processes.

0 comments

Discussion are closed.

Read next