CarlosAg Blog : Microsoft.Web.Administration

IIS 7.0 Site ID Computation

CarlosAg — Fri, 13 Jun 2008 10:00:00 GMT

In my previous post I mentioned that IIS Manager (more specifically Microsoft.Web.Administration) has two algorithms for assigning a Site ID when no ID is specified.

The two algorithms are:

Incremental Site ID. When this algorithm is configured we will assign the first consecutive number available, for example, if you have Site ID's 1,2,3,5,6,8 the next time you add a Site in the UI (or using ServerManager.Sites.Add friendly overloads), you will get Site ID = 4, next will be 7, and next will be 9. The side effect of this is that you will get different Site ID's depending on the sites that are available which might complicate things in certain scenarios when provisioning the same site in multiple machines. The good news is that in IIS 7.0 the Side ID is not so important in terms of the configuration system since now all the configuration is stored using the Site Name instead. (Exceptions apply, for example when using the Metabase compatibility (customMetadata) or when you are using things like Session State in ASP.NET)
Site Name Hash. In this case we will calculate a Hash of the Site Name and use that number for the Site ID. This will end up using some funky numbers that will be impossible to remember but that "can work" in different machines. Technically we use the .NET implementation of "String.GetHashCode()" which you can read the remarks "The behavior of GetHashCode is dependent on its implementation, which might change from one version of the common language runtime to another. A reason why this might happen is to improve the performance of GetHashCode."

In either case we will ensure that whatever ID we generate it will not collide with any existing Site.

These algorithms are configured using the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetMgr\Parameters

In there you will find a DWORD attribute called IncrementalSiteIDCreation when set to 1 we will use the Incremental algorithm (1), otherwise we will use the Site name hash.

Bottom line if you really care about the Site ID and are provisioning the sites using Microsoft.Web.Administration you are better off having your own deterministsic algorithm for assigning the Site ID yourself and it will actually be considerably faster.

If you are using the UI chances are you really don't care about the Site ID, cause you would never have to interact with it (again might need changes when using certain ASP.NET features).

Faster IIS Web Sites Provisioning using Microsoft Web Administration

CarlosAg — Thu, 12 Jun 2008 13:01:00 GMT

Yesterday I got an email about some performance numbers that one of our customers were running into when creating remotely Web Sites, Applications, Application Pools and other tasks in IIS using Microsoft.Web.Administration. In case you don't know Microsoft.Web.Administration is a .NET library that exposes the IIS Configuration System.

The code was using Microsoft.Web.Administration from PowerShell to create a single Application Pool, a new Web Site, and finally assign the Root Application to the new Application Pool, and it was measuring each of the tasks. The application then was called continually till 10,000 sites were created. They then created a very nice Excel Spreadsheet that had a chart with how long it took when performing each operation that clearly show how fast (or slow) things were depending on the existing number of sites in IIS.

Funny enough the code was doing almost exactly what we use to measure in IIS 7.0 performance while provisioning. And that we ran into very similar numbers back a couple of years ago but we probably never share them. The results back in the day were showing a trend like the one below, where the Creation of the AppPool was quite fast (less than 400ms once you had 10,000 sites), the Application Pool assignment was taking almost 10 times more (almost 4 seconds) and the creation of the Sites was taking almost 20 times more (up to 8 seconds).

Our test code looked something like this (removing all the Timing code):

using(ServerManager m = new ServerManager()) {
    ApplicationPool pool = m.ApplicationPools.Add("MyPool");

    Site site = m.Sites.Add("MySite", ... "d:\inetpub\wwwroot");
    site.Applications["/"].AppPoolName = "MyPool";

    m.CommitChanges();
}

Back in those days (2005) the numbers were even worst, you would have to wait literally minutes to get a site created but we profiled it and understood exactly what the performance behavior was and we made it better.

Here is how to make it faster

Most importantly batch as many changes you need to do to our configuration system so that you only CommitChanges once, for example, creating the 10,000 sites and only Committing once will probably average 1,000 sites per second. More importantly you will reduce the load on the server since every time the configuration is changed our server has to process its changes and that incurs in other CPU cycles in WAS and W3SVC.
The reason we noticed Application Pools was being slower at the beginning when using ServerManager locally was just an artifact of the fact that it’s the first operation being done in our Test Script. The reason is that when you create a ServerManager in reality nothing interesting happens other than we activate a COM object that parses the schema, however whenever you request a section that is when the real XML parsing of files happens. This means that the first operation (in this case accessing the AppPool collection) pays the price of parsing machine.config, root web.config and ApplicationHost.config, which is the file that grows considerably as new sites/pools are added.
Definitely using ServerManager remotely (OpenRemote) will be several times slower because every time property is set or anything is changed the code actually hits the network to set the values in the remote objects, since on the client there are only client proxies. This means that setting appPool.Name actually goes through the network to set the values on the dllhost.exe hosting DCOM.
Finally the most important one, the reason the Site creation is extremely slow is because the way our test code was creating the site and the application, in particular we are using the method m.Sites.Add() which has several overloads, where most of them provide a set of "friendly-non-performant” combinations. This is due to the fact that none of them receives a Site ID which forces us to automatically calculate one every time a Site will be added. We have implemented two algorithms for this (depending on a registry key called IncrementalSiteIDCreation) and both have the issue that we need to read all the sites first to make sure we don’t generate an ID that is already in use. This means that if you have 4,000 sites we have to read all 4,000 sites and that of course over the network translates to literally thousands of round trips.
So bottom line use the m.Sites.CreateElement() followed by a m.Sites.Add(newSite) which will not create an ID for the Site that will not incur in the costs mentioned. Something like the snippet below. Notice that there is a little bit more code since you also need to create the Root Application and set the bindings, but this will proof useful since setting the AppPoolName requires the App anyway and you save all the Lookups on the Sites list as well.

using(ServerManager m = new ServerManager()) {
    ApplicationPool pool = m.ApplicationPools.Add("MyPool");

    Site site = m.Sites.CreateElement("site");
    site.Name = "MySite"
    site.ID = "MySite".GetHashCode();

    Application app = site.Applications.Add("/", "d:\inetp...");
    app.AppPoolName = "MyPool";

    m.CommitChanges();
}

