Leveraging Windows PowerShell Type Extensions to get documentation

Leveraging Windows PowerShell Type Extensions to get documentation

Rate This
  • Comments 12

After just a little use of Windows PowerShell, you quickly learn that you need to pipe objects in the GET-MEMBER utility to understand the capabilities of that object.  Get-Member reflects against the object and shows you all of its methods and properties (more as well but that will be a different blog).  Get-Member is getting that information from the metadata about the type but the issue is that the metadata doesn't have any documenation about what the properties are or what the methods do.  Now mostly that doesn't matter because it is obvious but occassionally it does.  Here is how I handle that problem;

Below is an XML fragment from my MY.TYPES.PS1XML file that gets loaded during startup.  In my profile is a line:

Update-TypeData c:\ps\My.Types.Ps1xml

If you want to see an example of how this file needs to be written, you can do the following:

notepad  (join-path $pshome types.ps1xml)

Anyway - one of my entries is this:

<Type>
    <Name>System.Object</Name>
    <Members>
      <ScriptMethod>
        <Name>MSDN</Name>
        <Script>
if (($global:MSDNViewer -eq $null) -or ($global:MSDNViewer.HWND -eq $null))
{   $global:MSDNViewer = new-object -ComObject InternetExplorer.Application
}
$Uri = "http://msdn2.microsoft.com/library/" + $this.GetType().FullName + ".ASPX"
$global:MSDNViewer.Navigate2($Uri)
$global:MSDNViewer.Visible = $TRUE
        </Script>
      </ScriptMethod>
    </Members>
</Type>

 

Then I can do things like:

$d=get-date
$d.MSDN()

and it will fire up IE and show the documentation for this type.
Note that I attached this property to System.Object so absolutely every object now has this method.  Pretty cool huh?

Jeffrey Snover
Windows PowerShell Architect
(Can you believe that they actually pay to work on this Windows PowerShell - is that a deal or what!  We're still hiring http://blogs.msdn.com/powershell/archive/2006/05/04/590382.aspx)

PSMDTAG:FAQ: How can I find out what an Object can do?
PSMDTAG:FAQ: How can I get at the MSDN documenation for an object?
PSMDTAG:TYPEEXTENSION: MSDN Method on System.Object
PSMDTAG:DOCUMENTATION: Adding a method to all objects to get their MSDN Documentation

Leave a Comment
  • Please add 2 and 6 and type the answer here:
  • Post
  • This is a great illustration of PowerShell's flexibility. You can customise this a bit further to automatically open localised MSDN content. I was thinking of passing the culture to MSDN() as a parameter (e.g. MSDN("fr-fr")) but you can also leverage $host.currentculture in the script:

    $Uri = "http://msdn2.microsoft.com/" + $host.currentculture + "/library/" + $this.GetType().FullName + ".ASPX"^

    On my computer, this will automatically open the type documentation in French. Isn't that even better? :-)

    Jacques
  • I have modified it again so it can take a parameter. By default MSDN will try the current culture (as shown by $host.currentculture) and if for some reason you need to bypass default settings you can enter the culture string of your choice, eg:

    (get-date).MSDN("es-es") # MSDN page in Spanish

    Here is the updated <type> snippet:

    <Type>
       <Name>System.Object</Name>
       <Members>
         <ScriptMethod>
           <Name>MSDN</Name>
           <Script>
    $culture = $host.currentculture
    if ($args[0])
    {
    $culture = $args[0]
    }

    if (($global:MSDNViewer -eq $null) -or ($global:MSDNViewer.HWND -eq $null))
    {
    $global:MSDNViewer = new-object -ComObject InternetExplorer.Application
    }
    $Uri = "http://msdn2.microsoft.com/" + $culture + "/library/" + $this.GetType().FullName + ".ASPX"
    $global:MSDNViewer.Navigate2($Uri)
    $global:MSDNViewer.Visible = $TRUE
           </Script>
         </ScriptMethod>
       </Members>
    </Type>

    Jacques
  • In my customization, I added these 2 lines at the end of script area, to also activate the Internet Explorer window:

    $ShellObj = New-Object -ComObject WScript.Shell
    $ShellObj.AppActivate((Get-Process | Where {$_.MainWindowHandle -eq $global:MSDNViewer.HWND}).Id)

    I wonder if that could be done by just using PowerShell existent cmdlets though.

    PowerShell is so cooool. I love it! Working with objects at the command line - the idea is just brilliant!
  • &amp;lt;Edited to add categories&amp;gt;In our active, responsive, and useful newsgroup Microsoft.Public.Windows.PowerShell...
  • Here is an even shorter script that will start your default browser, be it IE, FireFox, Opera, Whatever:

    $culture = $host.currentculture
    if ($args[0])
    {
    $culture = $args[0]
    }
    $Uri = "http://msdn2.microsoft.com/" + $culture + "/library/" + $this.GetType().FullName + ".ASPX"
     
    [System.Diagnostics.Process]::Start($uri) | out-null
  • Also if you change the begining of $Uri to http://windowssdk.msdn.microsoft.com/ you'll get docs for all the PowerShell and .Net 3.0 objects. Handy.
  • gfg
  • When used with a COM object, the method throws an exception because it cannot reflect out the GetType method.

  • An added "Select" makes it work with collections. It gets the .NET help for the type of the first object in the collection.

    $Uri = "http://msdn2.microsoft.com/" + $culture + "/library/" + ($this | select -first 1).GetType().FullName + ".ASPX"

    Otherwise, you get "Content Not Found" for:

    (get-process).msdn(), which will confuse beginners.

  • PingBack from http://www.keyongtech.com/2835580-active-directory-search

Page 1 of 1 (12 items)