Product and service reviews are conducted independently by our editorial team, but we sometimes make money when you click on links. Learn more.
 

How to Create External Help for Your PowerShell Module Functions

By - Source: Toms IT Pro

One of the most overlooked tasks of a PowerShell scripter is writing documentation and help. Scripters just want to write code, and writing documentation to provide the user information on how to execute that code is an often-neglected feature. Help, however, is a critical piece of any good PowerShell tool especially when it's being released for public consumption or is part of an important business process.

There are two ways to create help for PowerShell module functions; comment-based help and external help. The difference in these two types of help content is where that help is stored. As you may have guess by the name, comment-based help is created inside of the function itself as a typical PowerShell comment just structured in a specific manner. External help isn't inside of the script at all but is written in Microsoft proprietary language called MAML that's located in an XML file in the same directory as your PowerShell module.

Even though creating comment-based help is known to be easier to understand and write, it's not necessarily scalable. When a developer is creating an important PowerShell module, she should always turn to external help.

External help consists of three parts to ensure PowerShell can understand the help file:

  • An XML file must be written in MAML with the appropriate structure
  • The XML file must be located in the same folder as the module
  • A reference to the XML file must be included in the module function pointing to the XML file

To demonstrate, let's create a simple PowerShell module with a single function. I'll call the module Thing.psm1 and a function inside will be called Do-Thing. This module will be located in the system module folder at C:Program FilesWindowsPowerShellModulesThing.

To get a basic module created, the Thing.psm1 file will look like this:

function Do-Thing {
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]$Name
    )

    ## Do stuff here
}

Next, we'll create the XML file inside of the same folder as the module C:Program FilesWindowsPowerShellModulesThing and call it the required name of Thing.psm1-Help.xml. The help file always has to follow the pattern <ModuleName>.psm1-Help.xml.

At this point, we have to build the XML file, which is no easy task. Unfortunately, there are not any great free tools out there to build these MAML files. The only tool that's currently used to build MAML for PowerShell is Sapien's HelpWriter tool. This article isn't going to be a HelpWriter tutorial, so I'm going to assume you've figured out how to create a new help file and create a cmdlet inside of HelpWriter for the Do-Thing function.

Once the XML file has been created, I'll then add the "marker" to do the Do-Thing function to point the PowerShell help system to the external file. We'll do this by adding a specially crafted comment like this: # .ExternalHelp Thing.psm1-Help.xml right above the Do-Thing function declaration.

# .ExternalHelp Thing.psm1-Help.xml
function Do-Thing {
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]$Name 
   )
    ## Do stuff here
}

At this point, we're done. To verify that PowerShell sees our external help file, I'll attempt to find the help content for my Do-Thing function.

PS C:WINDOWSsystem32> Get-help Do-Thing

NAME
    Do-Thing

SYNOPSIS
    This function does stuff.

SYNTAX
    Do-Thing [-Name <string>] [<CommonParameters>]

DESCRIPTION

RELATED LINKS

REMARKS   
To see the examples, type: "get-help Do-Thing -examples".   
For more information, type: "get-help Do-Thing -detailed".   
For technical information, type: "get-help Do-Thing -full".

Notice that we have something under the SYNOPSIS section. If PowerShell did not recognize the help file, nothing would be displayed here. This content was pulled from the XML file.

Comments