September, 2007

Posts
  • CarlosAg Blog

    Using the IIS 7.0 Managed Configuration API

    • 3 Comments

    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:

    1. 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.
    2. 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:

    1. 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.

    2. 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.

    3. 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

    1. 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
    2. I only want to modify Default Web Site
    3. 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.

    <sectionSchema name="system.webServer/directoryBrowse">
      <attribute name="enabled" type="bool" defaultValue="false" />
      ...
    </sectionSchema>

    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

    1. 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
    2. I only want to modify Default Web Site/MyApp
    3. 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

    1. Same system.webServer/handlers
    2. Same Default Web Site/MyApp
    3. 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.

  • CarlosAg Blog

    Internet Information Services (IIS) 7.0 Manager for Windows XP, 2003 and Windows Vista SP1 RC0 is available for download

    • 6 Comments

    NOTE: RTM has been released see the following blog: http://blogs.msdn.com/carlosag/archive/2008/03/04/IISManagerForWindowsXPand2003andVista.aspx 

    With the release of Windows Server 2008 RC0, in IIS we are also releasing the ability to manage the Web Server, the new FTP Server and the new modules remotely using IIS Manager 7.0.

    In the past with previous Beta we shipped similar functionality under a different name, however for the first time this is the real way we will be supporting this remote administration from different Windows versions when Windows Server 2008 final version comes along.

    The reason this release in particular is exiting is because for the first time all the UI extensibility is enabled for these platforms making it possible to build your own UI modules, install them in the server and have the clients that connect to your server automatically download the new functionality and use it as it was part of the IIS Manager release.

    Another reason this is important for us is because this is the first time we are releasing support for x64 which is something required for customers using Windows Vista 64 bit edition or any other 64 bit version of Windows.

    You can download and install them from:

    x86

    http://www.iis.net/downloads/default.aspx?tabid=34&g=6&i=1524

    x64

    http://www.iis.net/downloads/default.aspx?tabid=34&i=1525&g=6

    Note: This RC0 version will not be able to connect to any other older build of Windows 2008 Server including Beta 3, so if you need to still manage Beta 3 version you will need to install the Beta 3 build of the tool which can safely live side-by-side with the RC0 build.

Page 1 of 1 (2 items)