Blog:\>_

Simple way of extending PowerShell objects with custom methods

2008-09-08T07:45:00Z

As you may know, IIS configuration is extensible. You could add new section, extend existing one by adding new schema file into folder containing schemas. All this was described in full details in the article of Tobin Titus. When we provide methods on configuration elements with COM extension, the only way to call it using configuration APIs is through creation of method instance, then creation of input parameters element on this instance, etc -- quite convoluted way. In PowerShell we expose it in more convenient way, like intrinsic methods on the object. User is able to call these methods exactly the same way as any other intrinsic methods of given object. Let's see how runtime methods work on site element:

>$site = get-webconfiguration '/system.applicationHost/sites/site[@name="mysite"]'

>$site.Stop()

>$site.State

Stopped

>$site.Start()

>$site.State

Started

Methods that are coming from configuration extension could be called directly. Properties from extension are updated dynamically, like property State on web site object. In this post I will explain how it is done.

PowerShell SDK provides number of ways to add new functionality to any object. You could add note property, script property or code property. You also could add script and code methods. When I started my implementation, my first attempt was to expose extended methods as PSCodeMethod, but this requires code reference to real code that will be executed when my exposed method is called. That was a problem. This real code has to be generated dynamically. It is simple enough code that will take input parameters and do all required actions to call configuration API. It could be implemented using type DynamicMethod, but it has to be done through emitting code into buffer, and this is quite tricky even for simple code. After spending couple of days with code generators and managed assembly language reference I started looking for alternative.

PowerShell PSCodeMethod inherits from PSMethodInfo type. PSMethodInfo is an abstract class that PowerShell uses to work with extended methods: it has name, description and Invoke method. You could inherit your type from PSMethodInfo and it will be used exactly the same way as regular code method. Problem is that property Name is not virtual and there is no way to set it from inherited class. Fortunately, you could do it through reflection. After I realized that, coding took just couple of hours. PSMethodInfo is public class, therefore it has stay the same in future, and property Name shouldn't go away. Using reflection here is OK -- it is a workaround for mistake in type design.

You will find implementation code at the end of this post. Two methods of CodeMethod class are specific to IIS 7 configuration: one is Invoke() -- that uses configuration APIs to call extension method, and another one is GetDefinition() that produces human readable signature for the methods using method definition from IIS configuration schema. You could use the same approach for any other type of method: defined in XML, or in WMI, or in ADSI, any time when you have programmatically accessible method definition and some generic way to invoke this method, for example passing its name and parameters. With direct implementation of extension method you don't need to bend your code to be compatible with PSCodeMethod -- you could access your native method directly.

Class CodeProperty is implemented very similarly, the only difference is that it inherits from PSPropertyInfo and declares itself as type PSPropertyInfo.CodeProperty. You also have to do the same dirty hack with name. In CodeProperty methods get() and set() call native implementation, because of this property value is refreshing at every access. Let's see how this will looks like in PowerShell.

$s = get-webconfiguration "//sites/site[@name='test']"

$s | gm Start

TypeName: Microsoft.IIs.PowerShell.Framework.ConfigurationElement

Name MemberType Definition
---- ---------- ----------
Start CodeMethod void Start()

$s.bindings.Collection[0] | gm AddSslCertificate | fl *

TypeName : Microsoft.IIs.PowerShell.Framework.ConfigurationElement
Name : AddSslCertificate
MemberType : CodeMethod
Definition : void AddSslCertificate(System.String certificateHash, System.String certificateStoreName)

Method AddSslCertificate() is an extension, defined on each binding element of the site, and it has the following schema:

<element name="bindings">
  <collection addElement="binding" clearElement="clear">

  ...
  <method name="AddSslCertificate" extension="Microsoft.ApplicationHost.RscaExtension">
     <inputElement>
        <attribute name="certificateHash" type="string" />
        <attribute name="certificateStoreName" type="string" defaultValue="MY" />
     </inputElement>
  </method>

...

How to use CodeMethod? Every time you have to return your object into PowerShell, you will convert it into PSObject, right? If you not doing this, PowerShell will do it for you, and it don't know that you have extended methods that has to be exposed in some specific way. So, you have to add those methods manually.

PSObject myObject = new PSObject()

myObject.Methods.Add(new CodeMethod("methodName", configurationMethod));

...send object to PowerShell

In my case I am adding CodeMethod created from extended configuration method instance and name of the method. In your case you could pass and store any other type that will be used to call native method implementation.

Enjoy,

Sergei Antonov

Here is CodeMethod implementation (provided as is without any support):

public class CodeMethod : PSMethodInfo
{
   private ConfigurationMethod configMethod;
   string definition;

   public CodeMethod(string name, ConfigurationMethod method)
   {
      FieldInfo nameField = this.GetType().GetField("name", 
          BindingFlags.NonPublic | BindingFlags.Instance);
      if (nameField != null)
      {
          nameField.SetValue(this, name);
      }
      configMethod = method;
      definition = GetDefinition(method);
   }

