IIS Configuration Files (2/2)

applicationHost.config Configuration Hierarchy

The iis.net: The Configuration System in IIS 7 ^[1] page has a good description of the configuration files hierarchy. We recommend you have a look at that page before continuing.

Impact of adding a website

To better understand how the configuration files works we will create a new website and see how this is reflected in the configuration files.

Before creating the website we took a copy of the %WinDir%\System32\inetsrv\config\applicationHost.config file so that we can diff it against the updated file and see what the differences are. Using the IIS Manager as explained in our other tutorial, we add a website called "TestSite1", store its contents in C:\inetpub\testsite1 and give it an unassigned port number (in our case 8030). After we create the site and start it we observe that the C:\inetpub\testsite1 is still empty, no files have been added by IIS to our content directory at this stage.

Let's now look at the changes made to applicationHost.config. Our new site has been added to the <system.applicationHost><sites> element. Here is the updated <system.applicationHost><sites> element with the change highlighted in red.

        <sites>
            <site name="Default Web Site" id="1" serverAutoStart="true">
                <application path="/">
                    <virtualDirectory path="/" physicalPath="%SystemDrive%\inetpub\wwwroot" />
                </application>
                <bindings>
                    <binding protocol="http" bindingInformation="*:80:" />
                    <binding protocol="net.tcp" bindingInformation="808:*" />
                    <binding protocol="net.pipe" bindingInformation="*" />
                    <binding protocol="net.msmq" bindingInformation="localhost" />
                    <binding protocol="msmq.formatname" bindingInformation="localhost" />
                </bindings>
            </site>
            <site name="TestSite1" id="2">
                <application path="/" applicationPool="TestSite1">
                    <virtualDirectory path="/" physicalPath="C:\inetpub\testsite1" />
                </application>
                <bindings>
                    <binding protocol="http" bindingInformation="*:8030:" />
                </bindings>
            </site>
            <siteDefaults>
                <logFile logFormat="W3C" directory="%SystemDrive%\inetpub\logs\LogFiles" />
                <traceFailedRequestsLogging directory="%SystemDrive%\inetpub\logs\FailedReqLogFiles" />
            </siteDefaults>
            <applicationDefaults applicationPool="DefaultAppPool" />
            <virtualDirectoryDefaults allowSubDirConfig="true" />
        </sites>

The location we specified for the contents (C:\inetpub\testsite1) and the choice of bindings we made (port 8030) can be seen in the new site element.

In addition to that the new site has been assigned its own application pool named after the new site: TestSite1. Whether a new site gets its own application pool or use an existing one depends not only on the choice made at creation time but also on the application pool settings. The TechNet: Create an Application Pool (IIS 7) ^[2] page hints that "By default, IIS adds an application pool that runs in integrated mode and uses .NET Framework version 2.0" so it seems that IIS may create a new pool to make sure that is the case.

If a new application pool is created then the <system.applicationHost><applicationPools> will also have been updated to include the new pool. This is the case in our example and the changes are highlighted in red below.

        <applicationPools>
            <add name="DefaultAppPool" managedRuntimeVersion="v4.0" />
            <add name="ASP.NET v4.0" managedRuntimeVersion="v4.0" />
            <add name="ASP.NET v4.0 Classic" managedRuntimeVersion="v4.0" managedPipelineMode="Classic" />
            <add name="TestSite1" />
            <applicationPoolDefaults>
                <processModel identityType="ApplicationPoolIdentity" loadUserProfile="true" setProfileEnvironment="false" />
            </applicationPoolDefaults>
        </applicationPools>

The example above gives you an idea of how the configuration files can be edited manually to add a site. Our IIS Automation tutorial shows how this can be done using the APIs.

Overriding the default settings

Our newly added site is currently using the default settings. Let's see what happens when we override some of these settings. We'll use something very simple: the default document. In the default settings there is a list of several file names that will be tried to find a default document. Let's remove one of them, for instance Default.htm.

If we look at the contents of the C:\inetpub\testsite1 folder after doing this change we see that there is now a new file called web.config in there. This contains the settings that are specific to the TestSite1 site and overrides some of the default values found in applicationHost.config.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <defaultDocument>
            <files>
                <remove value="Default.htm" />
            </files>
        </defaultDocument>
    </system.webServer>
</configuration>

You can see how a remove element has been added to instruct IIS to remove the Default.htm option from the list.

Our last test for this example will show what happens when the configuration settings for one directory in the site are changed from their defaults. We add a directory called Dir1 to our TestSite1 site. As we did before we remove one option from the default document list but just for this directory. To do so we select the Dir1 directory in the IIS Manager, click on the Default Document icon and remove one of the choices, for instance Default.asp.

The result of this is that in the same way as a web.config file was created in C:\inetpub\testsite1 when we overrode the defaults for the entire site, a web.config has now been created in C:\inetpub\testsite1\Dir1 and its contents are shown below.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <defaultDocument>
            <files>
                <remove value="Default.asp" />
            </files>
        </defaultDocument>
    </system.webServer>
</configuration>

The testsite1\Dir1\web.config only removes one choice but because it is applied to testsite1\web.config (which is itself applied to applicationHost.config) two choices will in fact be removed: Default.asp and Default.htm.

Hopefully it is now clear how the applicationHost.config and the nested web.config are used to customize the entire server, a specific website or a single directory.

References

1. iis.net: The Configuration System in IIS 7
2. TechNet: Create an Application Pool (IIS 7)