コントラクトおよびサービスのエラーの指定と処理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. さらに、XML 形式でクライアントには、SOAP エラーが表される、ので、WCF アプリケーションのリーチを増やすと、あらゆる SOAP プラットフォーム上のクライアントが使用できる高度に相互運用可能な型システムであります。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.

SOAP エラーの 2 つの型を送信することができます:宣言宣言されていないします。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

操作のエラー条件を識別する、カスタムの SOAP エラーを定義してエラーを返す操作にマークすることは、正常にエラーを WCF アプリケーションでの処理で最初の手順を示します。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.

詳細については、次を参照してください。 Sending and Receiving Faultsします。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. 個別のエラー送信とデバッグ動作プロパティの設定の両方がで説明されているSending and Receiving Faultsします。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 エラーの可能性を想定する必要があります (として WCF クライアントに返されるSystem.ServiceModel.FaultExceptionオブジェクト) を正しくデバッグ情報を取得します。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