Summary: Microsoft Scripting Guy, Ed Wilson, talks about creating a graphical Help function in Windows PowerShell.
Microsoft Scripting Guy, Ed Wilson, is here. Well, I should have known. In yesterday’s post, A Graphical Tool to Explore PowerShell Help, I said it would not take too long to convert my Windows PowerShell script (that I used to display Help) into a function. All of a sudden, I get a dozen emails to scripter@microsoft.com asking how to do that—not to mention a few tweets.
As it turned out, I spent more than a few seconds converting the script into a function. Of course, I decided if I am going to go to the trouble of converting it to a function, I should add functionality. So I did.
I added another grid so I could pick the module from the list of available modules. I also added switched parameters to allow me to change the level of Help displayed by the final Get-Help cmdlet. Along the way, I decided to use splatting to pass my parameters to the Get-Help cmdlet. It is way cool, and a worthwhile technique to use in other functions.
Note I have posted several blog articles about splatting over the years. To come up to speed on this very useful technique,
read these Hey, Scripting Guy! Blog posts.
I start my function by using the Functionkeyword. I provide a name, open a script block, and define three switched parameters. Switched parameters only affect the script if they are present when calling the function. This portion of the script is shown here:
Function Get-GraphicalHelp {
Param (
[switch]$detailed,
[switch]$full,
[switch]$examples)
The three switched parameters are mutually exclusive after I pass them to the Get-Help function. I used a very rudimentary technique to handle this issue of too many parameters. I check the number of parameters contained in the $psBoundParameters automatic variable to see if there is more than one item there. If there is, I use the Throwkeyword to raise an error and stop the script execution. It is not very graceful, but it works. A better way of doing this would be to create different parameter sets.
Note I talk about creating parameter sets in Use Parameter Sets to Simplify PowerShell Commands.
Here is the simple command that I use to prevent sending too many parameters to function:
if ($psBoundParameters.count -gt 1) {throw "only one parameter permitted"}
When I pass too many parameters to the Get-GraphicalHelp function, it generates the following error message (the Throwcommand raises it):
I use the Get-Module –ListAvailable command to retrieve all available modules. I select the name of each module, and send the results to the Out-GridView cmdlet. When I call Out-GridView, I use the –PassThru parameter so I can retrieve the item selected and store it in the $m variable. This command is shown here:
$m = Get-Module -ListAvailable | select-object name | Out-GridView -PassThru
Note I can select multiple modules from the grid. If this becomes a normal usage scenario, I might want to
add ModuleName to my cmdlet grid.
The next portion of the function is the same script that I created yesterday. The Select-Object statement in this portion of the function is where I would add the ModuleNameproperty if I decided to choose multiple modules from the previous grid. This script is shown here:
Get-Command -Module $m.name |
Select-Object name, verb, noun, definition |
Out-GridView -Title "Cmdlets from the $m module" -PassThru |
To simplify the Get-Help command, I use splatting. The variable will always contain the parameter I supplied to the function, whether it is –Full, –Detailed, or –Examples. It does not matter because the parameters will be contained in the $psBoundParameters automatic variable. Therefore, all I need to do is to use splatting. Here is the command:
Get-Help @psBoundParameters }
That is all there is to it. The complete function is shown here:
Function Get-GraphicalHelp {
Param (
[switch]$detailed,
[switch]$full,
[switch]$examples)
if ($psBoundParameters.count -gt 1) {throw "only one parameter permitted"}
$m = Get-Module -ListAvailable | select-object name | Out-GridView -PassThru
Get-Command -Module $m.name |
Select-Object name, verb, noun, definition |
Out-GridView -Title "Cmdlets from the $m module" -PassThru |
Get-Help @psBoundParameters }
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