Default Document Files <files>

Article
04/06/2022

Overview

The <files> element of the <defaultDocument> collection specifies a list of file names that are configured as default documents. The <files> element can contain a list of <add> elements where each item in the list specifies a unique file to add to the <files> list.

Compatibility

Version	Notes
IIS 10.0	The `<files>` element was not modified in IIS 10.0.
IIS 8.5	The `<files>` element was not modified in IIS 8.5.
IIS 8.0	The `<files>` element was not modified in IIS 8.0.
IIS 7.5	The `<files>` element was not modified in IIS 7.5.
IIS 7.0	The `<files>` element of the `<defaultDocument>` collection was introduced in IIS 7.0.
IIS 6.0	The `<defaultDocument>` collection replaces the IIS 6.0 DefaultDoc property and the EnableDefaultDoc value of the DirBrowseFlags property on the IIsWebService metabase object.

Setup

The <files> element of the <defaultDocument> collection is included in the default installation of IIS 7.

How To

How to add a default document for an application or site

Open Internet Information Services (IIS) Manager:
- If you are using Windows Server 2012 or Windows Server 2012 R2:
  - On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows 8 or Windows 8.1:
  - Hold down the Windows key, press the letter X, and then click Control Panel.
  - Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
- If you are using Windows Server 2008 or Windows Server 2008 R2:
  - On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
- If you are using Windows Vista or Windows 7:
  - On the taskbar, click Start, and then click Control Panel.
  - Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
In the Connections pane, expand the server name, expand Sites, and then navigate to the Web site or application where you want to configure default documents.
In the Home pane, double-click Default Document.
In the Actions pane, click Add...
In the Add Default Document dialog box, type the name of the default document that you want to add in the Name box, and then click OK.
If necessary, in the Actions pane, select a default document in the list, and then click Move Up or Move Down to define the order in which IIS should search through the default document list.
In the Default Document alert box, click Yes to decline configuration inheritance from a parent configuration level, or click No or Cancel to cancel the change in default document order.
If necessary, click Remove in the Actions pane to remove any file names that you do not want to use as default documents.

Configuration

Attributes

None.

Child Elements

Element	Description
`add`	Optional element. Adds a file name to the collection of files.
`remove`	Optional element. Removes a reference to a file name from the files collection.
`clear`	Optional element. Removes all references to file names from the files collection.

Configuration Sample

The following configuration example, when included in a Web.config file for a site or application, enables default documents for the site or application. It then adds the file name "Home.html" to the list of the site's or application's default documents.

<configuration>
   <system.webServer>
      <defaultDocument enabled="true">
         <files>
            <add value="home.html" />
         </files>
      </defaultDocument>
   </system.webServer>
</configuration>

Sample Code

The following examples enable default documents on a Web site named Contoso then add a file named Home.html to the list of default documents for the site.

AppCmd.exe

appcmd.exe set config "Contoso" /section:defaultDocument /enabled:true /+files.[value='home.html']

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample {

    private static void Main() {
        
        using(ServerManager serverManager = new ServerManager()) { 
            Configuration config = serverManager.GetWebConfiguration("Contoso");
            
            ConfigurationSection defaultDocumentSection = config.GetSection("system.webServer/defaultDocument");
            
            defaultDocumentSection["enabled"] = true;
            
            ConfigurationElementCollection filesCollection = defaultDocumentSection.GetCollection("files");
            ConfigurationElement addElement = filesCollection.CreateElement("add");
            addElement["value"] = @"home.html";
            filesCollection.AddAt(0, addElement);
            
            serverManager.CommitChanges();
        }
    }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Class Sample
   Shared Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Contoso")
      Dim defaultDocumentSection As ConfigurationSection = config.GetSection("system.webServer/defaultDocument")

      defaultDocumentSection("enabled") = True

      Dim filesCollection As ConfigurationElementCollection = defaultDocumentSection.GetCollection("files")
      Dim addElement As ConfigurationElement = filesCollection.CreateElement("add")
      addElement("value") = "home.html"
      filesCollection.AddAt(0, addElement)

      serverManager.CommitChanges()
   End Sub
End Class

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";

var defaultDocumentSection = adminManager.GetAdminSection("system.webServer/defaultDocument",
   "MACHINE/WEBROOT/APPHOST/Contoso");

defaultDocumentSection.Properties.Item("enabled").Value = true;

var filesCollection = defaultDocumentSection.ChildElements.Item("files").Collection;

var addElement = filesCollection.CreateNewElement("add");
addElement.Properties.Item("value").Value = "home.html";
filesCollection.AddElement(addElement, 0);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"

Set defaultDocumentSection = adminManager.GetAdminSection("system.webServer/defaultDocument", _
   "MACHINE/WEBROOT/APPHOST/Contoso")

defaultDocumentSection.Properties.Item("enabled").Value = True  

Set filesCollection = defaultDocumentSection.ChildElements.Item("files").Collection

Set addElement = filesCollection.CreateNewElement("add")
addElement.Properties.Item("value").Value = "home.html"
filesCollection.AddElement addElement, 0

adminManager.CommitChanges

Share via