Prof. Powershell

Hidden Treasure of the Example Sample

Get direct access to the Example property and you'll open new doors to knowledge.

• By Jeffery Hicks
• 10/12/2010

One of the things I love about PowerShell is the cmdlet documentation. In PowerShell 2.0 you can create advanced functions that also include this type of documentation. Normally, we simply read help information:

PS C:\> get-help get-service

But the Get-Help cmdlet, or the Help function, is actually writing objects to the pipeline. Run this command in a PowerShell session to see what I'm talking about:

PS C:\> get-help get-service | get-member

Because there is an object, we can select specific properties:

PS C:\> get-help get-service | select synopsis

Synopsis
--------
Gets the services on a local or remote computer

And while it's not intuitive, we can dig into the documentation examples and extract some useful information. The help object includes a property called Examples:

PS C:\> (get-help get-service).examples | get-member

TypeName: MamlCommandHelpInfo#examples

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
example     NoteProperty System.Management.Automation.PSObject[]
                         example=System.M...

This object has a property called Example. I know it looks a little funny, but we can directly access the examples. Try this command to see for yourself.

PS C:\> (get-help get-service).examples.example

I can see that there are 11 examples.

PS C:\> (get-help get-service).examples.example | measure-object

Count : 11
Average :
Sum :
Maximum :
Minimum :
Property :

These too, are objects:

PS C:\> (get-help get-service).examples.example | get-member

TypeName: MamlCommandHelpInfo#example

Name         MemberType   Definition
----         ----------   ----------
Equals       Method       bool Equals(System.Object obj)
GetHashCode  Method       int GetHashCode()
GetType      Method       type GetType()
ToString     Method       string ToString()
code         NoteProperty System.String code=get-service
commandLines NoteProperty MamlCommandHelpInfo#commandLines
                          commandLines=@{command...
introduction NoteProperty System.Management.Automation.PSObject[]
                          introduction=Sy...
remarks      NoteProperty System.Management.Automation.PSObject[]
                          remarks=System....
title        NoteProperty System.String title=
                          -------------------------- EXAMPLE 1...

Now for the fun part. Notice that code property? Here's what I think you'll find useful. Try this command in your PowerShell session:

PS C:\> (get-help get-service).examples.example | select code

The code property is usually the PowerShell expression in each example; although sometimes it includes additional text. Here is the next to last example's code property:

PS C:\> (get-help get-service).examples.example[-2].code

get-service winrm -requiredServices

Here's the slick part: let's run it. Yes, I know I could copy and paste it, but where's the fun in that? This is the PowerShell way:

PS C:\> invoke-expression (get-help get-service).examples.example[-2].code

Status  Name  DisplayName
------  ----  -----------
Running RPCSS Remote Procedure Call (RPC)
Running HTTP  HTTP

We use the Invoke-Expression cmdlet to execute the code property from the example.

Even if you never have the need to run help examples this way, I hope this lesson has reinforced the concept that everything in PowerShell is an object and using tools like Get-Member can help you discover some fascinating, and often hidden, treasures.

• Code Download