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

In my previous blog article, 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:

1function Get-BiosInfo {
2
3    # Attempting to retrieve the BIOS information from the local computer
4    Get-WmiObject -Class Win32_BIOS
5
6}

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

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:

1function Get-BiosInfo {
2
3    [CmdletBinding()]
4    param()
5
6    # Attempting to retrieve the BIOS information from the local computer
7    Get-WmiObject -Class Win32_BIOS
8
9}

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

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

1help about_Functions_CmdletBindingAttribute

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:

1Get-Command -Name Get-BiosInfo | Select-Object -ExpandProperty Parameters

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

1help about_CommonParameters

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:

1function Get-BiosInfo {
2
3    [CmdletBinding()]
4    param()
5
6    Write-Verbose -Message "Attempting to retrieve the BIOS information from the local computer"
7    Get-WmiObject -Class Win32_BIOS
8
9}

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:

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:

 1function Get-BiosInfo {
 2
 3    [CmdletBinding()]
 4    param(
 5        [Parameter(Mandatory,
 6                   HelpMessage="Enter a Computer Name")]
 7        $ComputerName
 8    )
 9
10    Write-Verbose -Message "Attempting to retrieve the BIOS information from $ComputerName"
11    Get-WmiObject -Class Win32_BIOS -ComputerName $ComputerName
12
13}

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:

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.

µ