Blog:\>_ : XPath

How to change output format in PowerShell

sergeia — Fri, 29 Aug 2008 09:03:00 GMT

I was looking around the Net today and stumbled on the post in Scott Hanselman's blog, where he talks about technical and marketing aspects of product naming in Microsoft. There he shows display format for IIS application pools that may be relevant to servers, where admins keep multiple versions of CLR and run applications in various modes. This output includes managed runtime version for the pool and mode (integrated or classical) for the pool. By default IIS provider shows only name, state and list of applications, assigned to this pool. It is pretty easy to change this output to what Scott prefers.

Open file iisprovider.format.ps1xml (name could be changed in next release) and find view, defined there for application pool. This will be piece of XML tagged by type name "Microsoft.IIs.PowerShell.Provider.NavigationNode#AppPool". This typename means that as soon as PowerShell will find object in the output stream, which has this type name in its typenames collection, it will use this view. View selected once for the first object in output stream -- this is pretty annoying shortcoming in PowerShell because in IIS configuration it is common to have objects of multiple types in output.

OK, now you have to create new XML file with the name you like, and extension "format.ps1xml", say PoolModeView.format.ps1xml. Then add there header and footer:

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

  </ViewDefinitions>
</Configuration>

Select whole section with pool view in original file and copy it into your new file. We will modify this view to add new columns. We have to change name of the view first. Let's name it "appPoolModeView". Then add new column definitions after the State column:

<TableColumnHeader>
  <Label>State</Label>
  <Width>12</Width>
  <Alignment>left</Alignment>
</TableColumnHeader>
<TableColumnHeader>
  <Label>CLR Version</Label>
  <Width>12</Width>
  <Alignment>left</Alignment>
</TableColumnHeader>
<TableColumnHeader>
  <Label>Mode</Label>
  <Width>12</Width>
  <Alignment>left</Alignment>
</TableColumnHeader>

That will be our column headers. We have to define, what to show in these columns. After section TableColumnItem for State, add the following:

<TableColumnItem>
  <PropertyName>State</PropertyName>
</TableColumnItem>
<TableColumnItem>
  <PropertyName>managedRuntimeVersion</PropertyName>
</TableColumnItem>
<TableColumnItem>
  <PropertyName>managedPipelineMode</PropertyName>
</TableColumnItem>

We will display two properties that identify CLR runtime and mode. Now we could save our file. In PowerShell window run the following command:

PS C:\ #> Update-FormatData -prependpath <path-to-your-file>

Depending on your settings in PowerShell you may see an error, because new file is not signed. As a long term solution you will need to sign this file the same way you are signing scripts, for now you could relax execution policy to RemoteSigned.

Let's see what we get:

PS C:\ #> cd iis:\apppools

PS IIS:\AppPools #> dir

Name                  State     CLR Version  Mode         Applications
----                  -----     -----------  ----         ------------
DefaultAppPool        Started   v2.0         Integrated   Default Web Sit
                                                          e
                                                          mysite
                                                          /appDefault
                                                          /myapp
Classic .NET AppPool  Started   v2.0         Integrated
newPool               Started   v2.0         Integrated

If you want to have this view, but don't like to use it by default, run update-formatdata without -prependpath. PowerShell will add your view to the internal tables, but still will use the old one. To enable new output format, add "format-table -view apppoolmodeview" to your output command, and you will get this view.

PS IIS:\AppPools #> dir | ft -view appPoolModeView

XPath in output formatting

While we discussing output formatting, let me show how you could extend output for any object by adding pieces of script into the view. This script block could get any data and add it to your output. Look how I did it for application pool view. The last column shows applications, assigned to this pool. But pool structure doesn't include any indication about applications. To find which applications belong to the pool, we have to look through all applications and select those having property "applicationPool" set to the name of our pool. Let's take a look how we form column for applications (I inserted back ticks into long lines to fit them on screen):

<TableColumnItem>
  <ScriptBlock>
    $pn = $_.Name
    $sites = get-webconfigurationproperty `
      "/system.applicationHost/sites/site/`

      application[@applicationPool=`'$pn`'and `

      @path='/']/parent::*" `
      machine/webroot/apphost -name name
    $apps = get-webconfigurationproperty `
      "/system.applicationHost/sites/site/`

      application[@applicationPool=`'$pn`'and `

      @path!='/']" `
      machine/webroot/apphost -name path
    $out = ""
    foreach ($s in $sites + $apps) {$out = $out + $s + "`n"}
    $out = $out.Substring(0, $out.Length - 1)
    $out
  </ScriptBlock>
