Erros HTTP <httpErrors>

Artigo
03/25/2024

Visão geral

O elemento <httpErrors> permite que você configure mensagens de erro personalizadas para seu site ou aplicativo. As mensagens de erro personalizadas permitem fornecer uma resposta amigável ou mais informativa por meio do fornecimento de um arquivo, da devolução de outro recurso ou do redirecionamento para uma URL quando os visitantes de seu site não podem acessar o conteúdo solicitado. Por exemplo, convém personalizar cada uma das páginas de mensagens de erro de seu site com a mesma aparência do restante do site.

O elemento <httpErrors> contém uma coleção de elementos <error>, cada um dos quais define uma mensagem de erro que o IIS usa para responder a erros HTTP específicos. Você pode adicionar mensagens de erro personalizadas ao IIS adicionando um elemento <error> ao elemento <httpErrors> no arquivo Web.config para seu site, aplicativo ou URL. Cada elemento <error> usa o atributo responseMode para especificar se o IIS serve conteúdo estático, conteúdo dinâmico ou redirecionamentos para uma URL separada em resposta a um erro.

Você pode usar o elemento <remove> para remover uma mensagem de erro específica da coleção de mensagens de erro que seu site ou aplicativo herda de um nível mais alto na hierarquia de configuração do IIS. Além disso, você pode usar o elemento <clear> para remover todas as mensagens de erro HTTP da coleção de mensagens de erro HTTP herdadas pelo seu site ou aplicativo.

O elemento <httpErrors> também contém atributos que configuram o IIS 7 para processar solicitações que causam erros. O atributo existingResponse define o que o IIS 7 faz com uma resposta existente quando o servidor retorna um código de status de erro HTTP. O atributo defaultPath define o caminho para uma página de erro do cliente se você escolher especificar Arquivo para o atributo responseMode em um elemento <error>.

O atributo detailedMoreInformationLink especifica um link para obter mais informações sobre um erro específico.

O elemento <httpErrors> também pode conter um atributo errorMode que você pode usar para controlar o nível de detalhes que o IIS retorna a um navegador quando ocorre um erro HTTP. Você pode definir o atributo errorMode como DetailedLocalOnly, que é a configuração padrão, ou pode defini-lo como Personalizado ou Detalhado. Se você especificar DetailedLocalOnly ou se não especificar um valor errorMode, o IIS retornará informações detalhadas de erro apenas para o navegador no servidor local e uma mensagem de erro personalizada para um navegador em um computador externo. Se você definir o valor errorMode como Personalizado, o IIS retornará apenas mensagens de erro personalizadas para todos os navegadores solicitantes. Se você definir o valor errorMode como Detailed, o IIS retornará informações detalhadas de erro para todos os navegadores solicitantes. O valor DetailedLocalOnly permite solucionar problemas de erros HTTP no servidor local, sem expor informações confidenciais a navegadores externos.

Por padrão, o IIS fornece mensagens de erro definidas em arquivos armazenados na pasta %SystemRoot%\Help\IisHelp\Common. Você pode criar uma mensagem de erro personalizada para os usuários e configurar o IIS para retornar esta página sempre que encontrar um erro HTTP específico em seu site.

Compatibilidade

Versão	Observações
IIS 10.0	O elemento `<httpErrors>` não foi modificado no IIS 10.0.
IIS 8.5	O elemento `<httpErrors>` não foi modificado no IIS 8.5.
IIS 8.0	O elemento `<httpErrors>` não foi modificado no IIS 8.0.
IIS 7.5	O atributo `allowAbsolutePathsWhenDelegated` foi adicionado ao elemento `<httpErrors>` no IIS 7.5.
IIS 7.0	O elemento `<httpErrors>` foi introduzido no IIS 7.0.
IIS 6,0	O elemento `<httpErrors>` substitui a propriedade HttpErrors do IIS 6.0 do objeto de metabase IIsWebService.

Instalação

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

Instruções

