HTTP エラー <httpErrors>

[アーティクル]
08/25/2009

概要
互換性
セットアップ
方法
構成
サンプルコード

※本ページに挿入されている画像をクリックすると、画像全体が別ウィンドウで表示されます。

概要

<httpErrors> 要素を使用すると、Web サイトまたはアプリケーションにカスタムエラーメッセージを構成することができます。カスタムエラーメッセージを使用すると、サイトの利用者が要求したコンテンツにアクセスできない場合に、ファイルの提供、別のリソースの返送、または URL へのリダイレクトによって、わかりやすい応答や説明的な応答を提供できます。たとえば、Web サイトの各エラーメッセージページをカスタマイズして、そのサイトのその他のページと同じ外観にすることができます。

<httpErrors> 要素には、さまざまな <error> 要素が含まれ、これらの各要素によって、特定の HTTP エラーへの応答に IIS が使用するエラーメッセージが定義されます。サイト、アプリケーション、または URL の Web.config ファイルで <error> 要素を <httpErrors> 要素に追加することにより、カスタムエラーメッセージを IIS に追加できます。各 <error> 要素では、responseMode 属性を使用して、エラーに対して静的コンテンツを提供するか、動的コンテンツを提供するか、または、別の URL にリダイレクトするかどうかを指定します。

<remove> 要素を使用して、サイトまたはアプリケーションが IIS の構成階層構造のより上位レベルから継承しているエラーメッセージのコレクションから特定のエラーメッセージを削除できます。また、<clear> 要素を使用して、サイトまたはアプリケーションが継承する HTTP エラーメッセージのコレクションからすべての HTTP エラーメッセージを削除できます。

さらに、<httpErrors> 要素には、エラーの原因となる要求を処理するように IIS 7.0 を構成する属性が含まれます。existingResponse 属性では、サーバーが HTTP エラー状態コードを返す場合に IIS 7.0 で既存の応答に対して何を行うかについて定義します。defaultPath 属性では、<error> 要素内の responseMode 属性に File を指定することを選択した場合、カスタマーエラーページへのパスを定義します。

detailedMoreInformationLink 属性では、特定のエラーについての詳細情報へのリンクを指定します。

また、<httpErrors> 要素には、HTTP エラーが発生した際に IIS がブラウザーに返す詳細のレベルを制御するために使用できる errorMode 属性も格納されます。errorMode 属性は、DetailedLocalOnly (既定設定)、**Custom、**または Detailed に設定できます。DetailedLocalOnly を指定した場合、または、errorMode 値を指定しなかった場合は、IIS は詳細なエラー情報をローカルサーバーのブラウザーにのみ返し、カスタムエラーメッセージを外部コンピューターのブラウザーに返します。errorMode 値を Custom に設定すると、IIS は、要求しているすべてのブラウザーにカスタムエラーメッセージのみを返します。errorMode 値を Detailed に設定すると、要求しているすべてのブラウザーに詳細なエラー情報を返します。既定の DetailedLocalOnly 値を使用すると、外部ブラウザーに機密情報を公開することなく、ローカルサーバー上で HTTP エラーのトラブルシューティングを実行できます。

IIS は、既定では、%SystemRoot%\Help\IisHelp\Common フォルダーに格納されたファイル内で定義されているエラーメッセージを提供します。ユーザーに表示するカスタムエラーメッセージを作成し、サイト上で特定の HTTP エラーが発生した場合はこのページを返すように IIS を構成することもできます。

互換性

	IIS 7.0	IIS 6.0
注意	`<httpErrors>` は IIS 7.0 で新たに導入された要素です。	`<httpErrors>` 要素は、IIS 6.0 の IIsWebService メタベースオブジェクトの HttpErrors プロパティに代わるものです。

セットアップ

<httpErrors> 要素は、IIS 7.0 の既定のインストールに含まれています。

方法

カスタムエラーページを追加する方法

タスクバーで [スタート] ボタンをクリックし、[管理ツール] をポイントして [インターネットインフォメーションサービス (IIS) マネージャー] をクリックします。
[接続] ウィンドウで当該サーバー名を展開して [サイト] を展開し、カスタムエラーページを構成する Web サイトまたは Web アプリケーションを選択します。
[ホーム] ウィンドウで [エラーページ] をダブルクリックします。
[操作] ウィンドウで [追加] をクリックします。
[カスタムエラーページの追加] ダイアログボックスの [状態コード] の下に、カスタムエラーメッセージを作成する HTTP 状態コードの番号を入力します。
[応答動作] セクションで、次のいずれかを行います。
- カスタムエラーに .html ファイルなどの静的コンテンツを提供する場合は、[静的ファイルのコンテンツをエラー応答に挿入] を選択します。
- カスタムエラーに .asp ファイルなどの動的コンテンツを提供する場合は、[このサイトで URL を実行] を選択します。
- カスタムエラーファイルを持つ別の URL にクライアントブラウザーをリダイレクトする場合は、[302 リダイレクトによる応答] を選択します。
[ファイルパス] テキストボックスで、[静的ファイルのコンテンツをエラー応答に挿入] を選択した場合はカスタムエラーページのパスを入力し、[このサイトで URL を実行] または [302 リダイレクトによる応答] を使用する場合はカスタムエラーページの URL を入力し、[OK] をクリックします。

注 [このサイトで URL を実行] を選択した場合は、パスには相対パスを指定する必要があります。[302 リダイレクトによる応答] を選択した場合は、URL には絶対 URL を指定する必要があります。

構成

サーバーレベルでの <httpErrors> 要素の構成は ApplicationHost.config ファイルで、サイトおよびアプリケーションレベルでの構成は該当する Web.config ファイルで、それぞれ設定できます。

属性

属性	説明
`defaultPath`	オプションの string 属性。カスタムエラーページの既定のパスを指定します。パスの種類は、defaultResponseMode 属性によって決定されます。File を選択した場合、ファイルパスが返されます。ExecuteURL または Redirect のいずれかのパスの種類を選択した場合は、カスタムエラーページの URL が返されます。
`defaultResponseMode`	オプションの enum 属性。カスタムエラーのコンテンツが返される方法を指定します。 defaultResponseMode 属性には、次のいずれかの値を指定できます。既定値は `File` です。 -------------------------------------------------------------------------------------------------- 値: File 説明: カスタムエラーに .html ファイルなどの静的コンテンツを提供します。responseMode が File に設定されている場合、path の値にはファイルパスを指定する必要があります。数値は 0 です。値: ExecuteURL 説明: カスタムエラーに .asp ファイルなどの動的コンテンツを提供します。responseMode が ExecuteURL に設定されている場合、path の値にはサーバーの相対 URL を指定する必要があります。数値は 1 です。値: Redirect 説明: カスタムエラーファイルを持つ別の URL にクライアントブラウザーをリダイレクトします。responseMode が Redirect に設定されている場合、path の値には絶対 URL を指定する必要があります。数値は 2 です。
`detailedMoreInformationLink`	オプションの string 属性。特定のエラーについての詳細情報を持つページへのリンク (ページの下部に表示) を指定します。このプロパティを使用すると、カスタマイズしたエラー情報の場所をエンドユーザーに示すことができます。状態、副状態、HRESULT、およびメッセージ ID がクエリ文字列の一部として送信されます。既定値については、 `https://go.microsoft.com/fwlink/?LinkID=62293` を参照してください。
`errorMode`	オプションの enum 属性。 HTTP エラーを有効にするかどうかを指定します。 errorMode 属性には、次のいずれかの値を指定できます。既定値は `DetailedLocalOnly` です。 -------------------------------------------------------------------------------------------------- 値: DetailedLocalOnly 説明: 要求がローカルコンピューターからの場合は詳細エラー情報を返し、要求が外部コンピューターからの場合はカスタムエラーメッセージを返します。数値は 0 です。値: Custom 説明: モジュールまたはサーバーが生成するエラーを、指定するカスタムページで置き換えます。このモードは、エンドユーザーに扱いやすいエラーメッセージを提供するのに役立ちます。注 : この設定では、ローカルな要求に対してさえ、詳細エラーをオフにします。数値は 1 です。値: Detailed 説明: 詳細エラー情報をクライアントに返信します。このモードは、Web サイトとアプリケーションをテストおよびデバッグするのに役に立ちます。数値は 2 です。
`existingResponse`	オプションの enum 属性。 HTTP 状態コードがエラー、つまり応答コードが 400 以上の場合に、既存の応答をどうするかを指定します。 --------------------------------------------------------------------------------------------------------- 値: Auto 説明: SetStatus フラグが設定されている場合のみ、応答をそのままにしておきます。数値は 0 です。値: Replace 説明: SetStatus フラグが設定されている場合でも、既存の応答を置き換えます。数値は 1 です。値: PassThrough 説明: 既存の応答が存在する場合、応答をそのままにしておきます。数値は 2 です。

子要素

要素	説明
`error`	オプションの要素。 HTTP エラーのコレクションに HTTP エラーを追加します。
`remove`	オプションの要素。 HTTP エラーコレクションから 1 つの HTTP エラーに対する参照を削除します。
`clear`	オプションの要素。 HTTP エラーコレクションから HTTP エラーに対するすべての参照を削除します。

構成サンプル

次の構成例が Web サイトまたは Web アプリケーションの Web.config ファイルに組み込まれると、errorMode 属性を使用して、詳細なエラーメッセージがローカルコンピューターのみに表示されるようになります。また、defaultResponseMode 属性を使用して、サイトまたはアプリケーションの応答モードが設定されます。次に、状態コード 500 の継承されたエラーメッセージが削除されます。さらに、IIS で新しいカスタムエラーページが検索されるディレクトリが prefixLanguageFilePath 属性に指定され、カスタムエラーメッセージを含む 500.htm ファイルが path 属性に指定されます。

<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 のすべてのエラーに対して新しいファイルが追加されます。これは、"URL シーケンスが拒否されました" として IIS で返されるエラーです。この例では、プレフィックスパスが "%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

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()

次の方法で共有

HTTP エラー <httpErrors>

概要

互換性

セットアップ

方法

カスタムエラーページを追加する方法

構成

属性

子要素

構成サンプル

サンプルコード

AppCmd.exe

C#

VB.NET

JavaScript

VBScript

その他のリソース

次の方法で共有

HTTP エラー <httpErrors>

概要

互換性

セットアップ

方法

カスタム エラー ページを追加する方法

構成

属性

子要素

構成サンプル

サンプル コード

AppCmd.exe

C#

VB.NET

JavaScript

VBScript

その他のリソース

カスタムエラーページを追加する方法

サンプルコード