默认文档 <defaultDocument>

项目
03/25/2024

概述

<defaultDocument> 元素允许你启用或禁用网站或应用程序的默认文档行为。此元素包含一个 <files> 子元素，其中包含 <add> 元素的集合。每个 <add> 元素定义站点或应用程序在站点收到对根目录的请求时将返回到客户端浏览器的默认文档。

<defaultDocument> 元素可以包含一个或多个 <remove> 元素。每个 <remove> 元素删除从 Internet Information Services （IIS） 7 服务器上的更高级别配置文件继承的特定默认文档文件。还可以使用 <clear> 元素删除配置层次结构中定义的更高级别的所有默认文档设置。

默认文档处于启用状态，IIS 7 将 ApplicationHost.config 文件中的以下默认文档文件定义为服务器范围的默认值：

Default.htm
Default.asp
Index.htm
Index.html
Iisstart.htm

（如果在 Web 服务器上安装 ASP.NET，安装过程会将 Default.aspx 文件添加到此列表中。）

默认情况下，当请求到达站点或应用程序的根目录时，IIS 7 会根据在 <defaultDocument> 元素中定义的文件名向浏览器发送响应。 IIS 尝试按 <defaultDocument> 元素中显示的顺序返回正确的文件。如果存在 Default.htm 文件，IIS 会将其发送到客户端浏览器。如果 Default.htm 文件不存在，IIS 将尝试将 Default.asp 文件发送到浏览器，如果Default.asp 文件不存在，IIS 将尝试将 Index.htm 文件发送到浏览器。 IIS 以这种方式继续，直到它尝试将每个默认文档文件发送到客户端浏览器。

注意

如果正确排列此默认文档列表的顺序，则可以提高 IIS 的性能。例如，如果打算对网站的所有文件夹中的主页使用 Index.php，并且将 Index.php 添加到默认文档列表的底部，则 IIS 必须在尝试将 Index.php 返回到客户端浏览器之前检查列表中每个默认文档。根据网站中的文件夹数和客户端浏览器请求数，这可能会影响性能。

如果禁用默认文档但已启用目录浏览，来自浏览器的根目录请求到达时，IIS 将返回目录列表。如果同时禁用默认文档和目录浏览，IIS 会将“HTTP 404 文件不存在”错误发送到浏览器。

兼容性

版本	说明
IIS 10.0	`<defaultDocument>` 元素在 IIS 10.0 中未进行修改。
IIS 8.5	`<defaultDocument>` 元素在 IIS 8.5 中未进行修改。
IIS 8.0	`<defaultDocument>` 元素在 IIS 8.0 中未进行修改。
IIS 7.5	`<defaultDocument>` 元素未在 IIS 7.5 中进行修改。
IIS 7.0	`<defaultDocument>` 元素是在 IIS 7.0 中引入的。
IIS 6.0	`<defaultDocument>` 元素替代了 IIsWebService 元数据库对象的 DirBrowseFlags 属性的 IIS 6.0 DefaultDoc 属性和 EnableDefaultDoc 值。

安装

<defaultDocument> 元素包含在 IIS 7 的默认安装中。

操作方式

如何为应用程序或站点添加默认文档

打开 Internet Information Services (IIS) 管理器：
- 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：
  - 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS) 管理器”。
- 如果使用 Windows 8 或 Windows 8.1：
  - 按住 Windows 键，按字母 X，然后单击“控制面板”。
  - 单击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。
- 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：
  - 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS) 管理器”。
- 如果使用的是 Windows Vista 或 Windows 7：
  - 在任务栏上，单击“开始”，然后单击“控制面板”。
  - 双击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。
在“连接”窗格中，展开服务器名称，展开“站点”，然后导航到要为其配置默认文件的网站或应用程序。
在“主页”窗格中，双击“默认文档”。
在“操作”窗格中，单击“添加...”。
在“添加默认文档”对话框中，在“名称”框中键入要添加的默认文档的名称，然后单击“确定”。
如有必要，在“操作”窗格中，选择列表中的默认文档，然后单击“上移”或“下移”以定义 IIS 搜索默认文档列表应使用的顺序。
在“默认文档”警报框中，单击“是”以拒绝从父配置级别的配置继承，或者单击“否”或“取消”以取消对默认文档顺序的更改。
如有必要，在“操作”窗格中单击“删除”来删除任何不想用作默认文档的文件名。

配置

可以通过更改 <defaultDocument> 元素中 <add> 元素的顺序来更改 IIS 处理默认文档的顺序。

使用 ApplicationHost.config 文件，可以在服务器级别配置 <defaultDocument> 元素，使用相应的 Web.config 文件，则可以在站点、应用程序或 URL 级别配置。

特性

属性	说明
`enabled`	可选布尔属性。指定启用默认文档。默认值为 `true`。

子元素

元素	说明
`files`	可选元素。指定可作为默认文档返回的文件名列表。

配置示例

以下配置示例，当包含在网站或应用程序的 Web.config 文件中时，将为站点或应用程序启用默认文档。然后，它会将文件名“Home.html”添加到站点或应用程序的默认文档列表中。

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

代码示例

以下示例对名为 Contoso 的网站启用默认文档，然后将名为 Home.html 的文件添加到网站的默认文档列表中。

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