PowerShell Tip #3 from the Winner of the Advanced Category in the 2013 Scripting Games

In my previous blog article (PowerShell Tip #2), I left off with the subject of inline help and stated there was a better way. I’m fast-forwarding through lots of concepts and jumping right into “Advanced Functions and Scripts” with this tip because they are where you’ll find the answer to a “better way” to add inline help. The inline comments we saw in the previous tip looked like this:

When looking at the syntax for this function, you can see that it has no parameters:

posh-tip3a

CmdletBinding is an attribute that makes a function or script work like a compiled cmdlet. You can’t use the CmdletBinding attribute without also using the Parameter (Param) attribute, although you don’t necessarily have to define any parameters even if you do specify the Parameter attribute:

Among other things, the CmdletBinding attribute gives your function the ability to use “common parameters” without having to do anything else to it:

posh-tip3b

For more information about the CmdletBinding attribute, read the about_Functions_CmdletBindingAttribute help topic:

posh-tip3i

You might ask, what are these common parameters you speak of?

They are several parameters that are available to any cmdlet. The actual number of common parameters will vary depending on what version of PowerShell you’re using.

You can see these common parameter names along with any other parameters that you have added to your function by using the Get-Command cmdlet:

posh-tip3f

To learn more about the “common parameters”, read the about_CommonParameters help topic:

posh-tip3e

The common parameter that you’re interested in as far as using it as a “better way” to provide inline help is the Verbose parameter. You can use the Write-Verbose cmdlet in your function with the same message you previously used as inline help:

When you want to see the message, you can simply specify the Verbose parameter when calling your function to display it. Verbose, in addition to being one of the common parameters is also a switch parameter because it doesn’t require a value:

posh-tip3g

There’s one last thing I want to cover as far as adding help to your functions and scripts goes and that’s the parameter help message:

This allows the user of your function to see help by specifying “!?” for a mandatory parameter when they don’t initially specify a value for it. My recommendation is to not use this sort of help:

posh-tip3h

If you’re using standardized parameter names (and you should be) then what’s needed should be self-explanatory. If it’s not, then the user of this function needs to read the comment based help for the function because they clearly don’t understand how to use it and continuing may lead to undesired results to say the least. The comment based help for the function should include information about each parameter. For more information about comment based help, see my previous blog article.

There’s a blog article on PowerShell.org that June Blender wrote during the 2013 scripting games that provides some additional insight as to why parameter help messages don’t provide any value.

µ

Leave a Reply

%d bloggers like this: