エラーの定義と指定Defining and Specifying Faults

SOAP エラーを使用する目的は、エラー状態情報をサービスからクライアントに伝達し、双方向のシナリオでは、相互利用が可能な手段でクライアントからサービスにも伝達することです。SOAP faults convey error condition information from a service to a client and, in the duplex case, from a client to a service in an interoperable way. ここでは、カスタムのエラー コンテンツをいつどのように定義し、そのエラーを返す操作をどのように指定するかについて説明します。This topic discusses when and how to define custom fault content and specify which operations can return them. サービスまたは双方向クライアントがそれらの障害を送信する方法、およびクライアントまたはサービス アプリケーションがこれらの障害を処理する方法の詳細については、「エラーの送受信」を参照してください。For more information about how a service, or duplex client, can send those faults and how a client or service application handles these faults, see Sending and Receiving Faults. Wcf (Windows 通信基盤) アプリケーションでのエラー処理の概要については、「コントラクトとサービスでのエラーの指定と処理」を参照してください。For an overview of error handling in Windows Communication Foundation (WCF) applications, see Specifying and Handling Faults in Contracts and Services.

概要Overview

宣言された SOAP エラーは、カスタム SOAP エラーの種類を指定する System.ServiceModel.FaultContractAttribute を含む操作で発生します。Declared SOAP faults are those in which an operation has a System.ServiceModel.FaultContractAttribute that specifies a custom SOAP fault type. 宣言されていない SOAP エラーとは、操作のコントラクトに指定されていないエラーです。Undeclared SOAP faults are those that are not specified in the contract for an operation. ここでは、各種のエラー状態を特定したうえで、サービスに関するエラー コントラクトを作成する方法について説明します。クライアントは、カスタムの SOAP エラーから通知を受けたときに、これらを使用することでエラーを適切に処理できます。This topic helps you identify those error conditions and create a fault contract for your service that clients can use to properly handle those error conditions when notified by custom SOAP faults. 基本的なタスクは、次の順序で行います。The basic tasks are, in order:

  1. サービスのクライアントに通知する必要があるエラー状態を定義します。Define the error conditions that a client of your service should know about.

  2. そのエラー状態に対して SOAP エラーのカスタム コンテンツを定義します。Define the custom content of the SOAP faults for those error conditions.

  3. 操作でスローされた特定の SOAP エラーがクライアントに公開されるように、WSDL でその操作にマークします。Mark your operations so that the specific SOAP faults that they throw are exposed to clients in WSDL.

クライアントに通知する必要があるエラー状態の定義Defining Error Conditions That Clients Should Know About

SOAP エラーは、特定の操作に関するフォールト情報を伝達するためにパブリックに記述されたメッセージです。SOAP faults are publicly described messages that carry fault information for a particular operation. これらのメッセージは、WSDL で他の操作メッセージと共に記述されているので、クライアントは、操作を呼び出した時点でこのようなエラー処理を予測できます。Because they are described along with other operation messages in WSDL, clients know and, therefore, expect to handle such faults when invoking an operation. しかし、WCF サービスはマネージ コードで記述されているため、マネージ コードのどのエラー条件をエラーに変換してクライアントに返すかを決定すると、サービスのエラー条件とバグを正式なエラーから分離する機会が得られます。クライアントとの会話。But because WCF services are written in managed code, deciding which error conditions in managed code are to be converted into faults and returned to the client provides you the opportunity to separate error conditions and bugs in your service from the formal error conversation you have with a client.

たとえば、次のコード例には、2 つの整数を受け取り、別の整数を返す操作があります。For example, the following code example shows an operation that takes two integers and returns another integer. ここではいくつかの例外がスローされる可能性があります。そのため、エラー コントラクトを設計するときに、クライアントにとって重要なエラー状態を判別する必要があります。Several exceptions can be thrown here, so when designing the fault contract, you must determine which error conditions are important for your client. この場合、サービスでは System.DivideByZeroException 例外を検出する必要があります。In this case, the service should detect the System.DivideByZeroException exception.

