添加 HTTP 错误 <error>

  • 项目

概述

<httpErrors> 集合的 <error> 元素向 HTTP 错误集合添加唯一错误映射。

兼容性

版本 说明
IIS 10.0 <error> 元素在 IIS 10.0 中未进行修改。
IIS 8.5 <error> 元素在 IIS 8.5 中未进行修改。
IIS 8.0 <error> 元素在 IIS 8.0 中未进行修改。
IIS 7.5 <error> 元素在 IIS 7.5 中未进行修改。
IIS 7.0 IIS 7.0 中引入了 <httpErrors> 集合的 <error> 元素。
IIS 6.0 <httpErrors> 集合取代了 IIsWebService 元数据库对象的 IIS 6.0 HttpErrors 部分。

安装

在 IIS 7 的默认安装中包含 <httpErrors> 集合的 <error> 元素。

操作方式

如何添加自定义错误页

  1. 打开 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) 管理器”。

  2. 在“连接”窗格中，展开服务器名称，展开“站点”，然后导航到要为其配置自定义错误页面的网站或应用程序。

  3. 在“主页”窗格中，双击“错误页面”。
    Screenshot of the Home pane with the Error Pages option being highlighted.

  4. 在“操作”窗格中，单击“添加...”。

  5. 在“添加自定义错误页”对话框中的“状态代码”下，键入要为其创建自定义错误消息的 HTTP 状态代码的数量。
    Screenshot of the Add Custom Error Page dialog box, showing the Status code field.

  6. 在“响应操作”部分中，执行下列操作之一：

    • 选择“将静态文件中的内容插入到错误响应”中，以提供自定义错误的静态内容（例如，.html文件）。
    • 选择“在此站点上执行 URL”以提供自定义错误的动态内容，例如 .asp 文件。
    • 选择“使用 302 重定向进行响应”，以将客户端浏览器重定向到包含自定义错误文件的其他 URL。

  7. 如果选择了“将静态文件中的内容插入到错误响应中”，请在“文件路径”文本框中键入自定义错误页的路径；如果选择了“在此站点上执行 URL”或“使用 302 重定向进行响应”，请键入自定义错误页的 URL，然后单击“确定”。

    注意

    如果选择“在此站点上执行 URL”，则路径必须是相对路径。 如果选择“使用 302 重定向进行响应”，则 URL 必须是绝对 URL。

    注意

    无法自定义以下 HTTP 错误：400、403.9、411、414、500、500.11、500.14、500.15、501、503 和 505。

配置

特性

属性 说明
path 必需的字符串属性。

指定在响应由 statusCode 和 subStatusCode 属性指定的 HTTP 错误时提供的文件路径或 URL。 如果选择文件响应模式，请指定自定义错误页的路径。 如果选择 ExecuteURL 响应模式，则路径必须是服务器相对 URL（例如 /404.htm）。 如果选择 Redirect 响应模式，则必须输入绝对 URL（例如，www.contoso.com/404.htm）。
prefixLanguageFilePath 可选的字符串属性。

为自定义错误生成路径时指定初始路径段。 此段显示在自定义错误路径的语言特定部分之前。 例如，在路径 C:\Inetpub\Custerr\en-us\404.htm 中，C:\Inetpub\Custerr 是 prefixLanguageFilePath。
responseMode 可选的枚举属性。

指定如何返回自定义错误内容。

responseMode 属性可以是以下可能值之一。 默认为 File。
值 说明
File 提供自定义错误的静态内容，例如 .html 文件。

如果 responseMode 设置为 File，则路径属性值必须是文件路径。

数值为 0。
ExecuteURL 提供自定义错误的路径属性中指定的动态内容（例如，.asp文件）。

如果 responseMode 设置为 ExecuteURL，则路径值必须是服务器相对 URL。

数值为 1。
Redirect 将客户端浏览器重定向到路径属性中指定的 URL，其中包含自定义错误文件。

如果 responseMode 设置为 Redirect，则路径值必须是绝对 URL。

数值为 2。
statusCode 必需 uint 属性。

指定要为其创建自定义错误消息的 HTTP 状态代码的数目。 可接受 400 到 999 范围内的值。
subStatusCode 可选 int 属性。

指定要为其创建自定义错误消息的 HTTP 状态代码的数目。 可接受 -1 到 999 范围内的值。

默认值为 -1。

子元素

无。

配置示例

以下配置示例（如果包含在网站或应用程序的 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()