Поделиться через


Ошибки <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 по умолчанию.

Инструкции

Добавление настраиваемой страницы ошибок

  1. Откройте диспетчер служб 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.
  2. В области Подключения разверните имя сервера, узел Сайты, а затем перейдите к веб-сайту или приложению, для которого требуется настроить пользовательские страницы ошибок.

  3. На панели Главная дважды щелкните Страницы ошибок.
    Снимок экрана, на котором показан двойной щелчок страницы ошибок.

  4. В области Действия нажмите кнопку Добавить...

  5. В диалоговом окне Добавление настраиваемой страницы ошибок в разделе Код состояния введите номер кода состояния HTTP, для которого требуется создать пользовательское сообщение об ошибке.
    Снимок экрана: страница

  6. В разделе Действие ответа выполните одно из указанных ниже действий.

    • Выберите Вставить содержимое из статического файла в ответ на ошибку , чтобы предоставить статическое содержимое, например файл .html, для пользовательской ошибки.
    • Выберите Выполнить URL-адрес на этом сайте , чтобы обслуживать динамическое содержимое, например ASP-файл для пользовательской ошибки.
    • Выберите Ответить с перенаправлением 302 , чтобы перенаправить клиентские браузеры на другой URL-адрес, содержащий пользовательский файл ошибки.
  7. В текстовом поле Путь к файлу введите путь к пользовательской странице ошибок, если выбран вариант Вставить содержимое из статического файла в ответ об ошибке , или 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.
Значение Описание
File Обслуживает статическое содержимое, например файл .html для пользовательской ошибки. Если параметр responseMode имеет значение Файл, значением пути должен быть путь к файлу.

Числовое значение равно 0.
ExecuteURL Обслуживает динамическое содержимое, например ASP-файл для пользовательской ошибки. Если параметр responseMode имеет значение ExecuteURL, значение пути должно быть относительным URL-адресом сервера.

Числовое значение равно 1.
Redirect Перенаправляет клиентские браузеры на другой URL-адрес, содержащий пользовательский файл ошибки. Если параметр responseMode имеет значение Redirect, значение пути должно быть абсолютным URL-адресом.

Числовое значение равно 2.
detailedMoreInformationLink Необязательный строковый атрибут.

Указывает ссылку, показанную в нижней части страницы, на страницу с более подробными сведениями о конкретной ошибке. Это свойство можно использовать, чтобы указать конечным пользователям пользовательское расположение для получения сведений об ошибке. Состояние, подсостояние, HRESULT и идентификатор сообщения отправляются как часть строки запроса.

Значение по умолчанию — https://go.microsoft.com/fwlink/?LinkID=62293.
errorMode Необязательный атрибут перечисления.

Указывает, включены ли ошибки HTTP.

Атрибут errorMode может иметь одно из следующих значений: Значение по умолчанию — DetailedLocalOnly.
Значение Описание
DetailedLocalOnly Возвращает подробные сведения об ошибке, если запрос выполняется с локального компьютера, и пользовательское сообщение об ошибке, если запрос отправлен с внешнего компьютера.

Числовое значение равно 0.
Custom Заменяет ошибку, созданную модулем или сервером, указанной пользовательской страницей. Этот режим полезен для предоставления пользователям более понятных сообщений об ошибках.

Примечание. Этот параметр отключает подробные ошибки даже для локальных запросов.

Числовое значение равно 1.
Detailed Отправляет клиенту подробные сведения об ошибке. Этот режим полезен для тестирования и отладки веб-сайтов и приложений.

Числовое значение равно 2.
existingResponse Необязательный атрибут перечисления.

Указывает, что происходит с существующим ответом, если код состояния HTTP является ошибкой, т. е. коды >ответа = 400.

Атрибут existingResponse может иметь одно из следующих значений: Значение по умолчанию — Auto.
Значение Описание
Auto Оставляет ответ нетронутым, только если установлен флаг SetStatus .

Числовое значение равно 0.
Replace Заменяет существующий ответ, даже если установлен флаг SetStatus .

Числовое значение равно 1.
PassThrough Оставляет ответ нетронутым, если существует существующий ответ.

Числовое значение равно 2.

Дочерние элементы

Элемент Описание
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()