Como adicionar uma página de erro personalizada

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 deseja configurar páginas de erro personalizadas.
No painel Página Inicial, clique duas vezes em Páginas de Erro.
No painel Ações, clique em Adicionar.
Na caixa de diálogo Adicionar Página de Erro Personalizado, em Código de status, digite o número do código de status HTTP para o qual você deseja criar uma mensagem de erro personalizada.
Na seção Ação de resposta, siga um destes procedimentos:
- Selecione Inserir conteúdo do arquivo estático na resposta de erro para fornecer conteúdo estático, por exemplo, um arquivo .html, para o erro personalizado.
- Selecione Executar uma URL neste site para fornecer conteúdo dinâmico, por exemplo, um arquivo .asp para o erro personalizado.
- Selecione Responder com um redirecionamento 302 para redirecionar navegadores cliente para uma URL diferente que contenha o arquivo de erro personalizado.
Na caixa de texto Caminho do arquivo, digite o caminho da página de erro personalizada se você escolheu Inserir conteúdo do arquivo estático na resposta de erro ou na URL da página de erro personalizada se você usar o Executar uma URL neste site ou Responder com um de redirecionamento 302, e clique em OK.

Observação

Se você selecionar Executar uma URL neste site, o caminho deverá ser um caminho relativo. Se você selecionar Responder com um de redirecionamento 302, a URL deverá ser uma URL absoluta.

Configuração

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

Atributos

Atributo Descrição

allowAbsolutePathsWhenDelegated Atributo booliano opcional.

Quando definido como verdadeiro, os caminhos absolutos são permitidos para páginas de erro personalizadas quando a seção <httpErrors> é delegada. Quando definido como falso, somente os caminhos relativos à raiz do site são permitidos.

O valor padrão é false.

defaultPath Atributo de cadeia de caracteres opcional.

Especifica o caminho padrão da página de erro personalizada. O tipo de caminho é determinado pelo atributo defaultResponseMode. Se você escolher Arquivo, o caminho do arquivo será retornado. Se você escolher o tipo de caminho ExecuteURL ou Redirecionamento, a URL da página de erro personalizada será retornada.

defaultResponseMode

Atributo de enumeração opcional.

Especifica como o conteúdo de erro personalizado é retornado.

O atributo defaultResponseMode pode ser um dos seguintes valores possíveis; o padrão é File.

Valor	Descrição
`File`	Serve conteúdo estático, por exemplo, um arquivo .html para o erro personalizado. Se responseMode estiver definido como Arquivo, o valor do caminho deverá ser um caminho de arquivo. O valor numérico é `0`.
`ExecuteURL`	Serve conteúdo dinâmico, por exemplo, um arquivo de .asp para o erro personalizado. Se responseMode estiver definido como ExecuteURL, o valor do caminho deverá ser uma URL relativa do servidor. O valor numérico é `1`.
`Redirect`	Redireciona navegadores cliente para uma URL diferente que contenha o arquivo de erro personalizado. Se responseMode estiver definido como Redirecionamento, o valor do caminho deverá ser uma URL absoluta. O valor numérico é `2`.

detailedMoreInformationLink Atributo de cadeia de caracteres opcional.

Especifica um link, mostrado na parte inferior da página, para uma página com informações mais detalhadas sobre um erro específico. Você pode usar essa propriedade para apontar os usuários finais para um local personalizado para obter informações de erro. O status, o sub-status, o HRESULT e a ID da mensagem são enviados como parte da cadeia de caracteres de consulta.

O valor padrão é https://go.microsoft.com/fwlink/?LinkID=62293.

errorMode

Atributo de enumeração opcional.

Especifica se os erros HTTP estão habilitados.

O atributo errorMode pode ser um dos valores a seguir; o valor padrão é DetailedLocalOnly.

Valor	Descrição
`DetailedLocalOnly`	Retorna informações detalhadas de erro se a solicitação for do computador local e retornará uma mensagem de erro personalizada se a solicitação for de um computador externo. O valor numérico é `0`.
`Custom`	Substitui o erro gerado pelo módulo ou servidor por uma página personalizada que você especificar. Esse modo é útil para fornecer mensagens de erro mais amigáveis aos usuários finais. Observação: essa configuração desativa erros detalhados, mesmo para solicitações locais. O valor numérico é `1`.
`Detailed`	Envia informações detalhadas de erro de volta ao cliente. Esse modo é útil para testar e depurar sites e aplicativos da Web. O valor numérico é `2`.

existingResponse

Atributo de enumeração opcional.

Especifica o que acontece com uma resposta existente quando o código de status HTTP é um erro, ou seja, códigos de resposta >= 400.

O atributo existingResponse pode ser um dos valores a seguir; o valor padrão é Auto.