   public override PSMemberTypes MemberType
   {
      get {return PSMemberTypes.CodeMethod;}
   }

   public override Collection<string> OverloadDefinitions
   {
      get
      {
          Collection<string> returnValue = new Collection<string>();
          returnValue.Add(this.definition);
          return returnValue;
      }
   }

   public override string ToString()
   {
      StringBuilder returnValue = new StringBuilder();
      foreach (string overload in OverloadDefinitions)
      {
         returnValue.Append(overload);
         returnValue.Append(", ");
      }
      returnValue.Remove(returnValue.Length - 2, 2);
      return returnValue.ToString();
   }

   public override string TypeNameOfValue
   {
      get { return typeof(CodeMethod).FullName;}
   }

    public override PSMemberInfo Copy()
   {
      return new CodeMethod(Name, configMethod);
   }

   // This code is specific to IIS 7 configuration,

   // and I put it here for illustration

   public override object Invoke(params object[] arguments)
   {
      if (arguments == null)
      {
          throw new ArgumentNullException("arguments");
      }
      ConfigurationMethodInstance mi = configMethod.CreateInstance();
      ConfigurationElementSchema input

         = configMethod.Schema.InputSchema;
      if (arguments.Length > 0)
      {
          if (input != null)
          {
              int parametersCount = 0;
              if (input.AttributeSchemas != null)
              {
                  parametersCount += input.AttributeSchemas.Count;
              }
              if (input.ChildElementSchemas != null)
              {
                  parametersCount += input.ChildElementSchemas.Count;
              }
              if (arguments.Length != parametersCount)
              {
                  throw new ArgumentException();
              }
              PSObject argObject = new PSObject();
              // We produced definition from attributes first, then 
              // from child elements.

              // We expect the same order on input.
              int index = 0;
              if (input.AttributeSchemas != null)
              {
                  foreach (ConfigurationAttributeSchema s

                     in input.AttributeSchemas)
                  {
                     argObject.Properties.Add(

                        new PSNoteProperty(s.Name,

                        arguments[index++]));
                  }
              }
              if (input.ChildElementSchemas != null)
              {
                  foreach (ConfigurationElementSchema s

                     in input.ChildElementSchemas)
                  {
                     argObject.Properties.Add(

                        new PSNoteProperty(s.Name,

                        arguments[index++]));
                  }
              }
              mi.Input.Update(argObject);
          }
      }
      try
      {
          mi.Execute();
      }
      catch (COMException ex)
      {
          if (ex.ErrorCode == unchecked((int)0x80070490))
          {
             // This happens when there is no binding

             // for FTP on the site.
          }
          else
          {
             throw;
          }
      }
      if (mi.Output != null)
      {
          if (configMethod.Schema

                 .OutputSchema.AttributeSchemas.Count == 1)
          {
              return mi.Output.Attributes[0].ToPSObject();
          }
          else
          {
              return mi.Output.ToPSObject(null);
          }
      }
      return null;
  }

  private static string GetDefinition(ConfigurationMethod method)
  {
      ConfigurationMethodSchema ms = method.Schema;
      ConfigurationElementSchema input = ms.InputSchema;
      ConfigurationElementSchema output = ms.OutputSchema;

       StringBuilder builder = new StringBuilder();
      if (output != null)
      {
          if (output.AttributeSchemas.Count == 1)
          {
              // Configuration returns any result as element.

              // We could produce more reasonable signature here
              ConfigurationAttributeSchema a

                 = output.AttributeSchemas[0];
              builder.Append(a.ClrType.Name);
          }
          else
          {
              builder.Append("object");
          }
      }
      else
      {
          builder.Append("void");
      }
      builder.Append(" ");
      builder.Append(ms.Name);
      builder.Append("(");
      if (input != null)
      {
          foreach (ConfigurationAttributeSchema a

             in input.AttributeSchemas)
          {
              builder.Append(a.ClrType);
              builder.Append(" ");
              builder.Append(a.Name);
              builder.Append(", ");
          }

           if (input.ChildElementSchemas != null)
          {
              foreach (ConfigurationElementSchema child

                 in input.ChildElementSchemas)
              {
                  builder.Append("object");
                  builder.Append(" ");
                  builder.Append(child.Name);
                  builder.Append(", ");
              }
          }
          builder.Remove(builder.Length - 2, 2);
       }
       builder.Append(")");
       return builder.ToString();
    }
}

How to change output format in PowerShell

2008-08-29T09:03:00Z

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

2008-08-28T07:18:00Z

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

IIS7 PowerShell support -- details of our design

2008-08-22T19:35:00Z

After IIS team released Technical Preview of our PowerShell provider and commands, we got a few rants and grumblings from our customers. Some people pointed to complexity of IIS PowerShell provider and command parameters. Other people denied the need of provider for IIS at all, telling that just a set of commandlets with simple parameters will be sufficient. I have to admit that we did a mistake shipping preview of provider without complete set of commands. This created an impression of incomprehensible complexity of our tool.

