Prof. Powershell

Hidden Treasure of the Example Sample

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

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.

About the Author

Jeffery Hicks is an IT veteran with over 25 years of experience, much of it spent as an IT infrastructure consultant specializing in Microsoft server technologies with an emphasis in automation and efficiency. He is a multi-year recipient of the Microsoft MVP Award in Windows PowerShell. He works today as an independent author, trainer and consultant. Jeff has written for numerous online sites and print publications, is a contributing editor at Petri.com, and a frequent speaker at technology conferences and user groups.

comments powered by Disqus
Most   Popular

Upcoming Training Events