If you are like me, when you type a command line, you hit the TAB key to auto-fill parameters’ values. Or, when you don’t know which value to enter, you hit CTRL + C and you use a search engine or the Get-Help -Name CmdletName -Parameter ParameterName command line to find out which value to enter.

That’s why you probably don’t know that Help Messages exist, what they are for, in which situation they could be used to, and also that’s probably why you never used them…

Real life example

Recently, I wrote a post about Dynamic PowerShell and SSH remoting tabs for Windows Terminal.
The user is supposed to click in the menu or use a keyboard shortcut to initiate a remoting session.

But what if the user doesn’t know what to type when a specific parameter is requested? In this case, there is no Internet page with detailed information and the Get-Help command wouldn’t be useful neither.
Also I don’t expect the user to open Windows Terminal’s settings and have a look at the code to try to guess what to type.

The solution: the user can just type !? and immediately get more information about the parameter’s possible values.

Note:
For those who copied/pasted the JSON configuration directly from the website in the previous article, and didn’t use the GIST file, some characters were not correctly escaped in the HTML code of the web page and the help message was not present in the JSON configuration. However, this is now fixed.

When are Help Messages available

Help Messages are available when all those conditions are met:

1. You forgot to add a mandatory parameter to your command line
2. There is no default value for this parameter
3. The (Type !? for Help.) line is displayed, which means the author has implemented a Help Message

If you wonder which functions on your system make usage of Help Messages, here is how to display them:

Get-Help -Name * -Parameter * | Where-Object -Property Description

Note: this command line does not display cmdlets with a Help Message For example, the Get-ADUser had Help Messages for the -Filter parameter, but it does not appear in the list displayed by the former command line.

How to implement your own Help Messages

It’s pretty easy to implement your own Help Messages. Just use the built-in HelpMessage argument inside the [Parameter( )] attribute.
For example:

Param(
    [Parameter(
        Mandatory=$true,
        HelpMessage = "<UserName>@<ComputerName>:<PortNumber>"
    )]
    [String]$HostName
)

Obviously, the Help Message should have any utility. If your message for the -UserName parameter is “please enter a username”, this isn’t very useful.

When to implement Help Messages?

Theoretically, your parameter names should be self explaining. However, there are cases where a little additional explanation can be helpful, and here Help Messages can be useful.

But as a best practice, you could always summarize in a Help Message what the user should know before entering a value for a parameter.