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.
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.