Weekend Scripter: Create PowerShell Graphical Help Function

Doctor Scripto

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 Function keyword. 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 Throw keyword 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 Throw command 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 ModuleName property 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

Doctor Scripto Scripter, PowerShell, vbScript, BAT, CMD

Follow