System.ServiceModel 名前空間


.NET Framework クラス ライブラリ
FaultContractAttribute クラス

更新 : 2007 年 11 月

サービス操作で処理エラーが発生したときに返される 1 つ以上の SOAP エラーを指定します。

名前空間 :  System.ServiceModel
アセンブリ :  System.ServiceModel (System.ServiceModel.dll 内)
構文

Visual Basic (宣言)
<AttributeUsageAttribute(AttributeTargets.Method, AllowMultiple := True, Inherited := False)> _
Public NotInheritable Class FaultContractAttribute _
    Inherits Attribute
Visual Basic (使用法)
Dim instance As FaultContractAttribute
C#
[AttributeUsageAttribute(AttributeTargets.Method, AllowMultiple = true, Inherited = false)]
public sealed class FaultContractAttribute : Attribute
Visual C++
[AttributeUsageAttribute(AttributeTargets::Method, AllowMultiple = true, Inherited = false)]
public ref class FaultContractAttribute sealed : public Attribute
J#
/** @attribute AttributeUsageAttribute(AttributeTargets.Method, AllowMultiple = true, Inherited = false) */
public final class FaultContractAttribute extends Attribute
JScript
public final class FaultContractAttribute extends Attribute
解説

Web サービス記述言語 (WSDL) のサービス操作の説明に追加される 1 つ以上の特定の例外条件を、操作によって返される明示的な SOAP エラー メッセージとして宣言する FaultContractAttribute 属性を使用して、操作にマークを付けます。

すべてのマネージ アプリケーションで、操作エラーは Exception オブジェクトにより表されます。Windows Communication Foundation (WCF) アプリケーションなどの SOAP に基づくアプリケーションでは、サービス メソッドは SOAP エラー メッセージを使用して操作エラー情報を通知します。WCF アプリケーションは、両方の型のエラー システムで実行されるため、クライアントに送信する必要があるマネージ例外情報は、例外から SOAP エラーに変換される必要があります。既定のサービス例外動作を使用できます。または、例外をエラー メッセージにマッピングするかどうかとそのマッピング方法を明示的に制御できます。WCF アプリケーションでの例外と SOAP エラーの概要については、「コントラクトおよびサービスのエラーの指定と処理」を参照してください。

FaultContractAttribute を使用して、通常の操作中に受信することをクライアントが想定できるすべての SOAP エラーを正式に指定することをお勧めします。また、SOAP エラーでは、情報の開示を最小限に抑えるために、クライアントが知る必要がある情報だけを返すことをお勧めします。

  • Action プロパティは、エラー メッセージのアクションを制御します。

  • DetailType プロパティは、エラー メッセージ内にシリアル化された詳細オブジェクトの型を取得します。

  • Name プロパティと Namespace プロパティは、それぞれ、エラー メッセージの名前と名前空間を制御します。

  • HasProtectionLevel は、エラー メッセージに保護レベルが指定されるかどうかを示します。指定される場合は、ProtectionLevel プロパティがその保護レベルを制御します。

ms576187.alert_caution(ja-jp,VS.90).gif注意 :

エラー メッセージの情報でその機密性が高い場合、またはセキュリティの問題につながる可能性がある場合は、ProtectionLevel プロパティを設定することを強くお勧めします。

  • ProtectionLevelProtectionLevel..::.Sign または ProtectionLevel..::.EncryptAndSign のいずれかに明示的に設定する場合は、System.ServiceModel..::.SecurityMode プロパティによってセキュリティを有効にしたバインドを使用する必要があります。使用しない場合は、例外がスローされます。

  • セキュリティを有効にしたバインドを選択し、コントラクト上のどこにも ProtectionLevel プロパティを設定しない場合は、すべてのアプリケーション データが暗号化および署名されます。

  • セキュリティを無効にしたバインド (たとえば、System.ServiceModel..::.BasicHttpBinding は既定でセキュリティが無効に設定されています) を選択し、ProtectionLevel を明示的に設定しない場合は、すべてのアプリケーション データが保護されません。

ほとんどの場合、エラー メッセージでは、ProtectionLevelEncryptAndSign に設定すれば十分です。詳細については、「保護レベルの理解」を参照してください。

