Erros HTTP <httpErrors>
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.
|
||||||||
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.
|
||||||||
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.
|
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()