In reality we had the following plan in mind: build base functionality first -- namespace, provider and generic cmdlets for configuration data handling, then add on top of it number of helper commands to cover most common and most convoluted tasks and actions. In our second preview release we included several dozens of commands that don’t require deep understanding of IIS configuration and structure of provider namespace. All these commands were implemented as “C# coded scripts”, i.e. they take parameters from user and generate script lines utilizing base functionality. We have to do it as compiled cmdlets, because for PowerShell v1.0 it is the only way to get full service from shell: help, parameters description, etc. In PowerShell v 2.0 these cmdlets could be implemented through pure readable script.

For the beginning I would like to explain a bit of our reasoning behind design of our PowerShell provider and base level cmdlets.

1. From my early days in IIS team I always had a feeling that we need interactive command tool that would work like shell on top of IIS configuration. I believe IIS administrators will use this tool more like a shell than like a script processor. Therefore navigation and other aspects of namespace were considered important. When Jeffrey Snover showed us the very first prototype of PowerShell, I saw what I always wanted: interactive composable shell with navigation.

2. IIS configuration is rich and quite complicated. Let me illustrate it by numbers. On my development machine I could run the following command and find total number of configuration sections with schema (I will get back to details of these commands in my later posts):

$(get-webconfiguration “//*[is-section()=’true’]” MACHINE/WEBROOT/APPHOST).count

This will produce 102 in my case. It means we have at least 102 data structures to manage. Now let’s run another command, which will show how many sections have default collections:

$(get-webconfiguration "//*[is-section()='true']" MACHINE/WEBROOT/APPHOST | where {$_.Schema.CollectionSchema -ne $null}).count

That gives me 36. And finally, let’s take a look at the total number of collections on unique elements:

$names = @{}

$elements = get-webconfiguration //* MACHINE/WEBROOT/APPHOST | where {$_.Schema.CollectionSchema -ne $null}

foreach ($el in $elements) {$names[$el.ElementTagName] += 1}

$names.Count

I got 88 here. What these numbers tell us? Our tool have to handle many data collections, and most of them are nested either inside child elements of sections, or inside parent collections.

Both considerations lead to namespace that should support navigation, operations on objects of this namespace and on properties of those objects. PowerShell naturally supports this functionality through providers. Historically IIS had hierarchy of objects that roughly follows URL path. Up to IIS 6 it was directly supported by metabase, in IIS 7 we placed all URL “related” objects into nested collections of one giant structure, configuration section ‘system.applicationHost/sites’. For PowerShell namespace I decided to abstract from details of configuration storage implementation and return back to familiar hierarchy “server/site/application/virtual directory/web directory/etc”. User could navigate along this hierarchy, change properties of objects, execute commands for them, copy objects, and current path will be used in most commands by default. This hierarchy roughly relates to commit path, as it used in configuration APIs, i. e. to concrete configuration files.

Now, let’s consider why provider is important. Imagine that we want to have set of operations on configuration objects without navigation path. It would be like using file system provider from the root of the drive, you always have to type full path. Don’t like path at all? You still need to specify full set of parameters to address nested objects: applications inside of site element, virtual directories inside of application, etc. For example, command to set user name on virtual directory would be something like

Set-username –site mysite –application myapp –virtualdirectory myvdir –value dude

Set-property –site mysite –application myapp –virtualdirectory myvdir –name username –value dude

Instead of

Set-itemproperty iis:\sites\mysite\myapp\myvdir –name user –value dude

I don’t think that provider command is more complicated than any of first two commands. Use of provider has additional benefits: you have to deal with the same commands as in other namespaces, or in other parts of IIS namespace. Do you want to change setting on the application pool? Use the same command:

Set-itemproperty iis:\apppools\mypool –name autoStart –value false

All you need is to remember how path is constructed in our namespace. This will happen naturally when you use it and navigate along it. Don’t remember property names? Use the same command, as you would do for other providers:

Get-item iis:\apppools\mypool | get-member

Or, if you already navigated to this object and use standard command aliases,

Gi . | gm

Sp . –n autostart –val true

In other words, if we want to use benefits of being one of PowerShell namespaces, we have to design namespace, path and provider. I tried to show you here, that we are not losing anything when we use set of standard commands instead of recreating them outside of namespace.

Web objects are important, but main bulk of configuration data is stored outside of them – in configuration sections. In my next post I will discuss how we use XPath queries to provide flexible and user extensible namespace.

Hello, everyone!

2008-08-22T19:32:00Z

Hi, I would like to introduce myself first.

My name is Sergei Antonov, I am a developer and I spent with IIS team more than 10 years in various capacities, working on administration and configuration tools for IIS. During these years I worked on design and implementation of various GUI tools, programming APIs and configuration storage. Currently I own scripting and command line tools. You could send me your questions, comments and complains regarding PowerShell support in IIS and about WMI provider.

In my next blog posts I will concentrate on use of PowerShell with IIS, my main goal here is to engage community to start using our PowerShell platform in order to write custom tools that will solve your administration problems. When needed, I will discuss configuration features, our new XPath engine, scripting and whatever else you and I will find interesting.

Sergei