HTTP 错误 <httpErrors>
概述
使用 <httpErrors> 元素，你可以为网站或应用程序配置自定义错误消息。 使用自定义错误消息，你可以在网站访问者无法访问所请求的内容时，通过提供文件、返回另一资源或者重定向到某个 URL 来提供友好或者信息更丰富的响应。 例如，你可能想要自定义网站的每个错误消息页面，使其与网站的其他页面外观相同。
<httpErrors> 元素包含一组 <error> 元素，每个元素定义了 IIS 用于响应特定 HTTP 错误的错误消息。 要在 IIS 中添加自定义错误消息，可以将 <error> 元素添加到站点、应用程序或 URL 的 Web.config 文件中的 <httpErrors> 元素中。 每个 <error> 元素都使用 responseMode 属性来指定 IIS 是处理静态内容、动态内容还是重定向到单独的 URL 以响应错误。
如果错误消息集合是你的站点或应用程序从 IIS 配置层次结构中的更高级别继承而来，则可以使用 <remove> 元素从错误消息集合中删除特定的错误消息。 此外，如果 HTTP 错误消息集合是你的站点或应用程序继承继承而来，则可以使用 <clear> 从错误消息集合中移除所有 HTTP 错误消息。
<httpErrors> 元素还包含某些属性，可用于将 IIS 7 配置为处理导致错误的请求。 existingResponse 属性定义当服务器返回 HTTP 错误状态代码时 IIS 7 对现有响应执行的操作。 如果为 <error> 元素中的 responseMode 属性选择指定 File，则 defaultPath 属性定义客户错误页面的路径。
detailedMoreInformationLink 属性指定一个链接，后者可提供有关某个特定错误的详细信息。
<httpErrors> 元素还可以包含 errorMode 属性，可用于控制发生 HTTP 错误时 IIS 返回给浏览器的详细信息级别。 可以将 errorMode 属性设置为 DetailedLocalOnly，这是默认设置，也可以将其设置为 Custom 或 Detailed。 如果指定 DetailedLocalOnly，或者未指定 errorMode 值，IIS 将仅将详细的错误信息返回到本地服务器上的浏览器，向外部计算机上的浏览器返回自定义错误消息。 如果将 errorMode 值设置为 Custom，则 IIS 仅向所有发出请求的浏览器返回自定义错误消息。 如果将 errorMode 值设置为 Detailed，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 | 为 IIS 7.5 中的 <httpErrors> 元素增加了 allowAbsolutePathsWhenDelegated 属性 |
| IIS 7.0 | <httpErrors> 元素是在 IIS 7.0 中引入的。 |
| IIS 6.0 | <httpErrors> 元素取代了 IIsWebService 元数据库对象的 IIS 6.0 HttpErrors 属性。 |
安装
<httpErrors> 元素包含在 IIS 7 的默认安装中。
操作方式
如何添加自定义错误页
打开 Internet Information Services (IIS) 管理器：
如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：
- 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows 8 或 Windows 8.1：
- 按住 Windows 键，按字母 X，然后单击“控制面板”。
- 单击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。
如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：
- 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS)管理器”。
如果使用的是 Windows Vista 或 Windows 7：
- 在任务栏上，单击“开始”，然后单击“控制面板”。
- 双击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。
在“连接”窗格中，展开服务器名称，展开“站点”，然后导航到要为其配置自定义错误页面的网站或应用程序。
在“主页”窗格中，双击“错误页面”。
在“操作”窗格中，单击“添加...”。
在“添加自定义错误页”对话框中的“状态代码”下，键入要为其创建自定义错误消息的 HTTP 状态代码的数量。
在“响应操作”部分中，执行下列操作之一：
- 选择“将静态文件中的内容插入到错误响应”中，以提供自定义错误的静态内容（例如，.html文件）。
- 选择“在此站点上执行 URL”以提供自定义错误的动态内容，例如 .asp 文件。
- 选择“使用 302 重定向进行响应”，以将客户端浏览器重定向到包含自定义错误文件的其他 URL。
如果选择了“将静态文件中的内容插入到错误响应中”，请在“文件路径”文本框中键入自定义错误页的路径；如果选择了“在此站点上执行 URL”或“使用 302 重定向进行响应”，请键入自定义错误页的 URL，然后单击“确定”。
注意
如果选择“在此站点上执行 URL”，则路径必须是相对路径。 如果选择“使用 302 重定向进行响应”，则 URL 必须是绝对 URL。
配置
使用 ApplicationHost.config 文件，可以在服务器级别配置 <httpErrors> 元素，使用相应的 Web.config 文件，则可以在站点和应用程序级别配置。
特性
| 属性 | 说明 | ||||||||
|---|---|---|---|---|---|---|---|---|---|
allowAbsolutePathsWhenDelegated |
可选布尔属性。 如果设置为 true，则委托 <httpErrors> 节时，允许自定义错误页使用绝对路径。 设置为 false 时，则仅允许使用相对于站点根目录的路径。默认值为 false。 |
||||||||
defaultPath |
可选的字符串属性。 指定自定义错误页的默认路径。 路径的类型由 defaultResponseMode 属性确定。 如果选择 File，则返回文件路径。 如果选择 ExecuteURL 或 Redirect 路径类型，则返回自定义错误页的 URL。 |
||||||||
defaultResponseMode |
可选枚举特性。 指定如何返回自定义错误内容。 defaultResponseMode 属性可以是下列可能值之一；默认值为 File。
|
||||||||
detailedMoreInformationLink |
可选的字符串属性。 指定页面底部显示的链接，此链接指向包含有关特定错误的详细信息的页面。 可以使用此属性将最终用户指向一个自定义位置，以便向用户显示错误信息。 状态、子状态、HRESULT 和消息 ID 作为查询字符串的一部分发送。 默认值为 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 配置这些设置时，必须确保将 commit 参数设置为 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()