How to Create the Cmdlet Help File

 

This section describes how to create a valid XML file that contains content for Windows PowerShell cmdlet Help topics. This section discusses how to name the Help file, how to add the appropriate XML headers, and how to add nodes that will contain the different sections of the cmdlet Help content.

System_CAPS_noteNote

For a complete view of a Help file, open one of the dll-Help.xml files located in the Windows PowerShell installation directory. For example, the Microsoft.PowerShell.Commands.Management.dll-Help.xml file contains content for several of the Windows PowerShell cmdlets.

How to Create a Cmdlet Help File

  1. Create a text file and save it using UTF8 encoding. The file name must have the following format so that Windows PowerShell can detect it as a cmdlet Help file.

    <PSSnapInAssemblyName>.dll-Help.xml

  2. Add the following XML headers to the text file. Be aware that the file will be validated against the Multi-Agent Modeling Language (MAML) schema. Currently, Windows PowerShell does not provide any tools to validate the file.

    <?xml version="1.0" encoding="utf-8" ?> <helpItems xmlns="http://msh" schema="maml">

  3. Add a Command node to the cmdlet Help file for each cmdlet in the assembly. Each node within the Command node relates to the different sections of the cmdlet Help topic.

    The following table lists the XML element for each node, followed by a descriptions of each node.

    Node

    Description

    <details> 

    Adds content for the NAME and SYNOPSIS sections of the cmdlet Help topic. For more information, see How to Add the Cmdlet Name and Synopsis.

    <maml:description>

    Adds content for the DESCRIPTION section of the cmdlet Help topic. For more information, see How to Add the Detailed Description to a Cmdlet Help Topic.

    <command:syntax>

    Adds content for the SYNTAX section of the cmdlet Help topic. For more information, see How to Add Syntax to a Cmdlet Help Topic.

    <command:parameters

    Adds content for the PARAMETERS section of the cmdlet Help topic. For more information, see How to Add Parameters to a Cmdlet Help Topic.

    <command:inputTypes

    Adds content for the INPUTS section of the cmdlet Help topic. For more information, see How to Add Input Types to a Cmdlet Help Topic.

    <command:returnValues

    Adds content for the OUTPUTS section of the cmdlet Help topic. For more information, see How to Add Return Values to a Cmdlet Help Topic.

    <maml:alertset>

    Adds content to the NOTES section of the cmdlet Help topic. For more information, see How to add Notes to a Cmdlet Help Topic.

    <command:examples>

    Adds content for the EXAMPLES section of the cmdlet Help topic. For more information, see How to Add Examples to a Cmdlet Help Topic.

    <maml:relatedLinks

    Adds content for the RELATED LINKS section of the cmdlet Help topic. For more information, see How to Add Related Links to a Cmdlet Help Topic.

Example

Here is an example of a Command node that includes the nodes for the various sections of the cmdlet Help topic.

<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>
    <!--Add name an synopsis here-->
  </command:details>
  <maml:description>
    <!--Add detailed description here-->
  </maml:description>
  <command:syntax>
    <!--Add syntax information here-->
  </command:syntax>
  <command:parameters>
    <!--Add parameter information here-->
  </command:parameters>
  <command:inputTypes>
    <!--Add input type information here-->
  </command:inputTypes>
  <command:returnValues>
    <!--Add return value information here-->
  </command:returnValues>
  <maml:alertSet>
    <!--Add Note information here-->
  </maml:alertSet>
  <command:examples>
    <!--Add cmdlet examples here-->
  </command:examples>
  <maml:relatedLinks>
    <!--Add links to related content here-->
  </maml:relatedLinks>
</command:command>
Show: