Documento padrão <defaultDocument>

Artigo
03/25/2024

Visão geral

O elemento <defaultDocument> permite habilitar ou desabilitar o comportamento padrão do documento para seu site ou aplicativo. Esse elemento contém um elemento filho <files>, que contém uma coleção de elementos <add>. Cada elemento <add> define os documentos padrão que o site ou aplicativo retornará a um navegador do cliente quando o site receber uma solicitação para o diretório raiz.

O elemento <defaultDocument> também pode conter um elemento <remove>. Cada elemento <remove> remove um arquivo de documento padrão específico herdado de um arquivo de configuração de nível superior no servidor IIS (Serviços de Informações da Internet) 7. Você também pode usar o elemento <clear> para remover todas as configurações de documento padrão definidas mais alto na hierarquia de configuração.

Os documentos padrão são habilitados por padrão, e o IIS 7 define os seguintes arquivos de documento padrão no arquivo ApplicationHost.config como padrões de todo o servidor:

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

(Se você instalar ASP.NET em seu servidor Web, o processo de instalação adicionará o arquivo Default.aspx a esta lista.)

Por padrão, quando uma solicitação chega para o diretório raiz do seu site ou aplicativo, o IIS 7 envia uma resposta ao navegador com base nos nomes de arquivo definidos no elemento <defaultDocument>. O IIS tenta retornar os arquivos corretos na ordem em que eles aparecem no elemento <defaultDocument>. Se o arquivo Default.htm existir, o IIS o enviará para o navegador do cliente. Se o arquivo Default.htm não existir, o IIS tentará enviar o arquivo Default.asp para o navegador e, se o arquivo Default.asp não existir, o IIS tentará enviar o arquivo Index.htm para o navegador. O IIS continua dessa maneira até tentar enviar cada arquivo de documento padrão para o navegador do cliente.

Observação

Se você solicitar essa lista de documentos padrão corretamente, poderá melhorar o desempenho do IIS. Por exemplo, se você pretendia usar Index.php para a home page em todas as pastas do seu site e adicionar Index.php à parte inferior da lista de documentos padrão, o IIS terá que verificar cada um dos documentos padrão na lista antes de tentar retornar Index.php ao navegador do cliente. Dependendo do número de pastas em seu site e do número de solicitações do navegador do cliente, isso pode afetar seu desempenho.

Se você desabilitar documentos padrão, mas tiver habilitado a navegação de diretório, o IIS retornará uma listagem de diretório quando uma solicitação para o diretório raiz chegar de um navegador. Se você desabilitar documentos padrão e navegação de diretório, o IIS enviará um erro “Arquivo HTTP 404 não existe” para o navegador.

Compatibilidade

Versão	Observações
IIS 10.0	O elemento `<defaultDocument>` não foi modificado no IIS 10.0.
IIS 8.5	O elemento `<defaultDocument>` não foi modificado no IIS 8.5.
IIS 8.0	O elemento `<defaultDocument>` não foi modificado no IIS 8.0.
IIS 7.5	O elemento `<defaultDocument>` não foi modificado no IIS 7.5.
IIS 7.0	O elemento `<defaultDocument>` foi introduzido no IIS 7.0.
IIS 6,0	O elemento `<defaultDocument>` substitui a propriedade DefaultDoc do IIS 6.0 e o valor EnableDefaultDoc da propriedade DirBrowseFlags no objeto de metabase IIsWebService.

Instalação

O elemento <defaultDocument> está incluído na instalação padrão do IIS 7.

Instruções

Como adicionar um documento padrão para um aplicativo ou site

Abra o Gerenciador dos Serviços de Informações da Internet (IIS):
- Caso você esteja usando o Windows Server 2012 ou o Windows Server 2012 R2:
  - Na barra de tarefas, clique em Gerenciador do Servidor, em Ferramentas e em Gerenciador dos Serviços de Informações da Internet (IIS).
- Se você estiver usando o Windows 8 ou Windows 8.1:
  - Mantenha pressionada a tecla Windows, pressione a letra X e clique em Painel de Controle.
  - Clique em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
- Caso você esteja usando o Windows Server 2008 ou o Windows Server 2008 R2:
  - Na barra de tarefas, clique em Iniciar, vá para Ferramentas Administrativas e clique em Gerenciador dos Serviços de Informações da Internet (IIS).
- Se você estiver usando o Windows Vista ou Windows 7:
  - Na barra de tarefas, clique em Iniciar e, depois, em Painel de Controle.
  - Clique duas vezes em Ferramentas Administrativas e clique duas vezes em Gerenciador dos Serviços de Informações da Internet (IIS).
No painel Conexões, expanda o nome do servidor, expanda Sites e navegue até o site ou aplicativo para o qual você deseja configurar documentos padrão.
No painel Página Inicial, clique duas vezes em Documento Padrão.
No painel Ações, clique em Adicionar.
Na caixa de diálogo Adicionar Documento Padrão, digite o nome do documento padrão que você deseja adicionar na caixa Nome e clique em OK.
Se necessário, no painel Ações, selecione um documento padrão na lista e clique em Mover para Cima ou Mover para Baixo para definir a ordem na qual o IIS deve pesquisar pela lista de documentos padrão.
Na caixa de alerta Documento Padrão, clique em Sim para recusar a herança de configuração de um nível de configuração pai ou clique em Não ou Cancelar para cancelar a alteração na ordem de documento padrão.
Se necessário, clique em Remover no painel Ações para remover quaisquer nomes de arquivo que você não deseje usar como documentos padrão.

Configuração

Você pode alterar a ordem na qual o IIS processa documentos padrão alterando a ordem dos elementos <add> no elemento <defaultDocument>.

Você pode configurar o elemento <defaultDocument> no nível do servidor no arquivo ApplicationHost.config e no nível do site, aplicativo ou URL no arquivo Web.config apropriado.

Atributos

Atributo	Descrição
`enabled`	Atributo booliano opcional. Especifica que os documentos padrão estão habilitados. O valor padrão é `true`.

Elementos filho

Elemento	Descrição
`files`	Elemento opcional. Especifica uma lista de nomes de arquivo que podem ser retornados como documentos padrão.

Exemplo de configuração

O exemplo de configuração a seguir, quando incluído em um arquivo Web.config para um site ou aplicativo, habilita os documentos padrão do site ou aplicativo. Em seguida, ele adiciona o nome do arquivo “Home.html” à lista dos documentos padrão do site ou do aplicativo.

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

Exemplo de código

Os exemplos a seguir habilitam os documentos padrão em um site chamado Contoso e, em seguida, adicionam um arquivo chamado Home.html à lista de documentos padrão do 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

Compartilhar via