Hey, Scripting Guy! How Do I Add Help Information for Windows PowerShell Parameters?

ScriptingGuy1

Bookmark and Share
Hey, Scripting Guy! Question

Hey, Scripting Guy! I have been reading your articles this week about adding Help to scripts, and it looks really cool, but it also seems to be quite a bit of work. I would love to be able to display Help for a script when the script is run with a specific switch, but then it requires testing for the switched parameter and using nested if/then/else constructions. Is there an easier way to add Help information for parameters used in a Windows PowerShell script?

— AW

Hey, Scripting Guy! Answer Hello AW,

Microsoft Scripting Guy Ed Wilson here. Well, it has finally happened. I recently got my annual ear infection. The bad thing is I am listening to the Meat Loaf CD the Scripting Wife placed in my stocking, and it sounds a little lopsided because I’m just about deaf in my right ear. As far as I can tell, the CD is awesome. The saving grace is that my Zune speakers are on my left side, so I can at least hear out of my good ear. The horrible thing is that the ear infection started during the holidays and I was not able to get out into my scripting wood working shop because the Scripting Wife would not let me out of the house. At times she has much more common sense than I do.

AW, listening to lopsided music is sort of like your approach to adding Help to your script. This is because you are focusing on only one avenue for adding Help. In Windows PowerShell 1.0, there was only one way to add Help, and that involved adding a switched parameter and typing various here-strings. In Windows PowerShell 2.0, you can integrate with the Windows PowerShell Help system by using the Get-Help cmdlet. To do this, you will need to use various stylized Help function tags.

Note: Portions of today’s Hey, Scripting Guy! post are excerpted from the Microsoft Press book, Windows PowerShell 2.0 Best Practices by Ed Wilson, which is now available.

Much of the intensive work of producing Help information for your functions is removed when you use the stylized Help function tags that are available in Windows PowerShell 2.0. To use the Help function tags, you place the tags inside the block comment tags when you are writing your script. When you write Help for your function and employ the Help tags, it allows for complete integration with the Get-Help cmdlet. This provides a seamless user experience for those utilizing your functions. In addition, it promotes the custom user-defined function to the same status within Windows PowerShell as native cmdlets. The experience of using a custom user-defined function is no different than using a cmdlet, and indeed to the user there is no need to distinguish between a custom function that was dot sourced, loaded via a module, or a native cmdlet. The Help function tags and their associated meanings are shown in Table 1.

Table 1 Function Help Tags and Meanings

Help tag name

Help tag description

.Synopsis

A very brief description of the function. It begins with a verb and tells the user what the function does. It does not include the function name or how the function works. The function synopsis appears in the SYNOPSIS field of all help views.

.Description

Two or three full sentences that briefly list everything that the function can do. The description begins with “The <function name> function….” If the function can get multiple objects or take multiple inputs, use plural nouns in the description. The description appears in the DESCRIPTION field of all Help views.

.Parameter

Brief and thorough. Describe what the function does when the parameter is used. And what legal values are for the parameter. The parameter appears in the PARAMETERS field only in Detailed and Full Help views.

.Example

Illustrate use of function with all its parameters. First example is simplest with only the required parameters. Last example is most complex and should incorporate pipelining if appropriate. The example appears only in the EXAMPLES field in the Example, Detailed, and Full Help views.

.Inputs

Lists the .NET Framework classes of objects the function will accept as input. There is no limit to the number of input classes you may list. The inputs Help tag appears only in the INPUTS field in the Full Help view.

.Outputs

Lists the .NET Framework classes of objects the function will emit as output. There is no limit to the number of output classes you may list. The outputs Help tag appears in the OUTPUTS field only in the Full Help view.

.Notes

Provides a place to list information that does not fit easily into the other sections. This can be special requirements required by the function, as well as author, title, version, and other information. The notes Help tag appear in the NOTES field only in the Full help view.

.Link

Provides links to other Help topics and Internet Web sites of interest. Because these links appear in a command window, they are not direct links. There is no limit to the number of links you may provide. The links appear in the RELATED LINKS field in all Help views.

 

You do not need to supply values for all of the Help tags. As a best practice, however, you should consider supplying the .Synopsis and the .Example tag because these two tags supply the most critical information required to assist a person in learning how to use the function.

An example of using the Help tags is seen in the GetWmiClassesFunction1.ps1 script. First you will notice that there is no need to create a switched $help parameter. The reason for not needing the switched $help parameter is the incorporation of the code with the Get-Help cmdlet. When you do not need to use a switched $help parameter, you also do not need to test for the existence of the $help variable. By avoiding the testing for the $help variable, your script can be much simpler. You gain several other bonuses by using the special Help tags:

·         The name of the function is automatically displayed in all Help views.

·         The syntax of the function is automatically derived from the parameters and displayed in all Help views.

·         Detailed parameter information is automatically generated when the –full parameter of the Get-Help cmdlet is used.

·         Common parameter information is automatically displayed when Get-Help is used with the –detailed and –full parameters

In the GetWmiClassesFunction1.ps1 script, the Get-WmiClasses function begins the Help section with the Windows PowerShell 2.0 multiline comment block. The multiline comment block special characters begin with the left angle bracket followed with a pound sign (<#) and end with the pound sign followed by the right angle bracket (#>). Everything between the multiline comment characters is considered to be commented out. Two special Help tags are included: .Synopsis and .Example. The other Help tags that were listed in Table 1 are not used for this function.

  <#
    .SYNOPSIS
      Displays a list of WMI Classes based upon a search criteria
    .EXAMPLE
     Get-WmiClasses -class disk -ns rootcimv2″
     This command finds wmi classes that contain the word disk. The
     classes returned are from the rootcimv2 namespace.
  #>

After the GetWmiClassesFunction.ps1 script is dot-sourced into the Windows PowerShell console, you can use the Get-Help cmdlet to get Help information from the Get-WmiClasses function. This is seen in the following image.

Image of getting Help from Get-WmiClasses function

 

Because the Help tags integrate with the Windows PowerShell help subsystem, you can use the various parameters from the Get-Help cmdlet to modify the Help output. As seen in the following image, you can display only the examples.

Image showing you can only dislay examples

 

The complete GetWmiClassesFunction1.ps1 script is seen here.

GetWmiClassesFunction1.ps1

Function Get-WmiClasses(
                        $class=($paramMissing=$true),
                        $ns=”rootcimv2″
                       )
{
<#
    .SYNOPSIS
      Displays a list of WMI Classes based upon a search criteria
    .EXAMPLE
     Get-WmiClasses -class disk -ns rootcimv2″
     This command finds wmi classes that contain the word disk. The
     classes returned are from the rootcimv2 namespace.
#>
  If($local:paramMissing)
    {
      throw “USAGE: getwmi2 -class <class type> -ns <wmi namespace>”
    } #$local:paramMissing
  “`nClasses in $ns namespace ….”
  Get-WmiObject -namespace $ns -list |
  where-object {
                 $_.name -match $class -and `
                 $_.name -notlike ‘cim*’
               }
  # mred function
} #end get-wmiclasses

 

AW, that is all there is to using Help tags. This also concludes Windows PowerShell Help Week. Tomorrow, we will open the mail bag and pull out some questions that require short answers. Yep, Quick-Hits Friday!

If you want to know exactly what we will be covering tomorrow, follow us on Twitter or Facebook. If you have any questions, send e-mail to us at scripter@microsoft.com or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

 

Ed Wilson and Craig Liebendorfer, Scripting Guys

 

0 comments

Discussion is closed.

Feedback usabilla icon