PowerShell Snap-in: Advanced Configuration Tasks

by Thomas Deml

In this walkthrough you will learn how to accomplish some advanced configuration tasks using XPath queries and wildcards.

Introduction

The previous walkthrough introduced you to the *-WebConfiguration and *-WebConfigurationProperty cmdlets. There is more to these cmdlets than meets the eye. The -filter parameter is not just a way to specify a configuration section. It is an XPath query and in this walkthrough we'll explore how to take advantage of it. There are also some nice ways you can use wilcards with the *-WebConfiguration* commands.

This walkthrough uses the sites, applications and virtual directories created in previous examples.

Using XPath Queries

Here is a simple example that shows you how to use wilcards with the Get-WebConfigurationProperty cmdlet:

PS IIS:\Sites\DemoSite\DemoApp> Get-WebConfigurationProperty -filter //defaultDocument/files -name Collection[value="index*"] | select value

And another one. Here all the handler mappings that will get executed by ASPNET_ISAPI.DLL:

PS IIS:\Sites\DemoSite\DemoApp> Get-WebConfigurationProperty -filter //handlers -name Collection[scriptProcessor="*aspnet_isapi.dll"]  | select name,path
name                                              path
----                                              ----
svc-ISAPI-2.0-64                                  *.svc
svc-ISAPI-2.0                                     *.svc
AXD-ISAPI-2.0                                     *.axd
PageHandlerFactory-ISAPI-2.0                      *.mspx
SimpleHandlerFactory-ISAPI-2.0                    *.ashx
WebServiceHandlerFactory-ISAPI-2.0                *.asmx
HttpRemotingHandlerFactory-rem-ISAPI-2.0          *.rem
HttpRemotingHandlerFactory-soap-ISAPI-2.0         *.soap
AXD-ISAPI-2.0-64                                  *.axd
PageHandlerFactory-ISAPI-2.0-64                   *.mspx
SimpleHandlerFactory-ISAPI-2.0-64                 *.ashx
WebServiceHandlerFactory-ISAPI-2.0-64             *.asmx
HttpRemotingHandlerFactory-rem-ISAPI-2.0-64       *.rem
HttpRemotingHandlerFactory-soap-ISAPI-2.0-64      *.soap

Let's suppose you don't like the .aspx extension for your ASP.Net files too much and you want to change all IIS handler mappings from *.aspx to *.mspx. Can it be shorter than this?

PS IIS:\Sites\DemoSite\DemoApp> set-webconfiguration "/system.webServer/handlers/add[@path='*.aspx']/@path" -value "*.mspx"

Let's look if the changes were set:

(get-webconfiguration //handlers).collection | select name,path

Now how about looking at the configuration file itself. We can use the get-item cmdlet that we explored in a previous walkthrough.

PS IIS:\Sites\DemoSite\DemoApp> get-content (((get-item .).physicalPath).ToString() + "\web.config")
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
         <handlers>
            <remove name="PageHandlerFactory-ISAPI-2.0-64" />
            <remove name="PageHandlerFactory-ISAPI-2.0" />
            <remove name="PageHandlerFactory-Integrated" />
            <add name="PageHandlerFactory-Integrated" path="*.mspx" verb="GET,HEAD,POST,DEBUG" type="System.Web.UI.PageHandlerFactory" preCondition="integratedMode" />
            <add name="PageHandlerFactory-ISAPI-2.0" path="*.mspx" verb="GET,HEAD,POST,DEBUG" modules="IsapiModule" scriptProcessor="%windir%\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv2.0,bitness32" responseBufferLimit="0" />
            <add name="PageHandlerFactory-ISAPI-2.0-64" path="*.mspx" verb="GET,HEAD,POST,DEBUG" modules="IsapiModule" scriptProcessor="%windir%\Microsoft.NET\Framework64\v2.0.50727\aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv2.0,bitness64" responseBufferLimit="0" />
        </handlers>
    </system.webServer>
</configuration>

You can see that the configuration system removed the old handlers and replaced them with new handlers that are now mapped to *.mspx.

Discovering IIS Configuration

It's great if you know what you want to configure. But what if you don't. Here are a few helpers.

Showing available IIS configuration sections

get-webconfiguration //* | where {$_.psbase.SectionPath -like "*" -and $_.psbase.SectionPath.length -gt 0} | select SectionPath

Showing the properties you can configure on a particular section:

get-webconfiguration system.webServer/caching | select -exp Attributes | select Name

Putting the two together, i.e. showing all sections with their properties.

get-webconfiguration //* | where {$_.psbase.SectionPath -like "*" -and $_.psbase.SectionPath.length -gt 0} | foreach {$_.SectionPath.ToUpper();get-webconfiguration $_.SectionPath | select -exp Attributes | select Name;"`n"} | more

We will probably pack these commands into some functions at a later Tech Preview but this is what you get for now :).

Summary

In this walkthrough you learned how to accomplish complex IIS configuration tasks by using wildcards and XPath queries. The next walkthrough will discuss how to discover state and run-time data.