web.config defaultDocument
The defaultDocument section of the web.config file can be used to set a custom default page (document) for your web site. You can also have a custom list of default documents for your website. If the first file listed does not exist, the web server will check the current directory for each file in the list.
The web.config can be used to change the default document (page) for an entire site, or on a directory by directory basis. The default page may be a .aspx, .asp, .htm, .html, .txt, or any other file type handled by the web server.
Why it's done
People typically type "foo.com" into their browsers, rather than "foo.com/index.aspx". When someone visits your website without specifying a page, the web server returns the default document. This also applies if someone visits a subdirectory on your site, such as foo.com/dir1/ or foo.com/dir2, but doesn't specify a page.
If there isn't a default document in the directory, the client will receive a "file not found" or "directory browsing denied" error. Web servers are typically configured to search for a list of default files. Depending on your configuration, the default document list in IIS 7.5 may include the files listed below.
- default.aspx
- default.asp
- default.htm
- index.asp
- index.aspx
- index.htm
- index.html
- index.php
Compatibility
The default document of web.config is compatible with IIS 7 (w2k8) and IIS 7.5 (w2k8 r2).
Web.config files are deeply integrated with IIS 7.x. While some web.config sections sometimes require that the containing directory is set as an application, this isn't one of them. A simple web.config with a defaultDocument section may be placed in any directory, and the directory does NOT need to be set as an application.
Example
Example default document list. Comments are enclosed in <!-- --> and are not required.
<!-- this line enables default documents for a directory -->
<defaultDocument enabled="true">
<files>
<!-- clear, removes the existing default document list -->
<clear/>
<!-- set foo.htm as the default document -->
<add value="foo.htm"/>
<!-- set foo.php as the 2nd default document -->
<add value="foo.php"/>
<!-- set foo.aspx as the 3rd default document -->
<add value="foo.aspx/>
</files>
</defaultDocument>
Using defaultDocument to change the default page
- Use a text editor to create a file named web.config
- Save the web.config file with the appropriate content
- Place the web.config file in the directory where you wish to change the default page
Detailed web.config examples
If there isn't an existing web.config in the directory, your new web.config should look something like this
<?xml version="1.0"?>
<configuration>
<system.webServer>
<!-- this line enables default documents for a directory -->
<defaultDocument enabled="true">
<files>
<!-- clear, removes the existing default document list -->
<clear/>
<!-- set foo.htm as the default document -->
<add value="foo.htm"/>
<!-- set foo.php as the 2nd default document -->
<add value="foo.php"/>
<!-- set foo.aspx as the 3rd default document -->
<add value="foo.aspx/>
</files>
</defaultDocument>
<modules runAllManagedModulesForAllRequests="true"/>
</system.webServer>
</configuration>
If there is an existing web config, without a <system.webServer> section... Your new web.config should look like this
<?xml version="1.0"?>
<configuration>
<system.web>
<!-- .. existing text .. -->
<!-- .. existing text .. -->
</system.web>
<system.webServer>
<!-- this line enables default documents for a directory -->
<defaultDocument enabled="true">
<files>
<!-- clear, removes the existing default document list -->
<clear/>
<!-- set foo.htm as the default document -->
<add value="foo.htm"/>
<!-- set foo.php as the 2nd default document -->
<add value="foo.php"/>
<!-- set foo.aspx as the 3rd default document -->
<add value="foo.aspx/>
</files>
</defaultDocument>
<modules runAllManagedModulesForAllRequests="true"/>
</system.webServer>
</configuration>
If your existing web.config already has a <system.webServer> section, just add the <defaultDocument> section
<?xml version="1.0"?>
<configuration>
<system.web>
<!-- .. existing text .. -->
<!-- .. existing text .. -->
</system.web>
<system.webServer>
<!-- .. existing text .. -->
<!-- this line enables default documents for a directory -->
<defaultDocument enabled="true">
<files>
<!-- clear, removes the existing default document list -->
<clear/>
<!-- set foo.htm as the default document -->
<add value="foo.htm"/>
<!-- set foo.php as the 2nd default document -->
<add value="foo.php"/>
<!-- set foo.aspx as the 3rd default document -->
<add value="foo.aspx/>
</files>
</defaultDocument>
<!-- .. existing text .. -->
</system.webServer>
</configuration>