After all that story, what is important to realize is that there are ways to make this way faster and that you should use them if you are going to do any sort of massive creation of sites. With the two changes outlined above (Specify the Site ID yourself and don't lookup the Site again to get the App) the results were incredible we were back to under 350ms for all the tasks.

How to register a new Section Definition using Microsoft.Web.Administration

CarlosAg — Tue, 15 Apr 2008 15:10:00 GMT

Today I was asked how can someone would be able to add a new section definition using Microsoft.Web.Administration, so I thought I would post something quickly here just to show how this could be achieved.

using System;
using Microsoft.Web.Administration;

class Program {
    static void Main(string[] args) {
        using (ServerManager m = new ServerManager()) {
            Configuration config = m.GetApplicationHostConfiguration();

            SectionDefinition definition =
                RegisterSectionDefinition(config, "system.webServer/mySubgroup/mySection");
            definition.OverrideModeDefault = "Allow";

            m.CommitChanges();
        }
    }

    public static SectionDefinition RegisterSectionDefinition(Configuration config, string sectionPath) {
        string[] paths = sectionPath.Split('/');

        SectionGroup group = config.RootSectionGroup;
        for (int i = 0; i < paths.Length - 1; i++) {
            SectionGroup newGroup = group.SectionGroups[paths[i]];
            if (newGroup == null) {
                newGroup = group.SectionGroups.Add(paths[i]);
            }
            group = newGroup;
        }

        SectionDefinition section = group.Sections[paths[paths.Length - 1]];
        if (section == null) {
            section = group.Sections.Add(paths[paths.Length - 1]);
        }

        return section;
    }
}

The idea is that you can grab a Configuration object they usual way, it could be ApplicationHost.config or any web.config, and then you call the method RegisterSectionDefinition which will ensure the whole hierarchy is added (in the case of multiple nested Section Groups) and then it will return the newly added Section Definition that you can then use to change any of their properties.

A very similar functionality is exposed for scripts and native code in the AHADMIN COM library exposing the RootSectionGroup as well from any IAppHostConfigFile that you can manipulate in the same way.

Hope this helps,

Search your configuration sections in web.config files using IIS 7.0 API's

CarlosAg — Wed, 19 Mar 2008 03:05:00 GMT

Background

In IIS 7.0 we have the great functionality to allow you to configure the Web Server settings in a distributed way, including the IIS configuration along with the ASP.NET configuration in the web.config files by using Configuration Sections. For example, the following shows a web.config adding a default document (home.aspx) to a Web Application inside my Default Web Site:

Now, that is great but it does come with a price, specially for server administrators it means that now you need to deal with a distributed configuration environment where certain settings are applied at the server level and certain settings are applied along with the application or even folders.

Another interesting challenge is that given the nature of distributed configuration, we've added the functionality to lock certain configuration sections so that they can only be set by a server administrator. Again this is good, however before the server administrator locks any section in order to prevent breaking applications they should search configuration and see if anyone is using that configuration section underneath.

Searching Configuration

The IIS 7.0 configuration system has a not so well-known feature that allows you to "query" the configuration system to get an overview of the configuration files in the system as well as the configuration sections that are used in each of them. This feature is implemented as a magical section called configPaths, that has the following schema:

How to use it

One thing that is pretty cool is that you can consume this section from all of our tools, including a command line (AppCmd.exe), a script (such as vbscript or javascript using Microsoft.ApplicationHost.AdminManager), or using Managed Code (Microsoft.Web.Administration) including the ability to use it under PowerShell. For this exercise we will only use Microsoft.Web.Administration, but the concepts are exactly the same in the other tools.

In its simplest form you can use the following function to display all the configuration files in your server as well as the sections included on them (just add a reference to Windows\System32\Inetsrv\Microsoft.Web.Administration.dll):

    /// <summary>
    /// Displays the list of configuration files as well as the
    ///     sections being used in each file
    /// </summary>
    private static void DisplaySections() {
        using (ServerManager serverManager = new ServerManager()) {
            Configuration appHost = serverManager.GetApplicationHostConfiguration();
            ConfigurationSection configPaths = appHost.GetSection("configPaths");

            foreach (ConfigurationElement configPath in configPaths.GetCollection()) {
                string path = (string)configPath["path"];
                string locationPath = (string)configPath["locationPath"];

                Console.WriteLine();

                Console.WriteLine("Config Path:" + path);
                if (!String.IsNullOrEmpty(locationPath)) {
                    Console.WriteLine(" <locationPath path=" + locationPath + "'>");
                }

                foreach (ConfigurationElement section in configPath.GetCollection()) {
                    Console.WriteLine("    " + section["name"]);
                }
            }
        }
    }

An example result of running this is:

Config Path:MACHINE/WEBROOT/APPHOST
    system.applicationHost/applicationPools
    system.webServer/defaultDocument
    system.webServer/ImageCopyright
    system.applicationHost/sites
    system.webServer/security/authentication/windowsAuthentication
    system.webServer/tracing/traceProviderDefinitions
    ...

Config Path:MACHINE/WEBROOT/APPHOST
  <locationPath="Default Web Site/BlogApp">
    system.webServer/security/authentication/windowsAuthentication

Config Path:MACHINE/WEBROOT/APPHOST
  <locationPath path="Default Web Site/aspnet_client">
    system.webServer/directoryBrowse
    system.webServer/handlers

Config Path:MACHINE/WEBROOT/APPHOST
  <locationPath path="Site2/aspnet_client">
    system.webServer/directoryBrowser
    system.webServer/handlers
    system.webServer/defaultDocument

Config Path:MACHINE/WEBROOT/APPHOST
  <locationPath path="Default Web Site">
    system.webServer/security/authentication/anonymousAuthentication
    system.webServer/directoryBrowse
    system.webServer/security/authentication/windowsAuthentication

Config Path:MACHINE/WEBROOT/APPHOST/Default Web Site
    appSettings
...

This tells us that in ApplicationHost.config we have a lot of sections begin used including applicationPools and many more.

Now, lets focus on the last two set of entries, the one with "MACHINE/WEBROOT/APPHOST" with locationPath set to "Default Web Site" tells us that anonymousAuthentication was used as well as windowAuthentication. The locationPath basically tells the configuration that even though this is set in ApplicationHost.config this configuration should only be applied to Default Web Site and its children. The next entry with path "MACHINE/WEBROOT/APPHOST/Default Web Site", basiclally tells you that in the Web.config inside the Default Web Site (in other words in c:\inetpub\wwwroot\web.config) the section appSettings is being used.

Now, what is interesting is that this is walking the entire server to find configuration files and do a lot of processing, however if you already know that you only want to search within a Site, or a particular application, then you can scope it down by using the GetWebConfiguration() method instead and this will give you only the configuration sections that apply for that site or application. Note that this will also report the sections that are specifically set for that object inside ApplicationHost.config making it much more than just a "findstr" inside the site folder and their virtual directories.

    DisplaySectionsForSite("Default Web Site");

    private static void DisplaySectionsForSite(string siteName) {
        using (ServerManager serverManager = new ServerManager()) {
            Configuration appHost = serverManager.GetWebConfiguration(siteName);
            ConfigurationSection configPaths = appHost.GetSection("configPaths");

            foreach (ConfigurationElement configPath in configPaths.GetCollection()) {
                string path = (string)configPath["path"];
                string locationPath = (string)configPath["locationPath"];

                Console.WriteLine();

                Console.WriteLine("Config Path:" + path);
                if (!String.IsNullOrEmpty(locationPath)) {
                    Console.WriteLine(" <locationPath path=" + locationPath + "'>");
                }

                foreach (ConfigurationElement section in configPath.GetCollection()) {
                    Console.WriteLine("    " + section["name"]);
                }
            }
        }
    }

PowerShell

Now, lets look at other examples, lets consider that we are a server administrator and I want to lock the defaultDocument section, but as a good citizen I first want to see if I would be breaking any application in my entire server if I do this. Just for fun lets do this using PowerShell instead, to test this just copy the entire code below and paste in inside an elevated PowerShell window.

$sectionToLookFor = "*defaultdocument*"

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.Web.Administration")
$iis = new-object Microsoft.Web.Administration.ServerManager

$configPaths = $iis.GetApplicationHostConfiguration().GetSection("configPaths").GetCollection()

foreach($path in $configPaths.GetCollection()) {
foreach($section in $path.GetCollection()) {
    if ($section.GetAttributeValue("name") -like $sectionToLookFor) {
      write ($path.GetAttributeValue("path") + " LocationPath:" + $path.GetAttributeValue("locationPath"))
      write ("    " + $section.GetAttributeValue("name"))
    }
}
}

The result in my machine gives you something like follows:

MACHINE/WEBROOT/APPHOST
    system.webServer/defaultDocument
MACHINE/WEBROOT/APPHOST/Default Web Site/aspnet_client
    system.webServer/defaultDocument
MACHINE/WEBROOT/APPHOST/Site2/aspnet_client
    system.webServer/defaultDocument

This tells us that inside the c:\inetpub\wwwroot\aspnet_client\web.config file we are actually using that section so if we end up locking this in the server we would break that application.

Summary

The configPaths section is a very useful section that allows you to search configuration files and the configuration sections being used in each of them, making it an invaluable tool for scenarios like understanding the configuration usage as well as locking and many others.

Using Microsoft.Web.Administration in Windows PowerShell

CarlosAg — Mon, 11 Feb 2008 03:53:00 GMT

A couple of months ago I wrote about using LINQ with Microsoft.Web.Administration to manage and query IIS 7.0 configuration. Somebody came back to me and said that LINQ was very cool but that it was very much Developer oriented and that in a production server without VS or .NET 3.5 it wouldn't be an option. Indeed that is a very valid comment and so I decided to show similar stuff with a tool that is available in Windows and its more IT oriented, Windows PowerShell.

So in this blog I will quickly mention some of the things you can easily do with Microsoft.Web.Administration inside Windows PowerShell.

To start working with Microsoft.Web.Administration the first thing you need to do is load the assembly so that you can start using it. It is quite easy using the methods from the Assembly type.

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.Web.Administration")

Once you have the assembly available then you will need to create an instance of our ServerManager class that gives you access to the entire configuration system.

$iis = new-object Microsoft.Web.Administration.ServerManager

The above line basically declares a variable called $iis that we will be able to use for all of our configuration tasks.

Now to more interesting stuff.

Getting the list of Sites

Getting the list of sites is as easy as just accessing the Sites collection, this will output all the information about sites

PS C:\ > $iis = new-object Microsoft.Web.Administration.ServerManager
PS C:\ > $iis.sites
ApplicationDefaults : Microsoft.Web.Administration.ApplicationDefaults
Applications : {DefaultAppPool, DefaultAppPool, DefaultAppPool, DefaultAppPool...}
Bindings : {}
Id : 1
Limits : Microsoft.Web.Administration.SiteLimits
LogFile : Microsoft.Web.Administration.SiteLogFile
Name : Default Web Site
ServerAutoStart : True
State : Started

However, we can also specify the information we care and the format we want to use, for example:

PS C:\ > $iis = new-object Microsoft.Web.Administration.ServerManager
PS C:\ > $iis.sites | select-object Id, Name, State
Id Name State
-- ---- -----
1 Default Web Site Started
2 Site2 Started
3 Site3 Started

You can also use the where-object command to filter objects to get only the sites that are Stopped, and then we want to Start them.

PS C:\ > $iis = new-object Microsoft.Web.Administration.ServerManager
PS C:\ > $iis.sites | where-object {$_.State -eq "Stopped"} | foreach-object { $_.Start() }

OK, now let's imagine I want to find all the applications that are configured to run in the Default ApplicationPool and move them to run in my NewAppPool. This is better to do it in three lines:

PS C:\ > $iis = new-object Microsoft.Web.Administration.ServerManager
PS C:\ > $iis.sites | foreach {
$_.Applications | where { $_.ApplicationPoolName -eq 'DefaultAppPool' } |
foreach { $_.ApplicationPoolName = 'NewAppPool' }
}
PS C:\ > $iis.CommitChanges()

Now let's say I want to find the top 20 distinct URL's of all the requests running in all my worker processes that has taken more than 1 second.

PS C:\ > $iis = new-object Microsoft.Web.Administration.ServerManager
PS C:\ > $iis.WorkerProcesses | foreach {
$_.GetRequests(1000) | sort TimeElapsed -descending |
select-object Url -unique -first 20 }

OK, finally let's say I want to display a table of all the applications running under DefaultAppPool and display if Anonymous authentication is enabled or not. (Now this one is almost on the edge of "you should do it differently, but it is Ok if you are only reading a single value from the section):

PS C:\ > $iis = new-object Microsoft.Web.Administration.ServerManager
PS C:\ > $iis.Sites | foreach {
$_.Applications | where { $_.ApplicationPoolName -eq 'DefaultAppPool' } |
select-object Path,@{Name="AnonymousEnabled"; Expression = {
$_.GetWebConfiguration().GetSection("system.webServer/security/authentication/anonymousAuthentication").GetAttributeValue("enabled")
}}
}

Again, the interesting thing is that now you can access all the functionality from M.W.A. from Windows PowerShell very easily without the need of compiling code or anything else. It does take some time to get used to the syntax, but once you do it you can do very fancy stuff.

Using LINQ with Microsoft.Web.Administration

CarlosAg — Thu, 25 Oct 2007 02:32:00 GMT

With the upcoming release of .NET 3.5 and LINQ I thought it would be interesting to show some of the cool things you can do with IIS 7 and LINQ. Everything that I will do can be done with C# 2.0 code but it would take me several lines of code to write them but thanks to LINQ you can do them in about a line or two.

Let's start with a very basic example that does not use LINQ but just M.W.A (Microsoft.Web.Administration) and then start adding interesting things to it.

The following code just iterates the sites in IIS and displays their name.

using System;
using System.Linq;
using Microsoft.Web.Administration;
class Program {
    static void Main(string[] args) {
        using (ServerManager serverManager = new ServerManager()) {

            var sites = serverManager.Sites;
            foreach (Site site in sites) {
                Console.WriteLine(site.Name);
            }
        }
    }
}

Now, let's say I wanted to have them sorted by their name. This is where LINQ starts being useful

    using (ServerManager serverManager = new ServerManager()) {

        var sites = (from site in serverManager.Sites
            orderby site.Name
            select site);

        foreach (Site site in sites) {
            Console.WriteLine(site.Name);
        }
    }

Say you want to start all the sites that are stopped:

    using (ServerManager serverManager = new ServerManager()) {

        var sites = (from site in serverManager.Sites
            where site.State == ObjectState.Stopped
            orderby site.Name
            select site);

        foreach (Site site in sites) {
            site.Start();
        }
    }

OK, now let's imagine I want to find all the applications that are configured to run in the Default ApplicationPool and move them to run in my NewAppPool. This would take me a lot more lines of code but now I can just do:

    using (ServerManager serverManager = new ServerManager()) {

        var apps = (from site in serverManager.Sites
            from app in site.Applications
            where app.ApplicationPoolName.Equals("DefaultAppPool", StringComparison.OrdinalIgnoreCase)
            select app);

        foreach (Application app in apps) {
            app.ApplicationPoolName = "NewAppPool";
        }

        serverManager.CommitChanges();
    }

Now let's say I want to find the top 20 distinct URL's of all the requests running in all my worker processes that has taken more than 1 second.

    using (ServerManager serverManager = new ServerManager()) {

        var requests = (
            from wp in serverManager.WorkerProcesses
            from request in wp.GetRequests(1000)
            orderby request.TimeElapsed descending
            select request).Distinct().Take(20);

        foreach (Request request in requests) {
            Console.WriteLine(request.Url);
    }
}

    using (ServerManager serverManager = new ServerManager()) {

        var items = from site in serverManager.Sites
            from app in site.Applications
            where app.ApplicationPoolName.Equals("DefaultAppPool", StringComparison.OrdinalIgnoreCase)
            orderby site.Name, app.Path
            select new {
                Site = site,
                Application = app,
                AnoymousEnabled = ((bool)app.GetWebConfiguration().GetSection("system.webServer/security/authentication/anonymousAuthentication")["enabled"])
            };

        foreach (var item in items) {
            Console.WriteLine("Site:{0,-18} App:{1, -10} Anonymous Enabled:{2}",
                item.Site.Name, item.Application.Path, item.AnoymousEnabled);
        }
    }

As you can see LINQ is an incredibly useful feature in C# 3.0 and in conjunction with Microsoft.Web.Administration allows you to do incredibly complex operations in IIS with just few lines of code.

Using the IIS 7.0 Managed Configuration API

CarlosAg — Fri, 28 Sep 2007 23:31:00 GMT

More than a year ago I wrote about Microsoft.Web.Administration.dll and how it was a new API we were creating for managed code developers to be able to easily set any configuration settings of IIS, however I purposely ignored the configuration part of the API.

Later I talked about the way configuration was organized in IIS 7.0 and how configuration files inherited and worked.

Recently I was asked about some samples on how to modify IIS configuration and decided it was about time to talk about the configuration part of Microsoft.Web.Administration.

The first thing to really emphasize is that Microsoft.Web.Administration in a way has two different ways of reading configuration:

Run time: This is a read-only version of configuration that is meant to be used when running inside a worker process in IIS. It is exposed through a class called Microsoft.Web.Administration.WebConfigurationManager and its GetSection() method with several overloads. Since this blog is about changing configuration I will not be mentioning this API, but suffice to say, it works the same except you get a read-only section.
Design time: This API is our management story for modifying configuration from managed code, it is exposed through the class ServerManager and several of its methods listed below:

public sealed class ServerManager : IDisposable {

    // Note: some properties and methods were ignored since I'll focus on only these

    public void CommitChanges();

    public void Dispose();

    public Configuration GetAdministrationConfiguration();

    public Configuration GetApplicationHostConfiguration(...);

    public Configuration GetRedirectionConfiguration(...);

    public Configuration GetWebConfiguration(...);

    public static ServerManager OpenRemote(string serverName);
}

Whenever you work with the configuration system in IIS you need to:

Figure out which section you want to modify

The entire configuration in IIS is organized in sections inside configuration files. Sections are composed of elements, attributes, collections and potentially even methods. If you want to know what is the section you are looking you can search it in %windir%\System32\Inetsrv\Config\schema which is the folder where we place all the "schema" files that entirely describe the configuration in IIS.
Figure out for which object you want to manage

The configuration systemin IIS 7.0 is distributed and as such each child object inherits the configuration of its parent, so for example an application inherits the configuration of the site and the site inherits configuration from the server. So now you need to decide which objects you want to manage, for example, do you want to enable Windows Authentication for the entire server or do you only want to enable it for a particular site or application.
Determine in which place you want to make the change

As the previous bullet mentions the configuration system is distributed so now you can actually make the changes in different levels for the same object, for example you can modify applicationHost.config with a locationPath "Default Web Site" or you can obtain the same behavior by modifying a web.config file inside wwwroot directory. The concept that really impacts this decision is configuration locking since based on the settings that the server administrator has configured it might be invalid to set authentication in the web.config and might only be possible to set it in applicationHost.config.

OK, after all that talking lets go to the some actual examples and apply the 3 steps above.

All the code below assumes you have added a reference to Microsoft.Web.Administration.dll (located at %windir%\system32\inetsrv\) and that you are adding a "using Microsoft.Web.Administration;" at the top of your C# file.

Enable Directory Browsing for Default Web Site

Looking into system32\inetsrv\config\schema\IIS_Schema.xml you will find that the correct name of the section I'm looking for is system.webServer/directoryBrowse
I only want to modify Default Web Site
Since I now that IIS by default is not locked then I'll make the change directly in the web.config of the site so that when you XCopy my site to another server it remains working the same way.

Code:

    using (ServerManager manager = new ServerManager()) {

      Configuration webConfig = manager.GetWebConfiguration("Default Web Site");

      ConfigurationSection directoryBrowseSection =

      webConfig.GetSection("system.webServer/directoryBrowse");

      directoryBrowseSection.SetAttributeValue("enabled", true);

      manager.CommitChanges();

    }

The code uses ServerManager to get the web.config of the web site and then queries the directoryBrowse section and sets the attribute 'enabled' to true. If you open IIS_Schema.xml you will see that this section defines the 'enabled' attribute as a Boolean.

As you can see this API offers a loosely typed object model to ready and modify configuration, with the most important objects being Configuration, ConfigurationElement and ConfigurationAttribute.

Adding a Handler for the application MyApp underneath Default Web Site

Looking into system32\inetsrv\config\schema\IIS_Schema.xml you will find that the correct name of the section I'm looking for is system.webServer/handlers
I only want to modify Default Web Site/MyApp
In this example let's actually modify applicationHost.config.

Code:

    using (ServerManager manager = new ServerManager()) {

      Configuration webConfig = manager.GetApplicationHostConfiguration();

      ConfigurationSection handlersSection =
          webConfig.GetSection("system.webServer/handlers", "Default Web Site/MyApp");

      ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();

      ConfigurationElement handlerElement = handlersCollection.CreateElement();

      handlerElement.SetAttributeValue("name", "MyHandler");
      handlerElement.SetAttributeValue("path", "*.myhandler");
      handlerElement.SetAttributeValue("verb", "GET");
      handlerElement.SetAttributeValue("type", "CarlosAg.IIS.Samples.MyHandler");

      handlersCollection.Add(handlerElement);

      manager.CommitChanges();
    }

In this case the handlers Section has a default collection which is where we want to add our handler. For that we use the CreateElement() method to get a new element that we can set the attributes and then add it.

Removing our Handler

Same system.webServer/handlers
Same Default Web Site/MyApp
Same applicationHost.config.

Code:

    using (ServerManager manager = new ServerManager()) {

      Configuration webConfig = manager.GetApplicationHostConfiguration();

      ConfigurationSection handlersSection =
              webConfig.GetSection("system.webServer/handlers", "Default Web Site/MyApp");

      ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();

      foreach (ConfigurationElement handlerElement in handlersCollection) {

        if (String.Equals((string)handlerElement.GetAttributeValue("name"), "MyHandler", StringComparison.OrdinalIgnoreCase)) {
          handlersCollection.Remove(handlerElement);
          break;
        }
      }

      manager.CommitChanges();

    }

Unfortunately currently there is no way to search collections so your only option is to iterate through elements and find the match you are looking for, in this case I'm matching by the name and then removing it from the collection.

Hopefully that should give a good initial steps on how to start working with configuration using Microsoft.Web.Administration, there are several other options I'll be mentioning in other post on how to lock configuration, how to set metadata, how to enumerate configurations and how to do much more advanced stuff for the few developers that will actually need advanced control of IIS configuration.

Microsoft.Web.Administration in IIS 7

CarlosAg — Mon, 17 Apr 2006 08:56:00 GMT

While creating the new administration stack in IIS 7, we were looking into the different ways users could manipulate the server configuration as well as the new runtime information available in IIS 7 (Internally we call this RSCA-Runtime State and Control API) from managed code, and we realized we needed to provide a simpler and more straight forward API that developers could consume from managed code. Microsoft.Web.Administration is the answer to this problem. This API is designed to be simple to code against in an “intellisense-driven” sort of way. At the root level a class called ServerManager exposes all the functionality you will need.

To show the power and simplicity of this API, let’s look at some samples below. To try this samples just create a new Console Application in Visual Studio and add a reference to Microsoft.Web.Administration.dll that can be found at IIS directory (%WinDir%\System32\InetSrv).
Please note that the following code is based on Windows Vista Beta 2 code and will likely change for the release candidate versions of Windows Vista since we have planned several enhancements to simplify the API and expose more features into it.
The following picture shows the main objects (excluding Configuration related classes).

Creating a Site

ServerManager iisManager = new ServerManager();
iisManager.Sites.Add("NewSite", "http", "*:8080:", "d:\\MySite");
iisManager.Update();

This basically creates an instance of the ServerManager class and uses the Add method in the Sites collection to create a new site named "NewSite" listening at port 8080 using http protocol and content files are at d:\MySite.
One thing to note is that calling Update is a requirement since that is the moment when we persist the changes to the configuration store.
After running this code you have now a site that you can browse using http://localhost:8080

Adding an Application to a site

ServerManager iisManager = new ServerManager();
iisManager.Sites["NewSite"].Applications.Add("/Sales", "d:\\MyApp");
iisManager.Update();

This sample uses the Sites collection Indexer to get NewSite site and uses the Applications collection to add a new http://localhost:8080/Sales application.

Creating a Virtual Directory

ServerManager iisManager = new ServerManager();
Application app = iisManager.Sites["NewSite"].Applications["/Sales"];
app.VirtualDirectories.Add("/VDir", "d:\\MyVDir");
iisManager.Update();

Runtime State and Control

Now, moving on to the new Runtime state and control information we also expose in this objects information about their current state as well as the ability to modify them. For example, we expose the list of W3WP processes running (Worker processes) and what I think is really cool, we even expose the list of requests currently running. Stopping a Web Site

ServerManager iisManager = new ServerManager();
iisManager.Sites["NewSite"].Stop();

Recyciling an Application Pool

ServerManager iisManager = new ServerManager();
iisManager.ApplicationPools["DefaultAppPool"].Recycle();

Getting the list of executing requests

ServerManager iisManager = new ServerManager();
foreach(WorkerProcess w3wp in iisManager.WorkerProcesses) {
    Console.WriteLine("W3WP ({0})", w3wp.ProcessId);

    foreach (Request request in w3wp.GetRequests(0)) {
        Console.WriteLine("{0} - {1},{2},{3}",
                    request.Url,
                    request.ClientIPAddr,
                    request.TimeElapsed,
                    request.TimeInState);
    }
}

Another big thing on this API is the ability to edit the “.config” files using a simple API, this includes the ability of modifying the main applicationHost.config file from IIS, web.config files from asp.net as well as machine.config and other config files (such as administration.config). However I will talk about them in a future post.