Errores HTTP <httpErrors>
Información general
El elemento <httpErrors> le permite configurar mensajes de error personalizados para el sitio o aplicación web. Los mensajes de error personalizados le permiten proporcionar una respuesta sencilla o más informativa al suministrar un archivo, devolver otro recurso o redirigir a una dirección URL cuando los visitantes de su sitio no pueden acceder al contenido que solicitaron. Por ejemplo, quizás desee personalizar cada una de las páginas de mensajes de error del sitio web para que tengan la misma apariencia y comportamiento que el resto del sitio.
El elemento <httpErrors> contiene una colección de elementos <error>, cada uno de los cuales define un mensaje de error que IIS usa para responder a errores HTTP específicos. Puede agregar mensajes de error personalizados a IIS agregando un elemento <error> al elemento <httpErrors> en el archivo Web.config para el sitio, aplicación o dirección URL. Cada elemento <error> usa el atributo responseMode para especificar si IIS sirve contenido estático o dinámico o redirige a una dirección URL independiente en respuesta a un error.
Puede usar el elemento <remove> para quitar un mensaje de error específico de la colección de mensajes de error que su sitio o aplicación hereda de un nivel superior en la jerarquía de configuración de IIS. Además, puede usar el elemento <clear> para quitar todos los mensajes de error HTTP de la colección de mensajes de error HTTP que hereda el sitio o la aplicación.
El elemento <httpErrors> también contiene atributos que configuran IIS 7 para procesar solicitudes que provocan errores. El atributo existingResponse define lo que hace IIS 7 a una respuesta existente cuando el servidor devuelve un código de estado de error HTTP. El atributo defaultPath define la ruta de acceso a una página de error del cliente si elige especificar Archivo para el atributo responseMode en un elemento <error>.
El atributo detailedMoreInformationLink especifica un vínculo a más información sobre un error determinado.
El elemento <httpErrors> también puede contener un atributo errorMode que puede usar para controlar el nivel de detalle que IIS devuelve a un explorador cuando se produce un error HTTP. Puede establecer el atributo errorMode en DetailedLocalOnly, que es la configuración predeterminada, o bien puede establecerlo en Custom o Detailed. Si especifica DetailedLocalOnly o, si no especifica un valor errorMode, IIS devuelve información detallada del error solo al explorador del servidor local y un mensaje de error personalizado a un explorador de un equipo externo. Si establece el valor errorMode en Custom, IIS devuelve solo mensajes de error personalizados a todos los exploradores solicitantes. Si establece el valor errorMode en Detailed, IIS devuelve información detallada del error a todos los exploradores solicitantes. El valor DetailedLocalOnly predeterminado le permite solucionar errores HTTP en el servidor local, al tiempo que no se expone información confidencial a exploradores externos.
De forma predeterminada, IIS proporciona mensajes de error definidos en los archivos almacenados en la carpeta %SystemRoot%\Help\IisHelp\Common. Puede crear un mensaje de error personalizado para los usuarios y configurar IIS para que devuelva esta página cada vez que encuentre un error HTTP específico en el sitio.
Compatibilidad
| Versión | Notas |
|---|---|
| IIS 10.0 | El elemento <httpErrors> no se modificó en IIS 10.0. |
| IIS 8.5 | El elemento <httpErrors> no se modificó en IIS 8.5. |
| IIS 8.0 | El elemento <httpErrors> no se modificó en IIS 8.0. |
| IIS 7.5 | El atributo allowAbsolutePathsWhenDelegated se agregó al elemento <httpErrors> en IIS 7.5. |
| IIS 7.0 | El elemento <httpErrors> se introdujo en IIS 7.0. |
| IIS 6,0 | El elemento <httpErrors> reemplaza a la propiedad HttpErrors de IIS 6.0 del objeto metabase IIsWebService. |
Configuración
El elemento <httpErrors> se incluye en la instalación predeterminada de IIS 7.
Procedimientos
Adición de una página de error personalizada
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).
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.
En el panel Inicio, haga doble clic en Páginas de error.
En el panel Acciones, haga clic en Agregar....
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.
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.
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.
Configuración
Puede configurar el elemento <httpErrors> a nivel de servidor en el archivo ApplicationHost.config y a nivel de sitio y aplicación en el archivo Web.config adecuado.
Atributos
| Atributo | Descripción | ||||||||
|---|---|---|---|---|---|---|---|---|---|
allowAbsolutePathsWhenDelegated |
Atributo Boolean opcional. Cuando se establece en true, se permiten rutas de acceso absolutas para páginas de error personalizadas cuando se delega la sección <httpErrors>. Cuando se establece en false, solo se permiten rutas de acceso relativas a la raíz del sitio.El valor predeterminado es false. |
||||||||
defaultPath |
Atributo de cadena opcional. Especifica la ruta de acceso predeterminada de la página de error personalizada. El tipo de ruta de acceso viene determinado por el atributo defaultResponseMode. Si elige Archivo, se devuelve la ruta del archivo. Si elige el tipo de ruta de acceso ExecuteURL o Redirect, se devuelve la dirección URL de la página de error personalizada. |
||||||||
defaultResponseMode |
Atributo enum opcional. Especifica cómo se devuelve el contenido de errores personalizados. El atributo defaultResponseMode puede tener uno de los siguientes valores posibles; el valor predeterminado es File.
|
||||||||
detailedMoreInformationLink |
Atributo de cadena opcional. Especifica un vínculo, que se muestra en la parte inferior de la página, a una página con información más detallada sobre un error determinado. Puede usar esta propiedad para dirigir a los usuarios finales a una ubicación personalizada para obtener información del error. El estado, el subestado, HRESULT y el identificador de mensaje se envían como parte de la cadena de consulta. El valor predeterminado es https://go.microsoft.com/fwlink/?LinkID=62293. |
||||||||
errorMode |
Atributo enum opcional. Especifica si los errores HTTP están habilitados. El atributo errorMode puede tener uno de los siguientes valores; el valor predeterminado es DetailedLocalOnly.
|
||||||||
existingResponse |
Atributo enum opcional. Especifica lo que ocurre con una respuesta existente cuando el código de estado HTTP es un error, es decir, códigos de respuesta >= 400. El atributo existingResponse puede tener uno de los siguientes valores; el valor predeterminado es Auto.
|
Elementos secundarios
| Elemento | Descripción |
|---|---|
error |
Elemento opcional. Agrega un error HTTP a la colección de errores HTTP. |
remove |
Elemento opcional. Quita una referencia a un error HTTP de la colección de errores HTTP. |
clear |
Elemento opcional. Quita todas las referencias a errores HTTP de la colección de errores HTTP. |
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()