[ServiceContract]  
public class CalculatorService  
{  
    [OperationContract]
    int Divide(int a, int b)  
    {  
      if (b==0) throw new Exception("Division by zero!");  
      return a/b;  
    }  
}  
<ServiceContract> _
Public Class CalculatorService
    <OperationContract> _
    Public Function Divide(a As Integer, b As Integer) As Integer
        If b = 0 Then Throw New DivideByZeroException("Division by zero!")
        Return a / b
    End Function
End Class

この例で操作から返せるエラーには、ゼロによる除算に特化したカスタム SOAP エラー、ゼロ除算に特化した情報が算術演算に特化したエラーに含まれているもの、複数の異なるエラー状態に対する複数のエラーなどがあります。SOAP エラーを返さないことも選択できます。In the preceding example the operation can either return a custom SOAP fault that is specific to dividing by zero, a custom fault that is specific to math operations but that contains information specific to dividing by zero, multiple faults for several different error situations, or no SOAP fault at all.

エラー状態のコンテンツの定義Define the Content of Error Conditions

意義のあるカスタム SOAP エラーを返すエラー状態を特定したら、次の手順では、そのエラーのコンテンツを定義し、コンテンツ構造をシリアル化できるようにします。Once an error condition has been identified as one that can usefully return a custom SOAP fault, the next step is to define the contents of that fault and ensure that the content structure can be serialized. 前のセクションのコード例では、Divide 演算に特化したエラーを示していました。しかし、Calculator サービスに他の演算がある場合、1 つのカスタム SOAP エラーで、Divide を含むすべての電卓エラー状態をクライアントに通知することも可能です。The code example in the preceding section shows an error specific to a Divide operation, but if there are other operations on the Calculator service, then a single custom SOAP fault can inform the client of all calculator error conditions, Divide included. 次のコード例では、MathFault を含むすべての算術演算で生成されたエラーを報告するためのカスタム SOAP エラー Divide を作成しています。The following code example shows the creation of a custom SOAP fault, MathFault, which can report errors made using all math operations, including Divide. このクラスでは、操作 (Operation プロパティ) と問題を説明する値 (ProblemType プロパティ) を指定できますが、カスタム SOAP エラーでクライアントに転送するには、クラスとこれらのプロパティがシリアル化可能である必要があります。While the class can specify an operation (the Operation property) and a value that describes the problem (the ProblemType property), the class and these properties must be serializable to be transferred to the client in a custom SOAP fault. このため、System.Runtime.Serialization.DataContractAttribute 属性と System.Runtime.Serialization.DataMemberAttribute 属性を使用して、型とそのプロパティをシリアル化可能にし、できる限り相互運用可能にします。Therefore, the System.Runtime.Serialization.DataContractAttribute and System.Runtime.Serialization.DataMemberAttribute attributes are used to make the type and its properties serializable and as interoperable as possible.

// Define a math fault data contract
[DataContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public class MathFault
{
    private string operation;
    private string problemType;

    [DataMember]
    public string Operation
    {
        get { return operation; }
        set { operation = value; }
    }

    [DataMember]
    public string ProblemType
    {
        get { return problemType; }
        set { problemType = value; }
    }
}
' Define a math fault data contract
<DataContract([Namespace]:="http://Microsoft.ServiceModel.Samples")> _
Public Class MathFault

    Private m_operation As String
    Private m_problemType As String

    <DataMember()> _
    Public Property Operation() As String

        Get

            Return m_operation

        End Get

        Set(ByVal value As String)

            m_operation = value

        End Set

    End Property

    <DataMember()> _
    Public Property ProblemType() As String

        Get

            Return m_problemType

        End Get

        Set(ByVal value As String)

            m_problemType = value

        End Set

    End Property

End Class

データをシリアル化可能にする方法の詳細については、「サービスコントラクトでのデータ転送の指定」を参照してください。For more information about how to ensure your data is serializable, see Specifying Data Transfer in Service Contracts. 提供するシリアル化サポートの一覧については、「データ コントラクト シリアライザーでサポートされる型」を参照してください。 System.Runtime.Serialization.DataContractSerializerFor a list of the serialization support that System.Runtime.Serialization.DataContractSerializer provides, see Types Supported by the Data Contract Serializer.

エラー コントラクトを確立するための操作のマークMark Operations to Establish the Fault Contract

カスタム SOAP エラーの一部として返されるシリアル化可能なデータ構造を定義したら、最後に、その型の SOAP エラーをスローできることを操作コントラクトにマークします。Once a serializable data structure that is returned as part of a custom SOAP fault is defined, the last step is to mark your operation contract as throwing a SOAP fault of that type. これには、System.ServiceModel.FaultContractAttribute 属性を使用して、作成したカスタム データ型の型を渡します。To do this, use the System.ServiceModel.FaultContractAttribute attribute and pass the type of the custom data type that you have constructed. FaultContractAttribute 属性を使用して、Divide 操作で MathFault 型の SOAP エラーを返すように指定する方法を次のコード例に示します。The following code example shows how to use the FaultContractAttribute attribute to specify that the Divide operation can return a SOAP fault of type MathFault. 他の算術に関する操作でも、MathFault を返せるように指定できます。Other math-based operations can now also specify that they can return a MathFault.

[OperationContract]
[FaultContract(typeof(MathFault))]
int Divide(int n1, int n2);
<OperationContract()> _
<FaultContract(GetType(MathFault))> _
Function Divide(ByVal n1 As Integer, ByVal n2 As Integer) As Integer

操作に複数の FaultContractAttribute 属性をマークすることによって、その操作で複数のカスタム エラーを返すことを指定できます。An operation can specify that it returns more than one custom fault by marking that operation with more than one FaultContractAttribute attribute.

次の手順では、操作の実装で障害コントラクトを実装する方法について、トピック「送信および受信障害」で説明します。The next step, to implement the fault contract in your operation implementation, is described in the topic Sending and Receiving Faults.

SOAP、WSDL、相互運用性に関する考慮事項SOAP, WSDL, and Interoperability Considerations

特に他のプラットフォームと相互運用するときなど、状況によっては、SOAP メッセージでエラーを表す方法または WSDL メタデータでエラーを記述する方法を制御することが重要な場合があります。In some circumstances, especially when interoperating with other platforms, it may be important to control the way a fault appears in a SOAP message or the way it is described in the WSDL metadata.

FaultContractAttribute 属性の Name プロパティを使用すると、エラーに対してメタデータで生成される WSDL エラー要素名を制御できます。The FaultContractAttribute attribute has a Name property that allows control of the WSDL fault element name that is generated in the metadata for that fault.

SOAP 標準に従って、エラーには、ActionCode、および Reason を指定することができます。According to the SOAP standard, a fault can have an Action, a Code, and a Reason. Action は、Action プロパティによって制御されます。The Action is controlled by the Action property. Code プロパティと Reason プロパティは、ジェネリック System.ServiceModel.FaultException の親クラスである System.ServiceModel.FaultException<TDetail> クラスのプロパティです。The Code property and Reason property are both properties of the System.ServiceModel.FaultException class, which is the parent class of the generic System.ServiceModel.FaultException<TDetail>. Code プロパティには、SubCode メンバーが含まれています。The Code property includes a SubCode member.

エラーを生成する非サービスを利用する場合には、特定の制限事項があります。When accessing non-services that generate faults, certain limitations exist. WCF は、スキーマが記述し、データ コントラクトと互換性がある詳細な型のエラーのみをサポートします。WCF supports only faults with detail types that the schema describes and that are compatible with data contracts. たとえば、前述のように、WCF は詳細の種類で XML 属性を使用するエラー、または詳細セクションで複数の最上位要素を持つフォールトをサポートしていません。For example, as mentioned above, WCF does not support faults that use XML attributes in their detail types, or faults with more than one top-level element in the detail section.

関連項目See also