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

 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

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.

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.

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