Adicionar erros HTTP <error>

Artigo
03/25/2024

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.

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 atributo path deverá ser um caminho de arquivo. O valor numérico é `0`.
`ExecuteURL`	Atende conteúdo dinâmico (por exemplo, um arquivo de .asp) especificado no atributo path 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 de cliente para uma URL especificada no atributo path que contém 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`.

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()