{"id":202,"date":"2014-12-14T00:01:00","date_gmt":"2014-12-14T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2014\/12\/14\/weekend-scripter-create-powershell-graphical-help-function\/"},"modified":"2019-02-18T10:36:35","modified_gmt":"2019-02-18T17:36:35","slug":"weekend-scripter-create-powershell-graphical-help-function","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/weekend-scripter-create-powershell-graphical-help-function\/","title":{"rendered":"Weekend Scripter: Create PowerShell Graphical Help Function"},"content":{"rendered":"

Summary<\/b>: Microsoft Scripting Guy, Ed Wilson, talks about creating a graphical Help function in Windows PowerShell.<\/span><\/p>\n

Microsoft Scripting Guy, Ed Wilson, is here. Well, I should have known. In yesterday’s post, A Graphical Tool to Explore PowerShell Help<\/a>, 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<\/a> asking how to do that—not to mention a few tweets.<\/p>\n

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.<\/p>\n

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<\/b> cmdlet. Along the way, I decided to use splatting to pass my parameters to the Get-Help<\/b> cmdlet. It is way cool, and a worthwhile technique to use in other functions.<\/p>\n

   Note <\/b> 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<\/a>.<\/p>\n

I start my function by using the Function<\/b> <\/i>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:<\/p>\n

Function Get-GraphicalHelp {<\/p>\n

    Param (<\/p>\n

        [switch]$detailed,<\/p>\n

        [switch]$full,<\/p>\n

        [switch]$examples)<\/p>\n

The three switched parameters are mutually exclusive after I pass them to the Get-Help<\/b> 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 <\/b>automatic variable to see if there is more than one item there. If there is, I use the Throw<\/b> <\/i>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.<\/p>\n

   Note <\/b> I talk about creating parameter sets in Use Parameter Sets to Simplify PowerShell Commands<\/a>.<\/p>\n

Here is the simple command that I use to prevent sending too many parameters to function:<\/p>\n

if ($psBoundParameters.count -gt 1) {throw "only one parameter permitted"}<\/p>\n

When I pass too many parameters to the Get-GraphicalHelp<\/b> function, it generates the following error message (the Throw<\/b> <\/i>command raises it):<\/p>\n

\"Image<\/a><\/p>\n

I use the Get-Module –ListAvailable<\/b> command to retrieve all available modules. I select the name of each module, and send the results to the Out-GridView<\/b> cmdlet. When I call Out-GridView<\/b>, I use the –PassThru<\/b> parameter so I can retrieve the item selected and store it in the $m<\/b> variable. This command is shown here:<\/p>\n

$m = Get-Module -ListAvailable | select-object name | Out-GridView -PassThru<\/p>\n

   Note <\/b> I can select multiple modules from the grid. If this becomes a normal usage scenario, I might want to
   add ModuleName<\/b> to my cmdlet grid.<\/p>\n

The next portion of the function is the same script that I created yesterday. The Select-Object<\/b> statement in this portion of the function is where I would add the ModuleName<\/b> <\/i>property if I decided to choose multiple modules from the previous grid. This script is shown here:<\/p>\n

Get-Command -Module $m.name |<\/p>\n

Select-Object name, verb, noun, definition |<\/p>\n

Out-GridView -Title "Cmdlets from the $m module" -PassThru |<\/p>\n

To simplify the Get-Help<\/b> command, I use splatting. The variable will always contain the parameter I supplied to the function, whether it is –Full<\/b>, –Detailed<\/b>, or –Examples<\/b>. It does not matter because the parameters will be contained in the $psBoundParameters<\/b> automatic variable. Therefore, all I need to do is to use splatting. Here is the command:<\/p>\n

Get-Help @psBoundParameters }<\/p>\n

That is all there is to it. The complete function is shown here:<\/p>\n

Function Get-GraphicalHelp {<\/p>\n

    Param (<\/p>\n

        [switch]$detailed,<\/p>\n

        [switch]$full,<\/p>\n

        [switch]$examples)<\/p>\n

if ($psBoundParameters.count -gt 1) {throw "only one parameter permitted"}<\/p>\n

$m = Get-Module -ListAvailable | select-object name | Out-GridView -PassThru<\/p>\n

Get-Command -Module $m.name |<\/p>\n

Select-Object name, verb, noun, definition |<\/p>\n

Out-GridView -Title "Cmdlets from the $m module" -PassThru |<\/p>\n

Get-Help @psBoundParameters }<\/p>\n

I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

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 […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[69,463,3,562,170,61,45],"class_list":["post-202","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-functions","tag-help","tag-scripting-guy","tag-scripting-technique","tag-splatting","tag-weekend-scripter","tag-windows-powershell"],"acf":[],"blog_post_summary":"

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 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/202","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=202"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/202\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=202"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=202"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=202"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}