Documento predeterminado <defaultDocument>
Información general
El elemento <defaultDocument> permite habilitar o deshabilitar el comportamiento predeterminado del documento para su aplicación o sitio web. Este elemento contiene un elemento secundario <files>, que contiene una colección de elementos <add>. Cada elemento <add> define los documentos predeterminados que el sitio o la aplicación devolverán a un explorador cliente cuando el sitio reciba una solicitud al directorio raíz.
El elemento <defaultDocument> también puede contener uno o más elementos <remove>. Cada elemento <remove> quita un archivo de documento predeterminado específico heredado de un archivo de configuración de nivel superior en el servidor de Internet Information Services (IIS) 7. También puede usar el elemento <clear> para quitar toda la configuración predeterminada del documento que se define más arriba en la jerarquía de configuración.
Los documentos predeterminados están habilitados de forma predeterminada e IIS 7 define los siguientes archivos de documento predeterminados en el archivo ApplicationHost.config como valores predeterminados para todo el servidor:
- Default.htm
- Default.asp
- Index.htm
- Index.html
- Iisstart.htm
(Si instala ASP.NET en el servidor web, el proceso de instalación agregará el archivo Default.aspx a esta lista).
De forma predeterminada, cuando llega una solicitud para el directorio raíz de la aplicación o del sitio, IIS 7 envía una respuesta al explorador en función de los nombres de archivo que haya definido en el elemento <defaultDocument>. IIS intenta devolver los archivos correctos en el orden en el que aparecen en el elemento <defaultDocument>. Si el archivo Default.htm existe, IIS lo envía al explorador cliente. Si el archivo Default.htm no existe, IIS intenta enviar el archivo Default.asp al explorador y, en caso de que este archivo no exista, IIS intenta enviar el archivo Index.htm al explorador. IIS continúa de esta forma hasta que prueba a enviar cada archivo de documento predeterminado al explorador cliente.
Nota:
Si ordena esta lista de documentos predeterminados de forma correcta, puede ayudar a que mejore el rendimiento de IIS. Por ejemplo, si pretendía usar Index.php para la página principal en todas las carpetas del sitio web y agrega Index.php a la parte inferior de la lista de documentos predeterminados, IIS tendrá que comprobar cada uno de los documentos predeterminados en la lista antes de intentar devolver Index.php al explorador cliente. En función del número de carpetas del sitio web y del número de solicitudes del explorador cliente, esto puede afectar al rendimiento.
Si deshabilita los documentos predeterminados pero ha habilitado el examen de directorios, IIS devuelve una lista de directorios cuando llega una solicitud para el directorio raíz desde un explorador. Si deshabilita tanto los documentos predeterminados como el examen de directorios, IIS envía el error "HTTP 404: El archivo no existe" al explorador.
Compatibilidad
| Versión | Notas |
|---|---|
| IIS 10.0 | El elemento <defaultDocument> no se modificó en IIS 10.0. |
| IIS 8.5 | El elemento <defaultDocument> no se modificó en IIS 8.5. |
| IIS 8.0 | El elemento <defaultDocument> no se modificó en IIS 8.0. |
| IIS 7.5 | El elemento <defaultDocument> no se modificó en IIS 7.5. |
| IIS 7.0 | El elemento <defaultDocument> se introdujo en IIS 7.0. |
| IIS 6,0 | El elemento <defaultDocument> reemplaza la propiedad DefaultDoc de IIS 6.0 y el valor EnableDefaultDoc de la propiedad DirBrowseFlags en el objeto de metabase IIsWebService. |
Configuración
El elemento <defaultDocument> se incluye en la instalación predeterminada de IIS 7.
Procedimientos
Cómo agregar un documento predeterminado para una aplicación o un sitio
Abra el Administrador de Internet Information Services (IIS):
Si usa Windows Server 2012 o Windows Server 2012 R2:
- En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).
Si usa Windows 8 o Windows 8.1:
- Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
- Haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
Si usa Windows Server 2008 o Windows Server 2008 R2:
- En la barra de tareas, haga clic en Inicio, seleccione Herramientas administrativas y, a continuación, haga clic en Administrador de Internet Information Services (IIS).
Si usa Windows Vista o Windows 7:
- En la barra de tareas, haga clic en Inicio y, luego, haga clic en Panel de control.
- Haga doble clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
En el panel Conexiones, expanda el nombre del servidor, expanda Sitios y, a continuación, vaya a la aplicación o al sitio web donde quiere configurar los documentos predeterminados.
En el panel Inicio, haga doble clic en Documento predeterminado.
En el panel Acciones, haga clic en Agregar....
En el cuadro de diálogo Agregar documento predeterminado, escriba el nombre del documento predeterminado que quiere agregar en el cuadro Nombre y, a continuación, haga clic en Aceptar.
Si es necesario, en el panel Acciones, seleccione un documento predeterminado de la lista y, a continuación, haga clic en Subir o Bajar para definir el orden en el que IIS debe buscar en la lista de documentos predeterminados.
En el cuadro de alerta Documento predeterminado, haga clic en Sí para rechazar la herencia de configuración de un nivel de configuración primario, o bien haga clic en No o en Cancelar para cancelar el cambio en el orden de los documentos predeterminados.
Si es necesario, haga clic en Quitar en el panel Acciones para quitar los nombres de archivo que no quiera usar como documentos predeterminados.
Configuración
Puede cambiar el orden en el que IIS procesa los documentos predeterminados si cambia el orden de los elementos <add> en el elemento <defaultDocument>.
Puede configurar el elemento <defaultDocument> en el nivel de servidor en el archivo ApplicationHost.config y en el nivel de sitio, de aplicación o de dirección URL en el archivo Web.config correspondiente.
Atributos
| Atributo | Descripción |
|---|---|
enabled |
Atributo Boolean opcional. Especifica que los documentos predeterminados están habilitados. El valor predeterminado es true. |
Elementos secundarios
| Elemento | Descripción |
|---|---|
files |
Elemento opcional. Especifica una lista de nombres de archivo que se pueden devolver como documentos predeterminados. |
Ejemplo de configuración
El ejemplo de configuración siguiente, cuando se incluye en un archivo Web.config para un sitio o aplicación, habilita documentos predeterminados para el sitio o la aplicación. Después, agrega el nombre de archivo "Home.html" a la lista de documentos predeterminados del sitio o de la aplicación.
<configuration>
<system.webServer>
<defaultDocument enabled="true">
<files>
<add value="home.html" />
</files>
</defaultDocument>
</system.webServer>
</configuration>
Código de ejemplo
En los ejemplos siguientes se habilitan documentos predeterminados en un sitio web llamado Contoso y, después, se agrega un archivo denominado Home.html a la lista de documentos predeterminados del sitio.
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