How to add a default document with IIS7 web.config

IIS7 includes an all-new distributed configuration option, which allows for IIS7 configuration to be stored in web.config files, along with asp.net configuration, to be deployed with your content.  This makes transferring IIS7 configuration from your development box to your hosted server as easy as file copy!  Read more about this in the Delegating Configuration section of http://learn.IIS.net

In this post, I'll show how easy it is to add or change a default document for your Web site.  This method will work on any IIS7 web server, and it will be ignored on all non-IIS7 web servers, so it should be safe to do no matter the type of application or content. 

Scenario:  Let's say I want to add index.php as the default document for the new whiz-bang PHP application I just downloaded.  IIS doesn't recognize index.php as a default document, so how do I enable that?  It's as easy as:

1) create a web.config file in your application directory

2) edit it as follows:

<configuration>
   <system.webServer>
    <defaultDocument>
        <files>
            <add value="index.php" />
        </files>
    </defaultDocument>
   </system.webServer>
</configuration>

How does this work?  IIS7 monitors web directories for the web.config file, and will notice any time a file with this name is created or changed.  It reads the configuration in the file and merges it with any parent or global configuration set at higher levels (at a site or server level).  In this case, we're telling IIS to add the "index.php" value to the list of default documents.  You can also remove an individual entry in the defaultDocument list by doing this:

        
<files>             
    <remove value="index.php" />         
</files>

Or you can clear all of the inherited values in the defaultDocument list first by doing this:

<files>    
    <clear/>    
    <add value="index.php" />
</files>

IIS7 distributed configuration is very powerful!  Read more on http://learn.iis.net.