Weekend Scripter: A Little PowerShell Help Here...Please?

Summary: Guest blogger, Matt Tisdale, talks about adding Help text to Windows PowerShell functions.

Microsoft Scripting Guy, Ed Wilson, is here. Yesterday I introduced Matt Tisdale as the guest blogger. Guess what? He’s back today!  Dude!! Sweet!!! Here is Matt’s post from yesterday: Optimize Performance of AD DS Queries via PowerShell. Today he discusses adding Help text to custom functions…

I now have a few people at my company who are writing custom Windows PowerShell functions to help other IT team members and business employees. I am very excited to see this, and I always try to provide additional information to help these individuals make functions more beneficial and useful.

One of the best ways to make a function useful to others is to add Help text. Anyone who has used Windows PowerShell for more than five minutes is already familiar with the Get-Help cmdlet. If we want to learn how to use the Get-ADUser cmdlet, we simply run Get-Help Get-ADUser -detailed. The information that is displayed by Get-Help appears because the programmer who wrote Get-ADUser added the Help text into their script.

Likewise, Help text can be added to any custom function quite easily. Let's say you have a function named Get-FolderData. With just a few lines of script added to the function, other people can run Get-Help Get-FolderData -detailed and see exactly what the function does and how to use it.

There are a few ways you can add Help text, but to help maintain a consistent standard at my company, I recommend that everyone use the following standards:

1. Start your Help text block immediately under the first line of script in your function.
2. Open your Help text block with the characters <#, and end the block with #>
3. With your Help text, always include SYNOPSIS, DESCRIPTION, and EXAMPLE at a minimum.

Let's break this down a little...

So what is a Help text block? This is nothing more than a block of script that contains all of the data you want to display when Get-Help is used against your function. Here is a very simple example:

Function Get-FolderData() {

<#

.SYNOPSIS

Retrieve specific information about one or more folders

.DESCRIPTION

This function can be used to read information about folder properties.

Some of the properties this function can read include size, when created,

last modified and many more.

.PARAMETER Path

This parameter contains the full path to the folder you wish to

display information for.

.EXAMPLE

Get-FolderData -Path "c:\temp\test1"

This command returns information for the folder c:\temp\test1

#>

### CODE GOES HERE ###

}

That is all it takes. Pretty simple! Notice how the block starts with the characters <# and ends with #>? This is my preferred method for building a Help text block. All of the Help text that you want to display simply goes between these two character strings.

The next important thing to look for is Keyword headings. Take a look at .SYNOPSIS, .DESCRIPTION, and the other keywords in the previous Help text. Each of these keywords must be entered exactly as shown, including the preceding period. Get-Help looks for these keywords, and they determine how Help data is displayed on the screen.

Make sure that you always include .SYNOPSIS, .DESCRIPTION, and .EXAMPLE at a minimum. Another keyword that will most likely be used in most of your functions is .PARAMETER. The .PARAMETER and .EXAMPLE keywords can be used as many times as you want.

Instead of writing a book here about what each of these keywords are used for and all of the other remaining details related to Help text, I recommend that you check out the documentation already provided by Microsoft. To read all of the details about Help text, do either of the following:

• Check out about_Comment_Based_Help in the Windows Dev Center
• Open Windows PowerShell and run Get-Help about_comment_based_help

Happy scripting!

~Matt

Thank you, Matt. Way cool stuff. Join us tomorrow for one more guest post from Matt.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy