コントラクトおよびサービスのエラーの指定と処理Specifying and Handling Faults in Contracts and Services

Windows Communication Foundation (WCF) アプリケーションは、マネージ例外オブジェクトを SOAP エラーオブジェクトに、SOAP エラーオブジェクトをマネージ例外オブジェクトにマップすることによって、エラー状況を処理します。Windows Communication Foundation (WCF) applications handle error situations by mapping managed exception objects to SOAP fault objects and SOAP fault objects to managed exception objects. ここでは、エラー状態がカスタムの SOAP エラーとして公開されるようにコントラクトを設計する方法、そのエラーをサービス実装の一部として返す方法、およびクライアントがそのエラーをキャッチする方法を説明します。The topics in this section discuss how to design contracts to expose error conditions as custom SOAP faults, how to return such faults as part of service implementation, and how clients catch such faults.

エラー処理の概要Error Handling Overview

すべてのマネージド アプリケーションで、操作エラーは Exception オブジェクトにより表されます。In all managed applications, processing errors are represented by Exception objects. WCF アプリケーションなどの SOAP ベースのアプリケーションでは、サービスメソッドは SOAP エラーメッセージを使用して処理エラー情報を通信します。In SOAP-based applications such as WCF applications, service methods communicate processing error information using SOAP fault messages. SOAP エラーは、サービス操作のメタデータに含まれるメッセージ型です。これにより、クライアントが操作を堅牢かつインタラクティブにするために使用できるエラー コントラクトを作成できます。SOAP faults are message types that are included in the metadata for a service operation and therefore create a fault contract that clients can use to make their operation more robust or interactive. さらに、SOAP エラーは XML 形式でクライアントに表現されるので、任意の SOAP プラットフォーム上のクライアントが使用できる、相互運用可能な型システムで、WCF アプリケーションの範囲を広げることができます。In addition, because SOAP faults are expressed to clients in XML form, it is a highly interoperable type system that clients on any SOAP platform can use, increasing the reach of your WCF application.

WCF アプリケーションは両方の種類のエラーシステムで実行されるため、クライアントに送信されるマネージ例外情報は、例外からサービスの SOAP エラーに変換され、送信され、SOAP エラーから WCF クライアントのエラー例外に変換される必要があります。Because WCF applications run under both types of error systems, any managed exception information that is sent to the client must be converted from exceptions into SOAP faults on the service, sent, and converted from SOAP faults to fault exceptions in WCF clients. 双方向クライアントの場合は、クライアント コントラクトによって SOAP エラーがサービスに返送されることもあります。In the case of duplex clients, client contracts can also send SOAP faults back to a service. いずれの場合も、開発者は、既定のサービス例外の動作を使用することも、例外をエラー メッセージにマップするかどうかを制御することも (その場合はどのようにマップするかを指定することも) できます。In either case, you can use the default service exception behaviors, or you can explicitly control whether—and how—exceptions are mapped to fault messages.

2種類の SOAP エラーを送信できます。宣言され、宣言されていません。Two types of SOAP faults can be sent: declared and undeclared. 宣言された SOAP エラーは、カスタム SOAP エラーの種類を指定する System.ServiceModel.FaultContractAttribute 属性を含む操作で発生します。Declared SOAP faults are those in which an operation has a System.ServiceModel.FaultContractAttribute attribute that specifies a custom SOAP fault type. 宣言しないSOAP エラーは、操作のコントラクトで指定されていません。Undeclared SOAP faults are not specified in the contract for an operation.

FaultContractAttribute 属性を使用して、通常の操作中に受信することをクライアントが予期できるすべての SOAP エラーを正式に指定することによって、サービス操作でそのエラーを宣言することを強くお勧めします。It is strongly recommended that service operations declare their faults by using the FaultContractAttribute attribute to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. また、SOAP エラーでは、情報の漏えいを最小限に抑えるために、クライアントが知る必要がある情報だけを返すことをお勧めします。It is also recommended that you return in a SOAP fault only the information that a client must know to minimize information disclosure.

通常、サービス (および双方向クライアント) は、次の手順に従ってエラー処理をアプリケーションに統合します。Typically, services (and duplex clients) take the following steps to successfully integrate error handling into their applications:

  • 例外状態をカスタム SOAP エラーにマップします。Map exception conditions to custom SOAP faults.

  • クライアントとサービスは、SOAP エラーを例外として送受信します。Clients and services send and receive SOAP faults as exceptions.

また、WCF クライアントおよびサービスは、宣言されていない soap エラーをデバッグ目的で使用でき、既定のエラー動作を拡張できます。In addition, WCF clients and services can use undeclared soap faults for debugging purposes and can extend the default error behavior. 以下のセクションで、これらのタスクと概念について説明します。The following sections discuss these tasks and concepts.

SOAP エラーへの例外のマッピングMap Exceptions to SOAP Faults

エラー状態の処理操作を作成するための最初の手順は、クライアント アプリケーションにエラーを通知する状態を決定することです。The first step in creating an operation that handles error conditions is to decide under what conditions a client application should be informed about errors. 一部の操作には、その機能に固有のエラー状態があります。Some operations have error conditions specific to their functionality. たとえば、PurchaseOrder 操作では、発注書の作成が禁止になっている顧客に特定の情報を返すことができます。For example, a PurchaseOrder operation might return specific information to customers who are no longer permitted to initiate a purchase order. また、Calculator サービスなどでは、より一般的な MathFault SOAP エラーを使用してサービス全体のすべてのエラー状態を記述できます。In other cases, such as a Calculator service, a more general MathFault SOAP fault may be able to describe all error conditions across an entire service. サービスのクライアントのエラー状態を特定したら、カスタム SOAP エラーを作成し、エラー状態が発生したときに SOAP エラーを返す操作として、対応する操作をマークします。Once the error conditions of clients of your service are identified, a custom SOAP fault can be constructed and the operation can be marked as returning that SOAP fault when its corresponding error condition arises.

サービスまたはクライアントの開発手順の詳細については、「エラーの定義と指定」を参照してください。For more information about this step of developing your service or client, see Defining and Specifying Faults.

クライアントとサービスによる例外としての SOAP エラーの処理Clients and Services Handle SOAP Faults as Exceptions

WCF アプリケーションでエラー処理を成功させるには、操作エラー条件を特定し、カスタム SOAP エラーを定義し、これらの操作をこれらのエラーを返すようにマークします。Identifying operation error conditions, defining custom SOAP faults, and marking those operations as returning those faults are the first steps in successful error handling in WCF applications. 次の手順では、このエラーの送受信を適切に実装します。The next step is to properly implement the sending and receiving of these faults. 通常は、サービスがエラーを送信してクライアント アプリケーションにエラー状態を通知しますが、双方向クライアントが SOAP エラーをサービスに送信することもできます。Typically services send faults to inform client applications about error conditions, but duplex clients can also send SOAP faults to services.

詳細については、「エラーの送受信」を参照してください。For more information, see Sending and Receiving Faults.

非宣言 SOAP エラーとデバッグUndeclared SOAP Faults and Debugging

宣言 SOAP エラーは、堅牢で相互運用可能な分散アプリケーションを構築するうえで便利です。Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. ただし、サービス (または双方向クライアント) が非宣言 SOAP エラーを送信することが役立つ場合があります。非宣言 SOAP エラーとは、その操作について Web サービス記述言語 (WSDL) で宣言されていないエラーです。However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. たとえば、サービスの開発時に予期しない状況が発生する可能性があります。この場合、デバッグのために情報をクライアントに送信することが役立ちます。For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. また、ServiceBehaviorAttribute.IncludeExceptionDetailInFaults プロパティまたは ServiceDebugBehavior.IncludeExceptionDetailInFaults プロパティを true に設定して、WCF クライアントが内部サービス操作の例外に関する情報を取得できるようにすることもできます。In addition, you can set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults property or the ServiceDebugBehavior.IncludeExceptionDetailInFaults property to true to permit WCF clients to obtain information about internal service operation exceptions. 個々のエラーの送信とデバッグ動作プロパティの設定については、「エラーの送信と受信」を参照してください。Both sending individual faults and setting the debugging behavior properties are described in Sending and Receiving Faults.

重要

マネージ例外によって内部アプリケーション情報が公開される可能性があるため、ServiceBehaviorAttribute.IncludeExceptionDetailInFaults または ServiceDebugBehavior.IncludeExceptionDetailInFaultstrue に設定すると、WCF クライアントは、個人を特定できるなどの内部サービス操作例外に関する情報を取得することができます。機密情報。Because managed exceptions can expose internal application information, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information.

したがって、ServiceBehaviorAttribute.IncludeExceptionDetailInFaults または ServiceDebugBehavior.IncludeExceptionDetailInFaultstrue に設定することは、サービス アプリケーションを一時的にデバッグする方法としてのみお勧めできます。Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is recommended only as a way to temporarily debug a service application. さらに、このようにして未処理のマネージド例外を返すメソッドの WSDL には、FaultException<TDetail> 型の ExceptionDetail のコントラクトが含まれません。In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the FaultException<TDetail> of type ExceptionDetail. クライアントは、デバッグ情報を適切に取得するために、不明な SOAP エラー (System.ServiceModel.FaultException オブジェクトとして WCF クライアントに返される) の可能性を期待する必要があります。Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as System.ServiceModel.FaultException objects) to obtain the debugging information properly.

IErrorHandler によるエラー処理のカスタマイズCustomizing Error Handling with IErrorHandler

アプリケーション レベルの例外が発生した場合にクライアントへの応答メッセージをカスタマイズする、または応答メッセージが返された後に何らかのカスタム処理を実行するという特別な要件がある場合は、System.ServiceModel.Dispatcher.IErrorHandler インターフェイスを実装します。If you have special requirements to either customize the response message to the client when an application-level exception happens or perform some custom processing after the response message is returned, implement the System.ServiceModel.Dispatcher.IErrorHandler interface.

エラーのシリアル化の問題Fault Serialization Issues

WCF では、エラー コントラクトを逆シリアル化する場合、最初に SOAP メッセージのエラー コントラクト名とエラー コントラクトの型を一致させようとします。When deserializing a fault contract, WCF first attempts to match the fault contract name in the SOAP message with the fault contract type. 正しく一致しない場合、使用可能なエラー コントラクトのアルファベット順のリストで互換性のある型を検索します。If it cannot find an exact match it will then search the list of available fault contracts in alphabetical order for a compatible type. 2 つのエラー コントラクトが互換性のある型である場合 (たとえば、一方のコントラクトが別のコントラクトのサブクラスである場合)、エラーを逆シリアル化するときに間違った型が使用される場合があります。If two fault contracts are compatible types (one is a subclass of another, for example) the wrong type may be used to de-serialize the fault. このような問題は、エラー コントラクトで名前、名前空間、およびアクションが指定されていない場合に発生します。This only occurs if the fault contract does not specify a name, namespace, and action. このような問題が発生しないようにするには、常に名前、名前空間、およびアクションの属性を指定して、エラー コントラクトを完全修飾するようにしてください。To prevent this issue from occurring, always fully qualify fault contracts by specifying the name, namespace, and action attributes. また、共有基本クラスから派生した関連エラー コントラクトを定義している場合は、新しいメンバーを [DataMember(IsRequired=true)] でマークしてください。Additionally if you have defined a number of related fault contracts derived from a shared base class, make sure to mark any new members with [DataMember(IsRequired=true)]. この IsRequired 属性の詳細については、「DataMemberAttribute」を参照してください。For more information on this IsRequired attribute see, DataMemberAttribute. この結果、基本クラスに互換性のある型が指定されなくなり、正しい派生型にエラーが逆シリアル化されます。This will prevent a base class from being a compatible type and force the fault to be deserialized into the correct derived type.

参照See also