</TableColumnItem>

In our namespace we are hiding root applications and root virtual directories, and moved their properties to sites. That's another XPath query, but in namespace definition for site. Because we need both sites and applications, scriptblock runs two queries. First it selects all root applications (with path'/') that are assigned to our pool (with name $pn). For each path query selects parent node for application, i.e. site, and returns name of this site. Second query selects names of all non-root applications with the same setting. Next line does the trick that shows all entries inside of column -- it appends each name from combined list to the string variable, and adds symbol <CR> after that. Then script removes the last <CR> and outputs the resulting string. When output module in PowerShell formats the view, it wraps strings inside of column, and inserted <CR> symbols point to end of each row.

Certainly, one could write script block that doesn't use XPath, but this would be much longer code with multiple loops and conditions. XPath takes one query string and returns result with minimal overhead.

Enjoy,

Sergei Antonov

How we use XPath in IIS PowerShell namespace

sergeia — Thu, 28 Aug 2008 07:18:00 GMT

IIS 7 configuration API's were designed as DOM: you always have to start from top level data structure and work your way to the data you need, either collection element or child element attributes. It is quite annoying model when you are building generic tools, and soon we started looking for some way of cutting off amount of code required for access of internal collections and attributes. At some moment we realized that we could use System.Xml.XPath.XPathNavigator type to expose IIS configuration. This type could be used to represent any hierarchical data as tree for XPath queries, not necessarily originated in XML. That was a perfect fit: with XPath query we could access any entity inside of configuration in one step. First CTP of provider was based on this approach. It worked nice but was pretty slow. Keeping XPath engine in managed code introduced major performance bottleneck: configuration data are in non-managed code, and XPath engine should marshal across the border every piece of data during processing of query. To make it better, fearless IIS developer William Moy created XPath query processor in native code, following the same model as XPathNavigator, and second CTP of provider is based on this engine. It is so effective, that when we access internal data inside of configuration section using fully qualified path it takes in average only 10% longer than using straight code based on explicit configuration API's, when this code accesses the same data. Fully qualified here means that path points to the unique data inside of configuration, and query don't need to walk around big parts of tree. As you probably know, configuration system in IIS 7 is distributed, and is merged from multiple configuration files located in root folders of virtual directories and file system folders below them. Path that points to any of these containers for configuration files named commit path. XPath engine works with the search tree built from IIS configuration sections, merged from files which were gathered along some commit path. The tree has root, represented by root section group, then it includes child groups and sections, then child elements and collection elements, so it is kind of like Object Viewer tree in Visual Studio, rather than file system tree. If written properly, XPath query could return just one unique piece of data from configuration, in that case we could use it as universal addressing format for configuration data. Or it could select set of nodes from the search tree, in that case it is good to describe groups of data, for example, all sites, or all applications of the site, etc. If we store these queries into some place, we could describe our own namespace, composed from data extracted from configuration by these stored queries. XPath queries are the backbone of IIS 7 PowerShell namespace: if you open file NavigationTypes.xml, you will see that most of things in the namespace are described as XPath queries, for example,

<virtualDirectory>
...
<InstanceXPath>%parent::InstanceXPath%/virtualDirectory[@path="%path%"]</InstanceXPath>
...
<children>
    <childInfo>
      <childType>fileDirectory</childType>
      <xPath>%InstanceXPath%/physicalPath</xPath>
      ...
    </childInfo>
    <childInfo>
      <childType>file</childType>
      <xPath>%InstanceXPath%/physicalPath</xPath>
      ...
    </childInfo>
</children>
</virtualDirectory>

This description instructs code in provider how to list virtualDirectory namespace nodes, how to produce list of child nodes for this node. Names in %% are macros referring to namespace object properties, or its parent properties. When user wants to get object, provider resolves InstanceXPath using specific instance as parent and sends expanded query strings to XPath engine, then it uses resulting selection to build namespace object. This approach is very flexible: if I want to rearrange the tree, all I need to do is to modify this XML file; if I want to add new namespace type, based on configuration object from some section, in most cases I only add its description to this XML tree. After restart of PowerShell IIS provider will resolve it and new type will be exposed in the namespace. Format of namespace description was changed a bit after CTP2 to enable addition of new description files, so you could use this model to extend our namespace and include your objects.

XPath queries directly accessible for user through base level commands: get-webconfiguration and set-webconfiguration. There are two more commands that work with properties, they also consume XPath queries to address object owning properties. Our XPath engine actually works with two trees, one combined from sections, elements and attributes, and another one -- from commit paths. This commit path engine is used, for example, when we want to retrieve configuration recursively starting from some entry point on commit path tree, say, from some particular site. When you run command

