Ошибки <HTTP httpErrors>
Общие сведения
Элемент <httpErrors> позволяет настраивать пользовательские сообщения об ошибках для веб-сайта или приложения. Настраиваемые сообщения об ошибках обеспечивают более понятную или информативную обратную связь путем предоставления файла, возвращения другого ресурса или перенаправления на другой URL-адрес, если посетители сайта не могут получить доступ к запрошенному содержимому. Например, можно настроить каждую страницу сообщений об ошибках для веб-сайта в соответствии с оформлением остальных компонентов сайта.
Элемент <httpErrors> содержит коллекцию <error> элементов, каждый из которых определяет сообщение об ошибке, которое IIS использует для реагирования на определенные ошибки HTTP. Вы можете добавить пользовательские сообщения об ошибках в IIS, добавив <error> элемент <httpErrors> в элемент в файле Web.config для сайта, приложения или URL-адреса. Каждый <error> элемент использует атрибут responseMode , чтобы указать, обслуживает ли IIS статическое содержимое, динамическое содержимое или перенаправляет на отдельный URL-адрес в ответ на ошибку.
Элемент можно использовать для <remove> удаления определенного сообщения об ошибке из коллекции сообщений об ошибках, наследуемых сайтом или приложением от более высокого уровня в иерархии конфигурации IIS. Кроме того, элемент можно использовать для <clear> удаления всех сообщений об ошибках HTTP из коллекции сообщений об ошибках HTTP, наследуемых сайтом или приложением.
Элемент <httpErrors> также содержит атрибуты, которые настраивают IIS 7 для обработки запросов, вызывающих ошибки. Атрибут existingResponse определяет, что iis 7 делает с существующим ответом, когда сервер возвращает код состояния ошибки HTTP. Атрибут defaultPath определяет путь к странице ошибки клиента, если выбран параметр указать Файл для атрибута responseMode в элементе <error> .
Атрибут detailedMoreInformationLink указывает ссылку на дополнительные сведения о конкретной ошибке.
Элемент <httpErrors> также может содержать атрибут errorMode , который можно использовать для управления уровнем детализации, возвращаемой iis в браузер при возникновении ошибки HTTP. Для атрибута errorMode можно задать значение DetailedLocalOnly, которое является параметром по умолчанию, или задать для него значение Custom или Detailed. Если указать DetailedLocalOnly или не указать значение errorMode , IIS возвращает подробные сведения об ошибке только в браузер на локальном сервере, а пользовательское сообщение об ошибке — в браузер на внешнем компьютере. Если для параметра errorMode задано значение Custom, службы IIS возвращают только пользовательские сообщения об ошибках для всех запрашивающих браузеров. Если для параметра errorMode задано значение Подробно, службы IIS возвращают подробные сведения об ошибке всем запрашивающим браузерам. Значение по умолчанию DetailedLocalOnly позволяет устранять ошибки HTTP на локальном сервере, не предоставляя конфиденциальные сведения внешним браузерам.
По умолчанию IIS обслуживает сообщения об ошибках, определенные в файлах, хранящихся в папке %SystemRoot%\Help\IisHelp\Common. Вы можете создать пользовательское сообщение об ошибке для пользователей и настроить IIS для возврата этой страницы всякий раз, когда на сайте возникает определенная ошибка HTTP.
Совместимость
| Версия | Примечания |
|---|---|
| IIS 10.0 | Элемент <httpErrors> не был изменен в IIS 10.0. |
| IIS 8,5 | Элемент <httpErrors> не был изменен в IIS 8.5. |
| IIS 8,0 | Элемент <httpErrors> не был изменен в IIS 8.0. |
| IIS 7,5 | Атрибут allowAbsolutePathsWhenDelegated был добавлен в элемент в <httpErrors> IIS 7.5 |
| IIS 7.0 | Элемент <httpErrors> появился в IIS 7.0. |
| IIS 6,0 | Элемент <httpErrors> заменяет свойство IIS 6.0 HttpErrors объекта метабазы IIsWebService . |
Настройка
Элемент <httpErrors> включен в установку iis 7 по умолчанию.
Инструкции
Добавление настраиваемой страницы ошибок
Откройте диспетчер служб IIS:
Если вы используете Windows Server 2012 или Windows Server 2012 R2:
- На панели задач щелкните диспетчер сервера, выберите Сервис, а затем диспетчер служб IIS.
Если вы используете Windows 8 или Windows 8.1:
- Удерживая нажатой клавишу Windows, нажмите букву X и щелкните панель управления.
- Щелкните Администрирование, а затем дважды щелкните Диспетчер служб IIS.
Если вы используете Windows Server 2008 или Windows Server 2008 R2:
- На панели задач нажмите кнопку Пуск, наведите указатель на пункт Администрирование, а затем выберите Пункт Диспетчер служб IIS.
Если вы используете Windows Vista или Windows 7:
- На панели задач нажмите кнопку Пуск, а затем панель управления.
- Дважды щелкните Администрирование, а затем дважды щелкните Диспетчер служб IIS.
В области Подключения разверните имя сервера, узел Сайты, а затем перейдите к веб-сайту или приложению, для которого требуется настроить пользовательские страницы ошибок.
На панели Главная дважды щелкните Страницы ошибок.
В области Действия нажмите кнопку Добавить...
В диалоговом окне Добавление настраиваемой страницы ошибок в разделе Код состояния введите номер кода состояния HTTP, для которого требуется создать пользовательское сообщение об ошибке.
В разделе Действие ответа выполните одно из указанных ниже действий.
- Выберите Вставить содержимое из статического файла в ответ на ошибку , чтобы предоставить статическое содержимое, например файл .html, для пользовательской ошибки.
- Выберите Выполнить URL-адрес на этом сайте , чтобы обслуживать динамическое содержимое, например ASP-файл для пользовательской ошибки.
- Выберите Ответить с перенаправлением 302 , чтобы перенаправить клиентские браузеры на другой URL-адрес, содержащий пользовательский файл ошибки.
В текстовом поле Путь к файлу введите путь к пользовательской странице ошибок, если выбран вариант Вставить содержимое из статического файла в ответ об ошибке , или URL-адрес настраиваемой страницы ошибки, если вы используете параметр Выполнить URL-адрес на этом сайте или Ответить с перенаправлением 302, а затем нажмите кнопку ОК.
Примечание
При выборе параметра Выполнить URL-адрес на этом сайте путь должен быть относительным. Если выбрать Ответить с перенаправлением 302, URL-адрес должен быть абсолютным.
Конфигурация
Элемент можно настроить <httpErrors> на уровне сервера в файле ApplicationHost.config и на уровне сайта и приложения в соответствующем Web.config файле.
Атрибуты
| Атрибут | Описание | ||||||||
|---|---|---|---|---|---|---|---|---|---|
allowAbsolutePathsWhenDelegated |
Дополнительный логический атрибут. Если задано значение true, абсолютные пути разрешены для пользовательских страниц ошибок при делегировании <httpErrors> раздела. Если задано значение false, допускаются только пути, относящиеся к корню сайта.Значение по умолчанию — false. |
||||||||
defaultPath |
Необязательный строковый атрибут. Указывает путь по умолчанию к пользовательской странице ошибок. Тип пути определяется атрибутом defaultResponseMode . Если выбрать Файл, возвращается путь к файлу. При выборе типа ExecuteURL или Redirect path возвращается URL-адрес настраиваемой страницы ошибки. |
||||||||
defaultResponseMode |
Необязательный атрибут перечисления. Указывает, как возвращается пользовательское содержимое ошибки. Атрибут defaultResponseMode может быть одним из следующих возможных значений. Значение по умолчанию — File.
|
||||||||
detailedMoreInformationLink |
Необязательный строковый атрибут. Указывает ссылку, показанную в нижней части страницы, на страницу с более подробными сведениями о конкретной ошибке. Это свойство можно использовать, чтобы указать конечным пользователям пользовательское расположение для получения сведений об ошибке. Состояние, подсостояние, HRESULT и идентификатор сообщения отправляются как часть строки запроса. Значение по умолчанию — https://go.microsoft.com/fwlink/?LinkID=62293. |
||||||||
errorMode |
Необязательный атрибут перечисления. Указывает, включены ли ошибки HTTP. Атрибут errorMode может иметь одно из следующих значений: Значение по умолчанию — DetailedLocalOnly.
|
||||||||
existingResponse |
Необязательный атрибут перечисления. Указывает, что происходит с существующим ответом, если код состояния HTTP является ошибкой, т. е. коды >ответа = 400. Атрибут existingResponse может иметь одно из следующих значений: Значение по умолчанию — Auto.
|
Дочерние элементы
| Элемент | Описание |
|---|---|
error |
Необязательный элемент. Добавляет ошибку HTTP в коллекцию ошибок HTTP. |
remove |
Необязательный элемент. Удаляет ссылку на ошибку HTTP из коллекции ошибок HTTP. |
clear |
Необязательный элемент. Удаляет все ссылки на ошибки HTTP из коллекции ошибок HTTP. |
Образец конфигурации
В следующем примере конфигурации, включенном в файл Web.config для веб-сайта или приложения, атрибут errorMode используется для отображения на локальном компьютере только подробных сообщений об ошибках. Он также использует атрибут defaultResponseMode , чтобы задать режим ответа для сайта или приложения. Затем пример удаляет наследуемое сообщение об ошибке для кода состояния 500. Затем он задает атрибут prefixLanguageFilePath для каталога, в котором IIS должны выполнять поиск новой настраиваемой страницы ошибок, и задает атрибуту path значение 500.htm, файл, содержащий пользовательское сообщение об ошибке.
<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>
Пример кода
В следующих примерах добавляется новый файл для всех ошибок с кодом состояния 404 с подсостояние 5, которое IIS возвращает для ошибок "Отказано в последовательности URL-адресов". В этих примерах путь префикса имеет значение "%SystemDrive%\inetpub\custerr", а имя файла указывается как "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
Примечание
При использовании AppCmd.exe для настройки этих параметров для параметра apphostфиксации необходимо задать значение . Это зафиксирует параметры конфигурации в соответствующем разделе расположения в файле 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()