指定したエラーを FaultContractAttribute でマークした操作から返すには、操作中にマネージ例外が発生したときに、FaultException<(Of <(TDetail>)>) をスローします (型パラメータは、シリアル化可能なエラー情報です)。WCF クライアント アプリケーションは、SOAP エラーの型を、クライアントの実装でスローされたのと同じ型、つまり FaultException<(Of <(TDetail>)>) として処理します (型パラメータは、シリアル化可能なエラー情報です)。FaultContractAttribute は、双方向サービス操作と非同期操作のペアで発生する SOAP エラーを指定する場合のみ使用できます。一方向操作では SOAP エラーはサポートされないため、FaultContractAttribute もサポートされません。

ms576187.alert_note(ja-jp,VS.90).gifメモ :

エラー情報を伝えるために、任意のシリアル化可能な型を使用できます。このバージョンの WCF での唯一の制約は、FaultContractAttribute に指定する型は、System.Runtime.Serialization..::.DataContractSerializer によってシリアル化可能である必要があるということです。DataContractSerializer で提供されるシリアル化のサポートについては、「データ コントラクト シリアライザ」を参照してください。

たとえば、クライアントが Int32 を含む SOAP エラーの受信を想定できるように指定するには、サービス メソッドの FaultContractAttribute に型パラメータを配置します。

ms576187.alert_note(ja-jp,VS.90).gifメモ :

次のコード例では、ProtectionLevel プロパティ、Name プロパティ、および Namespace プロパティのいずれも設定しません。

Visual Basic
  <OperationContractAttribute(), FaultContractAttribute(GetType(Integer))> _
    Function Divide(ByVal arg1 As Integer, ByVal arg2 As Integer) As Integer
End Interface 'FCADemonstration
C#
[OperationContractAttribute]
[FaultContractAttribute(typeof(int))]
int Divide(int arg1, int arg2);

その後、サービス メソッドの中で、型パラメータがエラー情報を格納する型 (先に説明した例の場合は Int32) である新しい FaultException<(Of <(TDetail>)>) をスローします。例 :

Visual Basic
Throw New FaultException(Of Integer)(4)
C#
throw new FaultException<int>(4);

上の例は非常に基本的な形であり、System..::.Int32 コードを使用してあらゆる情報を渡すことができます。したがって、この詳細型は最も有効な型ではありません。通常、WCF アプリケーションでは、クライアントのエラー情報要件に固有の詳細型を使用して SOAP エラーを指定します。より完全な例については、「使用例」のセクションを参照してください。

ms576187.alert_note(ja-jp,VS.90).gifメモ :

型パラメータが System..::.String である FaultException<(Of <(TDetail>)>) を指定した場合、クライアント アプリケーションでは文字列値に Detail プロパティが割り当てられ、クライアントは FaultException<(Of <(TDetail>)>)..::.ToString メソッドを呼び出しても、その文字列を取得できません。クライアント アプリケーションが Exception..::.ToString を呼び出したときにこの文字列値を返すには、操作内で System.ServiceModel..::.FaultException 例外をスローし、この文字列をコンストラクタに渡します。

例外または FaultException<(Of <(TDetail>)>) がスローされるときのアプリケーションの動作を明示的に制御するには、System.ServiceModel.Description..::.IServiceBehaviorSystem.ServiceModel.Description..::.IContractBehavior、または System.ServiceModel.Description..::.IEndpointBehaviorSystem.ServiceModel.Dispatcher..::.IErrorHandler インターフェイスを実装し、これを ChannelDispatcherErrorhandlers()()() プロパティに割り当てます。IErrorHandler は、生成される SOAP エラーと、生成された SOAP エラーをクライアントに送信するかどうかを明示的に制御できるようにします。

デバッグを容易にするには、コード内で ServiceBehaviorAttribute..::.IncludeExceptionDetailInFaultstrue に設定します。または、アプリケーション構成ファイルの中で ServiceDebugBehavior..::.IncludeExceptionDetailInFaults を使用できます。有効な場合は、サービスが自動的に例外情報を呼び出し元に返します。これらのエラーは、FaultException 例外としてクライアントに表示されます。

ms576187.alert_caution(ja-jp,VS.90).gif重要 :

マネージ例外が内部アプリケーション情報を開示する可能性があるので、ServiceBehaviorAttribute..::.IncludeExceptionDetailInFaults または ServiceDebugBehavior..::.IncludeExceptionDetailInFaultstrue に設定すると、個人の身元を確認できる情報またはその他の機密情報を含む内部サービス操作例外に関する情報を WCF クライアントで取得できます。

