Weekend Scripter: Change PowerShell Get-Help to Display Examples

Doctor Scripto

Summary: Microsoft Scripting Guy, Ed Wilson, talks about changing the Get-Help cmdlet so it always displays examples.

Microsoft Scripting Guy, Ed Wilson, is here. For the last several weeks, I have been working on a project at work. The documentation team talked to customers to see how they were using Windows PowerShell, and to see how and when they used Help. The project has been a lot of fun, and it has been very interesting. The other day, we were discussing the results of the survey we conducted, and one of the managers mentioned that one customer said that he wished when he typed Get-Help, it would always display the examples. In fact, several customers said that the examples were the most helpful portion of the Help. I chimed in and said, “Dude, that is easy.”

The manager said, “Huh?”

I said, "I can easily fix the Get-Help cmdlet so that by default, it displays examples."

The manager said, “Really?”

I said, “Dude, it is like a one-liner. I mean, it is like less than a one-liner. I mean, I can fix any cmdlet and make it do what I want it to do.”

The manager said, “Really?”

I said, “In fact, that is a great idea. I will write a Hey, Scripting Guy! Blog post about it.”

And so I did…

Making Get-Help more helpful

Making Get-Help more helpful has always been a capability of Windows PowerShell. In fact, in my Windows PowerShell 1.0 Step by Step book, I included a function I called Get-MoreHelp. I even created an alias that I named GMH. The function accepts an input (the name of a cmdlet) and then calls Get-Help with the –Full parameter. Here is the Get-MoreHelp function:

Function Get-MoreHelp

{

 Get-Help $args[0] -full |

 more

} #End Get-MoreHelp

New-Alias -name gmh -value Get-MoreHelp -Option allscope

I then added this function to my Windows PowerShell profile, and now I have the Get-Help cmdlet working the way I want it to work.

Making Get-Help provide examples without scripting

One of the really cool features introduced in Windows PowerShell 3.0 was the $PSDefaultParameterValues automatic variable. This variable accepts a hash table that I can use to specify new default parameter values for any Windows PowerShell cmdlet. It is documented in the TehcNet Library: about_Parameters_Default_Values. In addition, my friend, Windows PowerShell MVP, David Moravec, wrote a really cool guest blog post that talks about how he uses this feature to simplify his scripts: Use PowerShell Default Parameter Values to Simplify Scripts.

How hard is it to use $PSDefaultParameterValues? Well, it is easier to use than to type it. (This is because in Windows PowerShell, we have Tab completion. Microsoft Word does not have Tab completion.) I provide a hash table with the cmdlet name, the parameter, and a value. Here is what I used to make Get-Help automatically provide examples:

$PSDefaultParameterValues = @{'Get-Help:examples'=$true}

Now when I type Get-Help and provide a cmdlet name, Help automatically returns those really cool examples that everyone loves. This technique is shown here:

If I like this, I add the command to my Windows PowerShell profile. If I want to override the behavior, I supply additional parameters (such as –Full). This command is shown here:

Get-Help Get-Process -full | more

Well, that is it. Talk to you tomorrow when I will have more way cool Windows PowerShell stuff.

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