Valor	Descrição
`Auto`	Deixa a resposta intocada somente se o sinalizador SetStatus estiver definido. O valor numérico é `0`.
`Replace`	Substitui a resposta existente mesmo se o sinalizador SetStatus estiver definido. O valor numérico é `1`.
`PassThrough`	Deixa a resposta intocada se houver uma resposta existente. O valor numérico é `2`.

Elementos filho

Elemento	Descrição
`error`	Elemento opcional. Adiciona um erro HTTP à coleção de erros HTTP.
`remove`	Elemento opcional. Remove uma referência a um erro HTTP da coleção de erros HTTP.
`clear`	Elemento opcional. Remove todas as referência a erros HTTP da coleção de erros HTTP.

Exemplo de configuração

O exemplo de configuração a seguir, quando incluído no arquivo Web.config para um site ou aplicativo, usa o atributo errorMode para permitir que apenas mensagens de erro detalhadas apareçam no computador local. Ele também usa o atributo defaultResponseMode para definir o modo de resposta para o site ou aplicativo. Em seguida, o exemplo remove a mensagem de erro herdada do código de status 500. Em seguida, ele define o atributo prefixLanguageFilePath para o diretório em que o IIS deve pesquisar uma nova página de erro personalizada e define o atributo path como 500.htm, o arquivo que contém a mensagem de erro personalizada.

<configuration>
   <system.webServer>
      <httpErrors errorMode="DetailedLocalOnly" defaultResponseMode="File" >
         <remove statusCode="500" />
         <error statusCode="500"
            prefixLanguageFilePath="C:\Contoso\Content\errors"
            path="500.htm" />
       </httpErrors>
   </system.webServer>
</configuration>

Exemplo de código

Os exemplos a seguir adicionam um novo arquivo para todos os erros de código de status 404 com um substatus de 5, que o IIS retorna para erros de “Sequência de URL Negada”. Nesses exemplos, o caminho do prefixo é definido como “%SystemDrive%\inetpub\custerr”, e o nome do arquivo é especificado como “404.5.htm”.

AppCmd.exe

appcmd.exe set config -section:system.webServer/httpErrors /+"[statusCode='404',subStatusCode='5',prefixLanguageFilePath='%SystemDrive%\inetpub\custerr',path='404.5.htm']" /commit:apphost

Observação

Defina o parâmetro commit para apphost quando usar AppCmd.exe para definir essas configurações. Isso confirma as definições de configuração para a seção de local apropriado no arquivo ApplicationHost.config.

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.GetApplicationHostConfiguration();
         ConfigurationSection httpErrorsSection = config.GetSection("system.webServer/httpErrors");
         ConfigurationElementCollection httpErrorsCollection = httpErrorsSection.GetCollection();

         ConfigurationElement errorElement = httpErrorsCollection.CreateElement("error");
         errorElement["statusCode"] = 404;
         errorElement["subStatusCode"] = 5;
         errorElement["prefixLanguageFilePath"] = @"%SystemDrive%\inetpub\custerr";
         errorElement["path"] = @"404.5.htm";
         httpErrorsCollection.Add(errorElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

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

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim httpErrorsSection As ConfigurationSection = config.GetSection("system.webServer/httpErrors")
      Dim httpErrorsCollection As ConfigurationElementCollection = httpErrorsSection.GetCollection

      Dim errorElement As ConfigurationElement = httpErrorsCollection.CreateElement("error")
      errorElement("statusCode") = 404
      errorElement("subStatusCode") = 5
      errorElement("prefixLanguageFilePath") = "%SystemDrive%\inetpub\custerr"
      errorElement("path") = "404.5.htm"
      httpErrorsCollection.Add(errorElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST");
var httpErrorsCollection = httpErrorsSection.Collection;

var errorElement = httpErrorsCollection.CreateNewElement("error");
errorElement.Properties.Item("statusCode").Value = 404;
errorElement.Properties.Item("subStatusCode").Value = 5;
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\\inetpub\\custerr";
errorElement.Properties.Item("path").Value = "404.5.htm";
httpErrorsCollection.AddElement(errorElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST")
Set httpErrorsCollection = httpErrorsSection.Collection

Set errorElement = httpErrorsCollection.CreateNewElement("error")
errorElement.Properties.Item("statusCode").Value = 404
errorElement.Properties.Item("subStatusCode").Value = 5
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\inetpub\custerr"
errorElement.Properties.Item("path").Value = "404.5.htm"
httpErrorsCollection.AddElement errorElement

adminManager.CommitChanges()