Hey, Scripting Guy! How Can I Add Help to Windows PowerShell Scripts?

ScriptingGuy1

Hey, Scripting Guy! I was told by the script committee at work that I must add Help to my scripts if they are to be stored in the official script repository we have at work. Can you tell me how I would go about doing this?

— CG

Hello CG,

Microsoft Scripting Guy Ed Wilson here. I am listening to Johnny Cash on my Zune HD and drinking espresso this morning. Normally, I would not drink espresso in the morning because I prefer it in the afternoon, but this morning seems like afternoon or evening or something. It has been a rather long night as I press on to my goal of getting all the Hey, Scripting Guy! posts written so that Craig, the Scripting Editor, can take a much deserved holiday. He actually sent me an e-mail challenge yesterday. So I dug out the simple steam-driven espresso machine I brought back from Naples, Italy, many years ago, placed it on the stove, and made a pot of midnight black espresso. I like to have a small piece of Língua de gato, which is a habit I acquired while I was teaching a VBScript class in Sao Paulo a couple years ago. 

Note: Portions of today’s Hey, Scripting Guy! article are excerpted from the Microsoft Press book, Windows PowerShell 2.0 Best Practices by Ed Wilson. This book is available for pre-order.

In Windows PowerShell 1.0, if you wanted to include a comment that spans multiple lines, you used multiple pound characters (#), as seen here:

# This is the first line of a multiple line comment
# This is the second line of the comment

This works fine for short comments, but when you need to write a paragraph documenting a particular feature, or construction in the script, it becomes rather annoying with the need to type all of the pound characters. If one of the comment characters is inadvertently left out, an error will be generated. Depending on the actual placement of the pound sign, the error could be misleading and cause you to waste development time by chasing down the errant line of code. You can still use the multiple pound character approach to adding comments in Windows PowerShell 2.0 if you wish to do so. The advantage is simplicity and backward compatibility with Windows PowerShell 1.0. Your code will also be easy to read: Anyone familiar with Windows PowerShell will be able to immediately recognize the lines of code as comments.

One trick that could be used in Windows PowerShell 1.0 to allow for multi-line comments was to use a here-string. The here-string allows you to assign text without worrying about line formatting, or escaping quotation marks and other special characters. It is helpful for working with multiple lines of text because it allows you to forget about the more tedious aspects of working with formatted text, such as escaping quotation marks. 

An example of working with here-strings is the Demo-HereString.ps1 script. The variable $instructions is used to hold the content of the here-string. The actual here-string itself is created by beginning the string with the ampersand double quotation mark (@”) symbol. The here-string is terminated by reversing the order: double quotation mark ampersand (“@) symbol. Everything between the two tags is interpreted as a string, including special characters. The here-string from the Demo-HereString.ps1 script is seen here:

$instructions = @”
This command-line demo illustrates working with multiple lines
of text. The cool thing about using a here-string is that it allows
you to “work” with text without the need to “worry” about quoting
or other formatting issues.
   It even allows you
     a sort of
       WYSIWYG type of experience.
You format the data as you wish it to appear.
“@

The here-string is displayed by calling the variable that contains the here-string. In the Demo-HereString.ps1 script, the response to a prompt posed by the Read-Host cmdlet is stored in the $response variable. The Read-Host command is seen here:

$response = Read-Host -Prompt “Do you need instructions? <y / n>”

The value stored in the $response variable is then evaluated by the if statement. If the value is equal to the letter y, the contents of the here-string are displayed. If the value of the $response variable is equal to anything else, the script displays the string “good bye” and exits. This section of the script is seen here:

if ($response -eq “y”) { $instructions ; exit }
else { “good bye” ; exit }The Demo-HereString.ps1 script is seen here.

The complete Demo-HereString.ps1 script is seen here.

Demo-HereString.ps1

$instructions = @”
This command-line demo illustrates working with multiple lines
of text. The cool thing about using a here-string is that it allows
you to “work” with text without the need to “worry” about quoting
or other formatting issues.
   It even allows you
     a sort of
       WYSIWYG type of experience.
You format the data as you wish it to appear.
“@

The advantage of using a here-string to store your comments is that it then becomes easy to create named sections of comments. If you have named comment sections, you can then solicit input from a user and then display the appropriate section of Help text for the user of the script. In the Demo-HereString1.ps1 script, three different levels of Help are created: Overview, Instructions, and Details. The results of the three different here-strings are stored in three different variables. The overview Help string provides a quick three-line summary, as shown here:

$overview=@”
OVERVIEW
The here-string provides an easy way to add
multi-line comments to a script. It can also
hold additional information if desired.
“@

The $instructions variable is used to hold additional information about here-strings, as seen here:

$instructions = @”
INSTRUCTIONS
This command-line demo illustrates working with multiple lines
of text. The cool thing about using a here-string is that it allows
you to “work” with text without the need to “worry” about quoting
or other formatting issues.
   It even allows you
     a sort of
       WYSIWYG type of experience.
You format the data as you wish it to appear.
“@

The $details variable holds a literal here-string. You can create a literal here-string the same way that you create a regular here-string, except that you use a single quotation mark following the at symbol (@). This is seen here:

$details=@’
DETAILS
When working with the here-string, it is important that the @” character
be immediately followed with a <cr>; you can then type test as required.
The cool thing about using a here-string is that it allows
you to “work” with text without the need to “worry” about quoting
or other formatting issues.
   It even allows you
     a sort of
       WYSIWYG type of experience.
You format the data as you wish it to appear.
When you are done you close you’re here-string by placing the “@ on its own
individual line.
If you wish to use the @” character or the “@ character in a here-string, use the
non-expanding here-string, which uses the @’ character or the ‘@ character.
One problem with using the exit statement in the ISE is that it closes the
Windows PowerShell ISE, which is annoying.
‘@

The switch statement is used to evaluate the value that is supplied to the Read-Host prompt. Note that if the value is not one of the three valid replies—o, i, or d—the default action will display a message and exit the script. When using the exit command in the Windows PowerShell ISE, it will close the Windows PowerShell ISE, which can be a bit annoying. I, therefore, always use the Windows PowerShell console when testing a script that includes the exit condition.

For more information on using the Switch statement in Windows PowerShell, see How Can I Evaluate a Condition and Select from Several Options with Windows PowerShell?

The complete Demo-HereString1.ps1 script is seen here.

Demo-HereString1.ps1

$overview=@”
OVERVIEW
The here-string provides an easy way to add
multi-line comments to a script. It can also
hold additional information if desired.
“@
$instructions = @”
INSTRUCTIONS
This command-line demo illustrates working with multiple lines
of text. The cool thing about using a here-string is that is allows
you to “work” with text without the need to “worry” about quoting
or other formatting issues.
   It even allows you
     a sort of
       WYSIWYG type of experience.
You format the data as you wish it to appear.
“@

When you run the Demo-HereString1.ps1 script and run through the different command-line options, you will be presented the output seen here:

CG, that is all there is to using here-strings for Help comments.  Windows PowerShell Help Week will continue tomorrow when we will talk about…not so fast.

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

Ed Wilson and Craig Liebendorfer, Scripting Guys

ScriptingGuy1

Follow