SOAP エラーは、エラー状態情報をサービスからクライアントに、双方向の場合はクライアントからサービスに相互運用可能な方法で伝えます。 このトピックでは、カスタム 障害コンテンツを定義するタイミングと方法について説明し、それらを返すことができる操作を指定します。 サービスまたは双方向クライアントがこれらの障害を送信する方法と、クライアントまたはサービス アプリケーションがこれらの障害を処理する方法の詳細については、「障害の 送受信」を参照してください。 Windows Communication Foundation (WCF) アプリケーションでのエラー処理の概要については、「 コントラクトとサービスでのエラーの指定と処理」を参照してください。
概要
宣言された SOAP エラーは、操作にカスタム SOAP エラーの種類を指定する System.ServiceModel.FaultContractAttribute があるエラーです。 宣言されていない SOAP エラーは、操作のコントラクトで指定されていないエラーです。 このトピックは、これらのエラー状態を特定し、カスタム SOAP エラーによって通知されたときにクライアントがそれらのエラー状態を適切に処理するために使用できるサービスのエラー コントラクトを作成するのに役立ちます。 基本的なタスクは次のとおりです。
サービスのクライアントが認識する必要があるエラー条件を定義します。
これらのエラー条件の SOAP エラーのカスタム コンテンツを定義します。
操作でスローされた特定の SOAP エラーがクライアントに公開されるように、WSDL でその操作にマークします。
クライアントが認識する必要があるエラー条件の定義
SOAP エラーは、特定の操作のエラー情報を伝達するパブリックに記述されたメッセージです。 これらは WSDL 内の他の操作メッセージと共に記述されるため、クライアントは操作を呼び出すときにこのようなエラーを処理することを認識し、そのため期待します。 ただし、WCF サービスはマネージド コードで記述されるため、マネージド コードでエラーに変換してクライアントに返すエラー条件を決定すると、サービス内のエラー状態とバグを、クライアントとの正式なエラー会話から切り離す機会が得られます。
たとえば、次のコード例は、2 つの整数を受け取り、別の整数を返す操作を示しています。 ここではいくつかの例外がスローされる可能性があります。そのため、エラー コントラクトを設計するときに、クライアントにとって重要なエラー状態を判別する必要があります。 この場合、サービスは System.DivideByZeroException 例外を検出する必要があります。
[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
前の例では、0 で除算することに固有のカスタム SOAP エラー、算術演算に固有のカスタム エラー、0 で除算することに固有の情報、複数の異なるエラー状況の複数のエラー、または SOAP エラーをまったく含まないカスタム SOAP エラーを返すことができます。
エラー条件の内容を定義する
カスタム SOAP エラーを返すことができるエラー条件が特定されたら、次の手順では、そのエラーの内容を定義し、コンテンツ構造をシリアル化できるようにします。 前のセクションのコード例は、 Divide 操作に固有のエラーを示していますが、 Calculator サービスに他の操作がある場合は、1 つのカスタム SOAP エラーによって、すべての電卓エラー状態がクライアントに通知 Divide 含まれます。 次のコード例は、MathFaultを含むすべての算術演算を使用して行われたエラーを報告できるカスタム SOAP エラー (Divide) の作成を示しています。 クラスは操作 ( Operation プロパティ) と問題を説明する値 ( ProblemType プロパティ) を指定できますが、カスタム SOAP エラーでクライアントに転送するには、クラスとこれらのプロパティをシリアル化できる必要があります。 したがって、 System.Runtime.Serialization.DataContractAttribute 属性と System.Runtime.Serialization.DataMemberAttribute 属性を使用して、型とそのプロパティをシリアル化可能にし、可能な限り相互運用できるようにします。
// 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
データがシリアル化可能であることを確認する方法の詳細については、「 サービス コントラクトでのデータ転送の指定」を参照してください。 System.Runtime.Serialization.DataContractSerializerが提供するシリアル化のサポートの一覧については、「データ コントラクト シリアライザーでサポートされる型」を参照してください。
障害契約を確立するための操作をマークする
カスタム SOAP エラーの一部として返されるシリアル化可能なデータ構造が定義されたら、最後の手順では、操作コントラクトをその型の SOAP エラーをスローするものとしてマークします。 これを行うには、 System.ServiceModel.FaultContractAttribute 属性を使用し、構築したカスタム データ型の型を渡します。 次のコード例は、 FaultContractAttribute 属性を使用して、 Divide 操作が MathFault 型の SOAP エラーを返すことができることを指定する方法を示しています。 他の数値演算ベースの操作でも、 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 属性を使用してその操作をマークすることで、複数のカスタム エラーを返すように指定できます。
操作の実装で障害コントラクトを実装する次の手順については、「 エラーの送信と受信」のトピックで説明します。
SOAP、WSDL、相互運用性に関する考慮事項
状況によっては、特に他のプラットフォームと相互運用する場合、SOAP メッセージでのエラーの表示方法や WSDL メタデータでのエラーの記述方法を制御することが重要な場合があります。
FaultContractAttribute属性には、そのエラーのメタデータで生成される WSDL 障害要素名を制御できるName プロパティがあります。
SOAP 標準によると、エラーには Action、 Code、および Reasonがあります。
Actionは、Action プロパティによって制御されます。
Code プロパティと Reason プロパティはどちらも、ジェネリック System.ServiceModel.FaultExceptionの親クラスである System.ServiceModel.FaultException<TDetail> クラスのプロパティです。
Code プロパティには、SubCode メンバーが含まれています。
障害を生成するサービス以外のサービスにアクセスする場合は、特定の制限が存在します。 WCF では、スキーマで記述され、データ コントラクトと互換性のある詳細な型を持つエラーのみがサポートされます。 たとえば、前述のように、WCF では、詳細の種類に XML 属性を使用するエラーや、詳細セクションの最上位要素が複数あるエラーはサポートされていません。