したがって、ServiceBehaviorAttribute..::.IncludeExceptionDetailInFaults または ServiceDebugBehavior..::.IncludeExceptionDetailInFaultstrue に設定することは、サービス アプリケーションを一時的にデバッグする方法としてのみお勧めできます。さらに、このようにして未処理のマネージ例外を返すメソッドの WSDL には、String 型の FaultException<(Of <(TDetail>)>) のコントラクトが含まれません。クライアントは、デバッグ情報を適切に取得するために、(System.ServiceModel..::.FaultException オブジェクトとして WCF クライアントに返される) 不明な SOAP エラーの可能性について想定しておく必要があります。


次のコード例は、SampleMethod 操作で GreetingFault の詳細な型と共に SOAP エラーを返すことができることを指定するために、FaultContractAttribute を使用しています。

C#
using System;
using System.Collections.Generic;
using System.Net.Security;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.Text;

namespace Microsoft.WCF.Documentation
{
  [ServiceContract(Namespace="http://microsoft.wcf.documentation")]
  public interface ISampleService{
    [OperationContract]
    [FaultContractAttribute(
      typeof(GreetingFault),
      Action="http://www.contoso.com/GreetingFault",
      ProtectionLevel=ProtectionLevel.EncryptAndSign
      )]
    string SampleMethod(string msg);
  }

  [DataContractAttribute]
  public class GreetingFault
  { 
    private string report;

    public GreetingFault(string message)
    {
      this.report = message;
    }

    [DataMemberAttribute]
    public string Message
    {
      get { return this.report; }
      set { this.report = value; }
    }
  }

  class SampleService : ISampleService
  {
  #region ISampleService Members

  public string  SampleMethod(string msg)
  {
    Console.WriteLine("Client said: " + msg);
    // Generate intermittent error behavior.
    Random rand = new Random(DateTime.Now.Millisecond);
    int test = rand.Next(5);
    if (test % 2 != 0)
      return "The service greets you: " + msg; 
    else
      throw new FaultException<GreetingFault>(new GreetingFault("A Greeting error occurred. You said: " + msg));
  }

  #endregion
  }
}

次のコード例は、ISampleService の WCF クライアントが、この SOAP エラーを GreetingFault 型の FaultException<(Of <(TDetail>)>) として受信することを示しています。

C#
using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using Microsoft.WCF.Documentation;

public class Client
{
  public static void Main()
  {
    // Picks up configuration from the config file.
    SampleServiceClient wcfClient = new SampleServiceClient();
    try
    {
      // Making calls.
      Console.WriteLine("Enter the greeting to send: ");
      string greeting = Console.ReadLine();
      Console.WriteLine("The service responded: " + wcfClient.SampleMethod(greeting));

      Console.WriteLine("Press ENTER to exit:");
      Console.ReadLine();

      // Done with service. 
      wcfClient.Close();
      Console.WriteLine("Done!");
    }
    catch (TimeoutException timeProblem)
    {
      Console.WriteLine("The service operation timed out. " + timeProblem.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException<GreetingFault> greetingFault)
    {
      Console.WriteLine(greetingFault.Detail.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException unknownFault)
    {
      Console.WriteLine("An unknown exception was received. " + unknownFault.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (CommunicationException commProblem)
    {
      Console.WriteLine("There was a communication problem. " + commProblem.Message + commProblem.StackTrace);
      Console.ReadLine();
      wcfClient.Abort();
    }
  }
}
継承階層

System..::.Object
  System..::.Attribute
    System.ServiceModel..::.FaultContractAttribute
スレッド セーフ

この型のすべてのパブリック static (Visual Basic では Shared) メンバは、スレッド セーフです。インスタンス メンバの場合は、スレッド セーフであるとは限りません。
プラットフォーム

Windows Vista, Windows XP SP2, Windows Server 2003

.NET Framework および .NET Compact Framework では、各プラットフォームのすべてのバージョンはサポートしていません。サポートされているバージョンについては、「.NET Framework システム要件」を参照してください。
バージョン情報

.NET Framework

サポート対象 : 3.5、3.0
参照

参照

タグ :


Page view tracker