Weekend Scripter: Create PowerShell Graphical Help Function

Doctor Scripto

Dr 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):

Image of command output

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
Dr Scripto

Scripter, PowerShell, vbScript, BAT, CMD

Follow Dr Scripto   

No Comments.