UPDATED 2009-03-11: BUGFIXES FOR CTP3! PLEASE RE-DOWNLOAD v0.2.1
One of the things I hear now and then is that while PowerShell the language can be mastered with the requisite effort, the .NET namespace is considerable harder to get a handle on. Wouldn’t it be nice if you could type things like:
PS> get-help -object [string]::format
Since Functions take precedence over native Cmdlets in the command search order, the first thing you might think is to create a function with the same name, get-help, that can do this. The function itself would have the same parameters as the native Cmdlet, and add one of its own: -object. If the arguments do not belong to the “object” ParameterSet, then the function would splat (using the @ operator) the original arguments to the native Cmdlet transparently and transfer control. The user is none the wiser we had a quick peek at the arguments. So, before we run off duplicating a Cmdlet’s surface through script, first stop, Command Proxies!
First off, required reading: Extending and/or Modifying Commands with Proxies. Ok, now that you’ve got read that entirely and gotten it out of the way, you understand that the [ProxyCommand]::Create(…) method lets you automatically generate a function that delegates to a steppable pipeline wrapping the original Cmdlet, right? What I did then is to pack all of these functions into a psm1 module, create a nice psd1 module manifest and away we go.
So here’s a quick look at the help for my module, in friendly, easy to read Cmdlet help style. The code for the PSM1 module file is way too large to dump here on my blog like I would usually do, so it’s available at as an attachment at the foot of the page. This help below is in a comment in the psm1 file itself.
NAME ObjectHelp Extensions Module 0.2 for PowerShell 2.0 CTP3 SYNOPSIS Get-Help -Object allows you to display usage and summary help for .NET Types and Members. DETAILED DESCRIPTION Get-Help -Object allows you to display usage and summary help for .NET Types and Members. If local documentation is not found and the object vendor is Microsoft, you will be directed to MSDN online to the correct page. If the vendor is not Microsoft and vendor information exists on the owning assembly, you will be prompted to search for information using Microsoft Live Search. TODO * localize strings into PSD1 file * Implement caching in hashtables. XMLDocuments are fat pigs. * Support getting property/field help * PowerTab integration * Test with Strict Parser EXAMPLES # get help on a type PS> get-help -obj [int] # get help against live instances PS> $obj = new-object system.xml.xmldocument PS> get-help -obj $obj or even: PS> get-help -obj 42 # get help against methods PS> get-help -obj $obj.Load # explictly try msdn PS> get-help -obj [regex] -online # go to msdn for regex's members PS> get-help -obj [regex] -online -members CREDITS Author: Oisin Grehan (MVP) Blog : http://www.nivot.org/ Have fun!
So what does it actually look like when you call help? If the help is available locally, it is displayed inline in the console (or ISE). Help for all types in MSCorlib and System is pre-cached. Any other help for types in assemblies belonging to the BCL (Base Class Libraries – effectively the stock .NET assemblies) will be loaded on-demand. This typically takes just a few seconds and will cached for the rest of your session.
Right now, it cannot deal with properties. That is to say, trying:
PS> get-help –object $s.length
where $s is a string, will get help on the property _type_, not the property itself. I have some ideas to get around this, so if you can wait for 0.3, I’d be happy. Of course you can wait. You have no choice. :D
The two files come in a zip file. Unzip this file to ~\documents\windowspowershell\modules\objecthelp\ where ~ is your home directory. On vista/win7 this would be c:\users\username. On XP, it would be c:\documents and settings\username. To load it, just execute:
PS> import-module objecthelp
That’s it! Have fun!
Page rendered at Sunday, March 14, 2010 12:17:20 AM (Eastern Standard Time, UTC-05:00)