Let’s start with creating a new object, I’ll call $help_xml, and this time we’ll cast the object as XML. And there I go again with that word, cast. At it's most basic, all this means is that I will tell PowerShell to specifically interpret the file contents as XML and make the object an XML object. And as we saw from part 1, if I didn't do this, Get-Content would read in the XML file as plain text by default.

And here’s how I make sure Get-Content reads in the help file as XML. In an opened, PowerShell console, I type:

$help_xml = [xml] (Get-Content $pshome\en-us\System.Management.Automation.dll-Help.xml)

(Notice that the only difference between this object creation and the $help_plain from the part 1 is the [xml] type specification, which I've highlighted in red to make it perfectly clear.)

I get a different result from displaying the contents of this object:

PS C:\> $help_xml

xml                                                                               helpItems
---                                                                                 ---------
version="1.0" encoding="utf-8"                              helpItems

Much different from a listing of the file. That’s because my new object, $help_xml, has the properties and methods of an xml object. I know from various books and web tutorials that an xml file is structured so that the information is contained in elements with attributes. Knowing the structure of an XML file, i.e. what the elements inside a file are, will let you pull out the information by referencing the elements by name. And when you create a PowerShell object that represents XML information, then the elements and attributes in XML show up as properties of the PowerShell object. Quite a mouthful, but it translates into being able to use the PowerShell object dotted notation to find things in the object that represents an XML file read in by Get-Content.

Going back to our example, in the help file, we displayed the $help_xml file as a list of two properties called: xml and helpItems. How do I know this? Well, I can use the Get-Member cmdlet to see just the properties for the $help_xml object.

PS C:\> $help_xml | gm -MemberType properties

   TypeName: System.Xml.XmlDocument

Name                                               MemberType Definition
----                                                        ---------- ----------
helpItems          Property                 System.Xml.XmlElement helpItems {get;}
xml                      Property                 System.String xml {get;set;}

In the above definition the property, helpItems, is defined as an XML element. The way XML documents work is that they always start with a single top or root node and have child nodes inside that root node. (If you aren’t very familiar with XML, there are lots of tutorials on the web. A book I’ve used to learn about XML is the XML Pocket Consultant by William R. Stanek. And feel free to add other book references for XML in the comments section.)

Knowing that helpItems is the root node, I can “walk the tree” using PowerShell dotted notation.

PS C:\> $help_xml.helpItems

schema         #comment                            command                               providerHelp
------                 --------                                        -------                                         ------------
maml        { v 1.1.0.9 ,  v 1.1.0.9 ,...       {command:command, :...           {...

Now, I see there are 4 properties of the helpItems node. I can also look at the properties using Get-Member again.

PS C:\> $help_xml.helpItems | gm -MemberType properties

   TypeName: System.Xml.XmlElement

Name             MemberType Definition
----                    ---------- ----------
#comment        Property   System.Object[] #comment {get;}
command         Property   System.Object[] command {get;}
providerHelp    Property   System.Object[] providerHelp {get;}
schema            Property   System.String schema {get;set;}

I could keep walking down through these properties. And I plan to.

Specifically, the next blog posts will be about rifling through the command and providerHelp properties to ferret out the help information from the file. Once I see where the information is located I can start figuring out how to create some simple scripts to pull out the information. And then I should be able to run the script for any PowerShell help file.

In the meantime, feel free to roam around the files yourself to discover what’s there. As long as you don't write content back to the file (for example don't do a Set-Content), you should not have any effect to the help file itself. 

And if this sparks questions or comments, please do post them in the comments section of this blog.

I followed the process I'm going to talk through when I needed to build some quick scripts that checked all of our Windows Server help files to make sure we had completely filled out the required fields. But before I could write scripts to automate the file verification, I first needed to know what I was looking to verify.  So, in a sense, I’m more crawling through the file, than walking.

What Am I Looking For?

I can see the skeleton of the information I want from the help file when I run, get-help get-help –full and distill the titles of the sections. (I could have used any cmdlet to see the section headers, so generalized it would be get-help <cmdlet name> -full

NAME

SYNOPSIS

SYNTAX   

DESCRIPTION   

PARAMETERS

INPUTS

OUTPUTS 

NOTES

     -------------------------- EXAMPLE 1 -------------------------- 

                               …

        -------------------------- EXAMPLE 15 --------------------------

RELATED LINKS

Rereading the PowerShell Help File (recap from last blog post)

In the past blog post, I had made it down to the level where I could see an element known as command. I've repeated the two sets of commands here so we can get started together (I’ve highlighted the two lines of commands I typed in):

PS C:\> $help_xml = [xml] (Get-Content $pshome\en-us\System.Management.Automation.dll-Help.xml)

PS C:\> $help_xml.helpItems | gm -MemberType properties

   TypeName: System.Xml.XmlElement

Name         MemberType Definition
----         ---------- ----------
#comment     Property   System.Object[] #comment {get;}
command      Property   System.Object[] command {get;}
providerHelp Property   System.Object[] providerHelp {get;}
schema       Property   System.String schema {get;set;}

Let’s go down one level to see what child nodes are inside the command XML node: (How did I know to look at the command node? Well, I want to see information for cmdlet help. This pretty much rules out the other three nodes based on their names.)

PS C:\> $help_xml.helpItems.command | gm -MemberType properties

   TypeName: System.Xml.XmlElement#http://schemas.microsoft.com/maml/dev/command/2004/10#command

Name                 MemberType Definition
----                 ---------- ----------
#comment             Property   System.Object[] #comment {get;}
alertSet             Property   System.Xml.XmlElement alertSet {get;}
command              Property   System.String command {get;set;}
description          Property   System.Xml.XmlElement description {get;}
details              Property   System.Xml.XmlElement details {get;}
dev                  Property   System.String dev {get;set;}
examples             Property   System.Xml.XmlElement examples {get;}
inputTypes           Property   System.Xml.XmlElement inputTypes {get;}
maml                 Property   System.String maml {get;set;}
nonTerminatingErrors Property   System.String nonTerminatingErrors {get;set;}
parameters           Property   System.Xml.XmlElement parameters {get;}
relatedLinks         Property   System.Xml.XmlElement relatedLinks {get;}
returnValues         Property   System.Xml.XmlElement returnValues {get;}
syntax               Property   System.Xml.XmlElement syntax {get;}
terminatingErrors    Property   System.String terminatingErrors {get;set;}

So, it looks like $help_xml.helpItems.command contains the cmdlet help topics I'm interested in. Some of the element/property names correspond to the section titles I’m looking for: description, examples, syntax, parameters, relatedLinks. Others seem close: inputTypes and returnValues. I don’t see notes, but there is an element called details, which might have more information.

Instead of looking at the properties of the $help_xml.helpItems.command members, let’s look at what happens when I just type $help_xml.helpItems.command  and press enter from the PowerShell command line:

PS C:\> $help_xml.helpItems.command

maml                 : http://schemas.microsoft.com/maml/2004/10
command              : http://schemas.microsoft.com/maml/dev/command/2004/10
dev                  : http://schemas.microsoft.com/maml/dev/2004/10
details              : details
description          : description
#comment             : { Cmdlet syntax section,  Cmdlet parameter section  ,  Input - Output section,  Error section...
                       }
syntax               : syntax
parameters           : parameters
inputTypes           : inputTypes
returnValues         : returnValues
terminatingErrors    :
nonTerminatingErrors :
alertSet             : alertSet
examples             : examples
relatedLinks         : relatedLinks

…

I’ve only displayed the first command that is spewed when you type $help_xml.helpItems.command. What you’ll see if you try this for yourself is a spew of listings that all appear the same – no actual information, though. Because we’re seeing multiple copies, I suspect that command is actually an array. Let’s look at the first element of command details.

PS C:\> $help_xml.helpItems.command[0].details

name        :
                                 Add-History

description : description
copyright   : copyright
verb        : Add
noun        : History
version     :

Woo hoo! OK, we’ve hit pay dirt here. Here is the name (Add-History) along with more elements providing verb (Add) and noun (History). And if we want to display just the name of the cmdlet we can run:

PS C:\> $help_xml.helpItems.command[0].details.name

                   Add-History

But maybe we want to look at a different command, maybe the 100th command in the file. If we do this here’s what we see:

PS C:\> $help_xml.helpItems.command[100].details
PS C:\>

Not very enlightening, but unless we specifically setup to trap an error, we might not see one. I’m guessing we might have put in too large an index for the array of $help_xml.helpItems.command We can find length of the array (number of cmdlets that have help specified in this file) by running:

PS C:\> $help_xml.helpItems.command.length
42

Because PowerShell arrays are zero indexed, the maximum index is length - 1. In this case, if we keep the index to ((length=42) - 1) = 41 and under, we’ll get a result. For the index 41,

PS C:\> $help_xml.helpItems.command[41].details

name        :
                                 Where-Object

description : description
copyright   : copyright
verb        : Where
noun        : Object
version     :

Let’s go a little further and see what’s under description:

PS C:\> $help_xml.helpItems.command[41].details.description

para
----
Creates a filter that controls which objects will be passed along a command pipeline.

Comparing to the results from Get-Help Where-Object –full, this looks like what we’ve been seeing as the synopsis. That means we can get the short description or synopsis  text directly with the dotted notation with para at the end:

PS C:\> $help_xml.helpItems.command[41].details.description.para
Creates a filter that controls which objects will be passed along a command pipeline.

To Recap What We’ve Found in the PowerShell Help File So Far

We’re still looking for syntax, full description, parameters with description, inputs, outputs, notes, examples, and related links. Feel free to look around for these on your own. I will be continuing to hunt down more information within the PowerShell help file in the next blog post.

And again, let me know what other XML files you think we should walk through as an exercise when we’re done with this file. Feel free to post suggestions in the comment sections of this post. Looking to hear from you soon. -- Judith

Reading a PowerShell Help File with Get-Content as Plain Text

I’m going to define an object called, $help_plain, that represents the contents of the help file when read using Get-Content:

$help_plain=Get-Content $pshome\en-us\System.Management.Automation.dll-Help.xml

And when I type the name of the object and press enter,

$help_plain

the whole contents of the help file will be spewed. The listing for several of the lines look something like this:

PS C:\> $help_plain
<?xml version="1.0" encoding="utf-8" ?>

<helpItems schema="maml">

<!-- v 1.1.0.9 -->
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/mam
l/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
        <command:details>
                <command:name>
                   Add-History
                </command:name>
                <maml:description>
                        <maml:para>Appends entries to the session history.</maml:para>
                </maml:description>
                <maml:copyright>
                        <maml:para></maml:para>
                </maml:copyright>
                <command:verb>Add</command:verb>
                <command:noun>History</command:noun>
                <dev:version></dev:version>
        </command:details>
        <maml:description>
                <maml:para>The Add-History cmdlet adds entries to the end of the session history, that is, the list of commands entered during the current session.

...

Now, this looks suspiciously like a listing of the file, if I were to just type it or open the file in notepad. Except, what I have is the contents of the file in an object that has read in each line separately. So, this object can be thought of as an array of lines of text.

If I want to see only the first line of the file, then I can add the index position to the object:

$help_plain[0]

Displays the first line of the file:

<?xml version="1.0" encoding="utf-8" ?>

As a side note, the book “Windows PowerShell 2.0 Administrator’s Pocket Consultant” by William R. Stanek, has a nice chapter on working with arrays. On page 161, he shows how you can use the range operator (..) with an array. In my case, I might want to display say the first ten lines of the help file that was read into the $help_plain object.

PS C:\> $help_plain[0..9]
<?xml version="1.0" encoding="utf-8" ?>

<helpItems schema="maml">

<!-- v 1.1.0.9 -->
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/mam
l/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
        <command:details>
                <command:name>
                   Add-History
                </command:name>

In the above, I'm already seeing an element from the help file called, name. And the element contains a name of a cmdlet called, Add-History. Go figure. So, it looks like if we grovel through the file, we should be able to figure out which elements contain the information I want to pull out of the file. And if I could search by elements that would be helpful. But in the current form that I've read in, I'm stuck with having to parse out the text because that's how I've read in the file as plain text.

So, to recap, I was able to read in the help file, but it came in as plain text, which doesn’t help me with parsing the information in the file. On the upside, I learned that the file was read in one line per array element and I can display separate lines from the file using the element notation [] and range operator [..]

To get what I want out of the help file, I’ll have to try a different way. That’s what I’ll do in the next blog post.

dir $PShome\en-us\*.xml

Which returns the following list of files for my system:

    Directory: C:\Windows\System32\WindowsPowerShell\v1.0\en-us

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         6/10/2009   3:37 PM     160510 Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml
-a---         6/10/2009   3:22 PM    1957661 Microsoft.PowerShell.Commands.Management.dll-Help.xml
-a---         6/10/2009   3:22 PM    1602040 Microsoft.PowerShell.Commands.Utility.dll-Help.xml
-a---         6/10/2009   3:22 PM      15869 Microsoft.PowerShell.ConsoleHost.dll-Help.xml
-a---         6/10/2009   3:22 PM     154493 Microsoft.PowerShell.Security.dll-Help.xml
-a---         6/10/2009   3:37 PM     538884 Microsoft.Wsman.Management.dll-Help.xml
-a---         6/10/2009   3:22 PM    1268150 System.Management.Automation.dll-Help.xml

Now, I’m going to pick the last file in the list, System.Management.Automation.dll-Help.xml

Why that one? Well, I cheated. I already know this is the help file that contains the help text for the basic PowerShell commands, like Get-Help. But all the files are structured the same way. Once I show you how to walk through one help file, you can do the same thing for any of the help files. Even for modules or snap-ins. That’s the beauty of XML files. They're all structured the same way.

We’ve found some files that we can look at together because these files come with PowerShell 2.0. And now that I know you can follow along in the coming blog entries here’s what I’m going to do:

1. Read a PowerShell help file using Get-Content as Plain Text (Reading the file part 1 of 2)
2. Read a PowerShell help file using Get-Content as XML (Reading the file part 2 of 2)
3. Navigate through the Lower Depths of the PowerShell Help File
4. Now, let’s start automating parsing the PowerShell help file

So, I’m going to share a secret that I learned from reading chapter 8 of the “Windows PowerShell Cookbook” by Lee Holmes.

Yikes! What is this cast business and why can’t I speak English anymore? Is what I’m sure you’re asking. And how is this making anything easier.

Let’s take this one step at a time. Most PowerShell books will teach you to read in a file using the Get-Content cmdlet. The description of what Get-Content does is: 

The Get-Content cmdlet gets the content of the item at the location specified by the path, such as the text in a file. It reads the content one line at a time and returns an object for each line.

This definition tells me that Get-Content will read in the contents from a file as plain text.

Plenty of PowerShell books show you how to do this. However, if you read in the file as plain text, you are back to parsing through the text. And for XML files, I will be using my above secret to show you a much, much easier way. But before I can do that I have to find a file that all of us can look at together. That way you can follow along with me. And that’s what I’m going to do in the next blog post.

Stay tuned…

(Oh, and while you’re waiting, if you have suggestions of XML files from Windows Server that you’re wondering how to take them apart with PowerShell, please list the files in the comments section. Once I get going we’ll look at a number of suggestions.)

But I’m back now and ready to go with talking about easy tips and tricks for PowerShell 2.0.

If there are things you have been trying to do with PowerShell, especially with administrating Windows, feel free to list those tasks in the comments section.

Or if you have tricks you’d like to share, feel free to list those tips and tricks in the comments section.

Sorry to be gone so long. Glad to be back.

------------------------------------------------------

If you've played around with PowerShell on Windows Server 2008 R2 then you already know that you can add cmdlets for different roles and features. And these cmdlets are contained in different modules or snap-ins that must be imported or added each time you open a new PowerShell window. Pretty lame, but wait, there's actually a way to add all modules and snap-ins at one time.

And you can read about it here: Getting Started PowerShell on Windows Server 2008 R2.

However, getting the list and moving that list into a spreadsheet where I could use it for reports, etc. required extra processing. For example, in my little one DC test domain, I can run nltest even in Windows PowerShell.

The output looks sort of like it's in columns. I have PDC information, DC information and a site name. It also displays the name of the domain. It's just not in the labeled columns I had in the previous examples. Since this topic is still about the Out-GridView cmdlet, I wondered what would happen if I ran the output of nltest into the input of Out-GridView. And here's what happened:

Everything was smooshed into one column. The heading for this column is interesting, although, expected once I thought about it. The executables were written to output a string of text. In Windows PowerShell the variables, output from cmdlets, and essentially any output is an object. And it makes sense that a string of text would be a String object. So, it all makes sense, but is not all that useful for creating a report for a large number of DC's.

Now, thinking back to the AD PowerShell Cookbook, that I sent a link to several posts back, I bet I can find a new cmdlet that will output some type of DC object that would be useful with the Out-GridView cmdlet. Sure enough, there's a topic called, "Finding the Domain Controllers for a Domain" which should give me the information I need. In my case, I can run the following in Windows PowerShell on my Windows Server 2008 R2 machine where my domain name is Corp1.contoso.com.

Get-ADDomainController -Discover -DomainName Corp1.contoso.com

And the output looks like:

This looks like columns turned into rows, differently arranged than get-help or get-process output, but still potentially useful. The best thing I have found with Windows PowerShell is that when in doubt, it's better to just try it out. So, I next reran the same cmdlet and then piped the output to the Out-GridView cmdlet to get the following result:

And yes, this is absolutely in the format that I can use to create a nice display with all the headers that appeared in the output from the Get-ADDomainController cmdlet.

Okay, so with only one DC, it is sort of lame, but think what a nice report you can generate if you had a larger number of DC's. And the best part is you can generate this display on the fly.

Next post, I'll look at one more example with Out-GridView and then probably move on to a new cmdlet. (Gasp, finally.) Stay tuned. :-)

• Where to find what's new with Windows Server 2008 R2
• Where to find what's new with Windows 7 client
• AD PowerShell Cookbook
• Group Policy's new Windows PowerShell cmdlets
• Server Manager's new Windows PowerShell cmdlets
• Installing and running Windows Server Migration tools using Windows PowerShell
• What's new in Windows PowerShell
• What roles and features in Windows Server 2008 R2 provide cmdlets for scripting administration tasks

So, I went back to the help for the Out-GridView cmdlet. I ran:

Get-Help Out-GridView

The first line of the detailed description gave me the best clue to the simplest answer to my question of how does Out-GridView figure out what column headings to use. The line I'm referring to states, "The Out-GridView cmdlet sends the output from a command to a grid view window..." (Obviously, there's more to the help for Out-GridView. While it's all worthwhile reading, my goal is just to highlight this specific nugget of information.)

What does sending the output from a command to a grid view window mean with regards to the column headings?

I picked two examples that everyone uses to illustrate the meaning for myself. At it's simplest level, I ran the Get-Help * and the Get-Process cmdlets in the Windows PowerShell directly and then with the output piped to the Out-GridView cmdlet. And here's what I found.

Example 1: Get-Help *

Running Get-Help * cmdlet directly in Windows PowerShell displays three columns with headings called: Name, Category, and Synopsis. In the below picture, I've scrolled back to the beginning of the output so I can see the headings.

And now compare this to the separate window created when I pipe the output from Get-Help * into the Out-GridView cmdlet (Get-Help * | Out-GridView).

Notice the column headers are the same as the ones printed in Windows PowerShell when I ran Get-Help * as in the first picture.

Example 2: Get-Process

It sometimes helps me to repeat the experiment with a different cmdlet just to make sure the first try wasn't a fluke. I'm going to compare the output of the Get-Process cmdlet with the column headings in the grid view window when I pipe the output from the Get-Process cmdlet to the Out-GridView cmdlet.

And to save space in this blog post, this time I'll just show the column headings this time.

Here's the headings I see when I run Get-Process in Windows PowerShell:

And here's the headings for the grid view window when I've piped the output from Get-Process to Out-GridView, in other words, Get-Process | Out-GridView.

With the pictures scoped down to just so the headings, it is pretty obvious they are the same.

An off the topic, BTW here... Notice, that for Get-Process I ran ps. This is known as an alias. An alias lets you use a shorthand instead of always typing out the full cmdlet name. For more information take a look at the about_Aliases topic on Technet or type the following in Windows PowerShell.

 get-help about_Aliases

Now, the next question I have is still where do these column headings come from, in other words, they represent something about the output of the cmdlet. But what is that?

Do I need to know this in order to use the Out-GridView cmdlet to analyze information I'm getting from other cmdlets? I would say, no, I can use these cmdlets with what I now know.

Next post I plan to walk through more examples showing different aspects of the Out-GridView cmdlet and how it comes in handy for things like analyzing event logs. A pretty nice feature of using Out-GridView.

Or, I can follow down the question habit trail of what these column headers represent. In other words, I would ask, "Tell me about Windows PowerShell objects and how understanding this will help me do more with the output of cmdlets?"

If you prefer one topic over the other, let me know and I can shift to following down the trail of thought to look at objects. Just want to avoid that squeaky old hamster wheel....

So, till next post, try out some of your own cmdlets with Out-GridView. Post comments on things you've tried and what you want to talk about next. And thanks for listening.  --- Judith Herman

This is a huge document, both in number of pages and accomplishment. I've played around with the Active Directory since Windows 2000. I found the Active Directory PowerShell Cookbook covers tasks that I hadn't even thought of doing. And it presents all these tasks through the new Active Directory PowerShell cmdlets available in Windows Server 2008 R2 beta.

Why take a diversion from the Out-GridView cmdlet to mention this?

First, I think this is the best kept secret of the Windows Server 2008 R2 content releases.

Second, now that this information is publically available, I plan on using these cmdlets in some of my examples. So, take a look at the cookbook and stay tuned.

Oh, and please send in comments or questions on what you'd like to see in examples as we slowly work our way through some of the new awesome cmdlets for Windows PowerShell 2.0.