HTTP 錯誤 < HTTPErrors>

  • 發行項

概觀

元素 <httpErrors> 可讓您為網站或應用程式設定自訂錯誤訊息。 自訂錯誤訊息可讓您透過服務檔案、傳回其他資源，或是在站台造訪者無法存取要求的內容時重新導向至 URL 的方式，提供易讀或含有更多資訊的回應。 例如，您可能想要自訂網站的每一個錯誤訊息網頁，以便提供與站台上其他部分相同的外觀及操作。

元素 <httpErrors> 包含專案的集合 <error> ，每個元素都會定義 IIS 用來回應特定 HTTP 錯誤的錯誤訊息。 您可以將元素新增至網站、應用程式或 URL 的 Web.config 檔案中的 元素，以將自訂錯誤訊息新增 <error> 至 <httpErrors> IIS。 每個 <error> 元素都會使用 responseMode 屬性來指定 IIS 是否提供靜態內容、動態內容，或重新導向至個別 URL 以回應錯誤。

您可以使用 <remove> 元素，從月臺或應用程式繼承自 IIS 組態階層中較高層級的錯誤訊息集合中移除特定的錯誤訊息。 此外，您也可以使用 <clear> 元素，從月臺或應用程式繼承的 HTTP 錯誤訊息集合中移除所有 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 值設定為 [詳細]，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 在 IIS 8.0 中未修改專案 <httpErrors> 。
IIS 7.5 屬性 allowAbsolutePathsWhenDelegated 已新增至 <httpErrors> IIS 7.5 中的 專案
IIS 7.0 專案 <httpErrors> 是在 IIS 7.0 中引進的。
IIS 6.0 元素 <httpErrors> 會取代IIsWebService中繼基底物件的 IIS 6.0 HttpErrors屬性。

安裝程式

專案 <httpErrors> 包含在 IIS 7 的預設安裝中。

作法

如何新增自訂錯誤頁面

  1. (IIS) 管理員開啟 Internet Information Services：

    • 如果您使用 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. 在 [ 首頁] 窗格中，按兩下 [錯誤頁面]。
    顯示按兩下 [錯誤頁面] 的螢幕擷取畫面。

  4. 在 [ 動作] 窗格中，按一下 [ 新增...

  5. 在 [ 新增自訂錯誤頁面] 對話方塊的 [ 狀態碼] 底下，輸入您要建立自訂錯誤訊息的 HTTP 狀態碼數目。
    顯示 [新增自訂錯誤頁面] 的螢幕擷取畫面。

  6. 在 [ 回應動作] 區段中，執行下列其中一項動作：

    • 針對自訂錯誤，選取 [將靜態檔案的內容插入錯誤回應 中，以提供靜態內容，例如.html檔案。
    • 選取 [在此網站上執行 URL ] 來提供動態內容，例如自訂錯誤的 .asp 檔案。
    • 選取 [使用 302 重新導向回應 ]，將用戶端瀏覽器重新導向至包含自訂錯誤檔案的不同 URL。

  7. 在 [ 檔案路徑 ] 文字方塊中，如果您選擇 [ 將靜態檔案的內容插入至錯誤回應 ] 或自訂錯誤頁面的 URL，請輸入自訂錯誤頁面的路徑，如果您使用 此網站上的 [執行 URL ] 或 [ 回應 302 重新導向]，然後按一下 [ 確定]。

    注意

    如果您選取 [在此網站上執行 URL]，則路徑必須是相對路徑。 如果您選取 [使用 302 重新導向回應]，則 URL 必須是絕對 URL。

組態

您可以在 <httpErrors> ApplicationHost.config檔案中的伺服器層級，以及在適當Web.config檔案的月臺和應用層級設定專案。

屬性

屬性 描述
allowAbsolutePathsWhenDelegated 選擇性的 Boolean 屬性。

當設定為 true時，委派區段時 <httpErrors> ，允許自訂錯誤頁面的絕對路徑。 當設定為 false時，只允許相對於網站根目錄的路徑。

預設值是 false。
defaultPath 選擇性字串屬性。

指定自訂錯誤頁面的預設路徑。 路徑的類型取決於 defaultResponseMode 屬性。 如果您選擇 [ 檔案]，則會傳回檔案路徑。 如果您選擇 ExecuteURL 或 重新 導向路徑類型，則會傳回自訂錯誤頁面的 URL。
defaultResponseMode 選擇性列舉屬性。

指定如何傳回自訂錯誤內容。

defaultResponseMode屬性可以是下列其中一個可能的值;預設值為 File 。
值 描述
File 例如，提供靜態內容，例如自訂錯誤的.html檔案。 如果 responseMode 設定為 File，路徑值必須是檔案路徑。

數值為 0 。
ExecuteURL 提供動態內容，例如自訂錯誤的 .asp 檔案。 如果 responseMode 設定為 ExecuteURL，路徑值必須是伺服器相對 URL。

數值為 1 。
Redirect 將用戶端瀏覽器重新導向至包含自訂錯誤檔案的不同 URL。 如果 responseMode 設定為 [重新導向]，路徑值必須是絕對 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 應該搜尋新自訂錯誤頁面的目錄，並將 路徑 屬性設定為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()