Adicionar erros HTTP <error>
Visão geral
O elemento <error> da coleção <httpErrors> adiciona um mapeamento de erro exclusivo à coleção de erros HTTP.
Compatibilidade
| Versão | Observações |
|---|---|
| IIS 10.0 | O elemento <error> não foi modificado no IIS 10.0. |
| IIS 8.5 | O elemento <error> não foi modificado no IIS 8.5. |
| IIS 8.0 | O elemento <error> não foi modificado no IIS 8.0. |
| IIS 7.5 | O elemento <error> não foi modificado no IIS 7.5. |
| IIS 7.0 | O elemento <error> da coleção <httpErrors> foi introduzido no IIS 7.0. |
| IIS 6,0 | A coleção <httpErrors> substitui a seção HttpErrors do IIS 6.0 do objeto de metabase IIsWebService. |
Instalação
O elemento <error> da coleção <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.
Observação
Os seguintes erros HTTP não podem ser personalizados: 400, 403.9, 411, 414, 500, 500.11, 500.14, 500.15, 501, 503 e 505.
Configuração
Atributos
| Atributo | Descrição | ||||||||
|---|---|---|---|---|---|---|---|---|---|
path |
Atributo de cadeia de caracteres obrigatório. Especifica o caminho do arquivo ou a URL que é fornecida em resposta ao erro HTTP especificado pelos atributos statusCode e subStatusCode. Se você escolher o modo de resposta File, especifique o caminho da página de erro personalizada. Se você escolher o modo de resposta ExecuteURL, o caminho deverá ser uma URL relativa do servidor (por exemplo, /404.htm). Se você escolher o modo de resposta Redirect, deverá inserir uma URL absoluta (por exemplo, www.contoso.com/404.htm). |
||||||||
prefixLanguageFilePath |
Atributo de cadeia de caracteres opcional. Especifica o segmento de caminho inicial ao gerar o caminho para um erro personalizado. Esse segmento é exibido antes da parte específica a um idioma do caminho de erro personalizado. Por exemplo, no caminho C:\Inetpub\Custerr\en-us\404.htm, C:\Inetpub\Custerr é o prefixLanguageFilePath. |
||||||||
responseMode |
Atributo de enumeração opcional. Especifica como o conteúdo de erro personalizado é retornado. O atributo responseMode pode ser um dos valores possíveis a seguir. O padrão é File.
|
||||||||
statusCode |
Atributo uint obrigatório. Especifica o número do código de status HTTP para o qual você deseja criar uma mensagem de erro personalizada. Os valores aceitáveis estão no intervalo de 400 a 999. |
||||||||
subStatusCode |
Atributo int opcional. Especifica o número do código de substatus HTTP para o qual você deseja criar uma mensagem de erro personalizada. Os valores aceitáveis estão no intervalo de -1 a 999. O valor padrão é -1. |
Elementos filho
Nenhum.
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()