get-webconfiguration /system.webServer/asp/limits/@requestQueueMax "iis:\sites\default web site" -recurse

it will return all setting for asp section attribute requestQueueMax, existing down the tree from "Default Web Site". To direct query down the tree, provider internally resolves namespace path, and when -recurse is specified, converts it into "MACHINE/WEBROOT/APPHOST/Default Web Site/descendant-or-self::node()". This expression tells query engine that it should not limit search by one level, and should go down the tree. Another part, configuration XPath is also modified to "/system.webServer/asp/limits/@requestQueueMax[is-locally-defined()]". Function in square brackets is specific to IIS configuration navigator, it returns "true" if attribute was defined on some particular level, otherwise query will return all inherited values for this attribute. Our XPath engine defines several functions like this one, I will describe all of them later.

This is an example of simplest XPath query. You could write much more complicated expressions and get more specific data from configuration. I recommend to learn a bit about XPath, if you want to use our "platform" level functionality to write you own scripts and functions in PowerShell, you will be surprised, how much you could achieve in just couple of line. You could find pretty good practical courses in XPath in many places in the Net, some sites offer visual XPath editor that shows result of your query applied to sample data file.

Almost all helper commands that we released in CTP2 were built very quickly and are all based on base level commands. Each simplified cmdlet is nothing more but piece of code that declares parameters, then compiles low level command from user input and calls get-webconfiguration or other command. You could do the same for cmdlet specific to your needs. If you are using PowerShell v2.0, you could write script based cmdlets instead of compiled code. Let me show you one example of helper command.

PS IIS:\#> get-command new-webbinding | select definition | fl *

Definition : New-WebBinding [-Site] <String> [-Port <UInt32>] [-IPAddress <String>] [-HostHeader <String>] [-Ssl] [-Force] ...

For clarity I removed parameters inserted by PowerShell. This cmdlet defines all parameters that we need to create binding on some site: site name, port, ipaddress, host header and ssl switch, that tells us that we have to build binding for ssl. Internal code then compiles another command:

new-itemproperty IIS:\sites\<site_name> -name Bindings -value @{protocol="http";bindingInformation="<IPAddress>:<Port>:<Host_Header>"}

Here is the source code for ProcessRecord method of the cmdlet, it uses couple of utility functions to format error message and to invoke resulting script. I assume that you are familiar with details of PowerShell SDK and know how to write cmdlets. PowerShell v1.0 doesn't show errors happened in internally called script, therefore I have to check $error variable and if there is an error, print it in my utility function. In v2.0 that was already fixed.

...

protected override void ProcessRecord()
{
     StringBuilder cmdLine = new StringBuilder("new-itemproperty ");
     string protocol = "http";
     if (sslBinding.IsPresent)
     {
         protocol = "https";
     }
     cmdLine.Append("\"IIS:\\sites\\" + siteName + "\" ");
     cmdLine.Append(" -name Bindings -value @{protocol=\"");
     cmdLine.Append(protocol);
     cmdLine.Append("\";bindingInformation=\"");
     if (!ipAddress.Equals("*"))
     {
         IPAddress test = IPAddress.Any;
         if (!IPAddress.TryParse(ipAddress, out test))
         {
             throw new ArgumentException(

Utility.FormatResourceString(

                    "InvalidIPAddress", ipAddress));
         }
     }
     cmdLine.Append(ipAddress);
     if (sitePort == 0xFFFFFFFF)
     {
         sitePort = (uint)(sslBinding.IsPresent ? 443 : 80);
     }
     cmdLine.Append(":" + sitePort.ToString() + ":");
     if (!String.IsNullOrEmpty(hostHeader))
     {
         cmdLine.Append(hostHeader);
     }
     else if (!sslBinding.IsPresent)
     {
         cmdLine.Append(siteName);
     }
     cmdLine.Append("\"}");
     if (Force.IsPresent)
     {
         cmdLine.Append(" -force");
     }
     Utility.InvokeScriptShowError(this,

cmdLine.ToString());
}

...

That's all you need to make it work. It is a simple command, most of source code is required to declare and describe parameters, I spent half an hour to write it, and as a result user could avoid typing expression for PowerShell hastable @{...}, so unpopular in PowerShell MVP circles and could omit some parameters altogether.

In my next post I will show you some less trivial queries that could produce more exciting results.

Sergei Antonov