Adición de errores HTTP <error>

  • Artículo

Información general

El elemento <error> de la colección <httpErrors> agrega una asignación única de errores a la colección de errores HTTP.

Compatibilidad

Versión Notas
IIS 10.0 El elemento <error> no se modificó en IIS 10.0.
IIS 8.5 El elemento <error> no se modificó en IIS 8.5.
IIS 8.0 El elemento <error> no se modificó en IIS 8.0.
IIS 7.5 El elemento <error> no se modificó en IIS 7.5.
IIS 7.0 El elemento <error> de la colección <httpErrors> se introdujo en IIS 7.0.
IIS 6,0 La colección <httpErrors> reemplaza a la sección HttpErrors de IIS 6.0 del objeto metabase IIsWebService.

Configuración

El elemento <error> de la colección <httpErrors> se incluye en la instalación predeterminada de IIS 7.

Procedimientos

Adición de una página de error personalizada

  1. Abra el Administrador de Internet Information Services (IIS):

    • Si usa Windows Server 2012 o Windows Server 2012 R2:

      • En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).

    • Si usa Windows 8 o Windows 8.1:

      • Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
      • En Panel de control, haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).

    • Si usa Windows Server 2008 o Windows Server 2008 R2:

      • En la barra de tareas, haga clic en Inicio, seleccione Herramientas administrativas y, a continuación, haga clic en Administrador de Internet Information Services (IIS).

    • Si usa Windows Vista o Windows 7:

      • En la barra de tareas, haga clic en Inicio y, luego, haga clic en Panel de control.
      • Haga doble clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).

  2. En el panel Conexiones, expanda el nombre del servidor, expanda Sitios y, a continuación, vaya al sitio o aplicación web en los que desea configurar páginas de error personalizadas.

  3. En el panel Inicio, haga doble clic en Páginas de error.
    Screenshot of the Home pane with the Error Pages option being highlighted.

  4. En el panel Acciones, haga clic en Agregar....

  5. En el cuadro de diálogo Agregar página de error personalizada, en Código de estado, escriba el número del código de estado HTTP para el que desea crear un mensaje de error personalizado.
    Screenshot of the Add Custom Error Page dialog box, showing the Status code field.

  6. En la sección Acción de respuesta, realice una de las acciones siguientes:

    • Seleccione Insertar contenido del archivo estático en la respuesta de error para servir contenido estático, por ejemplo, un archivo .html para el error personalizado.
    • Seleccione Ejecutar una dirección URL en este sitio para servir contenido dinámico, por ejemplo, un archivo .asp para el error personalizado.
    • Seleccione Responder con un redireccionamiento 302 para redirigir los exploradores cliente a una dirección URL diferente que contenga el archivo de error personalizado.

  7. En el cuadro de texto Ruta de archivo, escriba la ruta de acceso de la página de error personalizada si eligió Insertar contenido del archivo estático en la respuesta de error o la dirección URL de la página de error personalizada si usa Ejecutar una dirección URL en este sitio o Responder con un redireccionamiento 302 y, a continuación, haga clic en Aceptar.

    Nota:

    Si selecciona Ejecutar una dirección URL en este sitio, la ruta de acceso debe ser una ruta de acceso relativa. Si selecciona Responder con un redireccionamiento 302, la dirección URL debe ser una dirección URL absoluta.

    Nota:

    Los siguientes errores HTTP no se pueden personalizar: 400, 403.9, 411, 414, 500, 500.11, 500.14, 500.15, 501, 503 y 505.

Configuración

Atributos

Atributo Descripción
path Atributo de cadena necesario.

Especifica la ruta de archivo o la dirección URL que se sirve en respuesta al error HTTP especificado por los atributos statusCode y subStatusCode. Si elige el modo de respuesta de archivo, especificará la ruta de acceso de la página de errores personalizada. Si elige el modo de respuesta ExecuteURL, la ruta de acceso debe ser una dirección URL relativa del servidor (por ejemplo, /404.htm). Si elige el modo de respuesta Redirect, debe escribir una dirección URL absoluta (por ejemplo, www.contoso.com/404.htm).
prefixLanguageFilePath Atributo de cadena opcional.

Especifica el segmento de ruta al generar la ruta de acceso para un error personalizado. Este segmento aparece antes de la parte específica del idioma de la ruta de acceso al error personalizado. Por ejemplo, en la ruta de acceso C:\Inetpub\Custerr\en-us\404.htm, C:\Inetpub\Custerr es el elemento prefixLanguageFilePath.
responseMode Atributo enum opcional.

Especifica cómo se devuelve el contenido de errores personalizados.

El atributo responseMode puede tener uno de los siguientes valores posibles. El valor predeterminado es File.
Valor Descripción
File Sirve contenido estático, por ejemplo, un archivo .html para el error personalizado.

Si responseMode se establece en Archivo, el valor del atributo path tiene que ser una ruta de archivo.

El valor numérico es 0.
ExecuteURL Sirve contenido dinámico (por ejemplo, un archivo .asp) especificado en el atributo path para el error personalizado.

Si responseMode se establece en ExecuteURL, el valor de la ruta de acceso debe ser una dirección URL relativa del servidor.

El valor numérico es 1.
Redirect Redirige los exploradores de cliente a una dirección URL especificada en el atributo path que contiene el archivo de error personalizado.

Si responseMode se establece en Redirect, el valor de la ruta de acceso debe ser una dirección URL absoluta.

El valor numérico es 2.
statusCode Atributo uint obligatorio.

Especifica el número del código de estado HTTP para el que desea crear un mensaje de error personalizado. Los valores aceptables están comprendidos entre 400 y 999.
subStatusCode Atributo int opcional.

Especifica el número del código de subestado HTTP para el que desea crear un mensaje de error personalizado. Los valores aceptables están comprendidos entre -1 y 999.

El valor predeterminado es -1.

Elementos secundarios

Ninguno.

Ejemplo de configuración

En el ejemplo de configuración siguiente, cuando se incluye en el archivo Web.config para un sitio o aplicación web, se usa el atributo errorMode para permitir que solo aparezcan mensajes de error detallados en el equipo local. También se usa el atributo defaultResponseMode para establecer el modo de respuesta para el sitio o la aplicación. A continuación, en el ejemplo se quita el mensaje de error heredado para el código de estado 500. Luego, se establece el atributo prefixLanguageFilePath en el directorio donde IIS debe buscar una nueva página de error personalizada y establece el atributo path en 500.htm, el archivo que contiene el mensaje de error personalizado.

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

Código de ejemplo

En los ejemplos siguientes se agrega un nuevo archivo para todos los errores de código de estado 404 con un subestado de 5, que IIS devuelve para errores en "Secuencia de direcciones URL denegadas". En estos ejemplos, la ruta de acceso del prefijo se establece en "%SystemDrive%\inetpub\custerr" y el nombre de archivo se especifica 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

Nota:

Debe asegurarse de establecer el parámetro de confirmación en apphost cuando use AppCmd.exe para configurar estas opciones. Esto confirma los valores de configuración en la sección de ubicación adecuada del archivo 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()