FaultContractAttribute クラス

定義

サービス操作で処理エラーが発生したときに返される SOAP エラーを指定します。Specifies one or more SOAP faults that are returned when a service operation encounters processing errors.

public ref class FaultContractAttribute sealed : Attribute
[System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true, Inherited=false)]
public sealed class FaultContractAttribute : Attribute
type FaultContractAttribute = class
    inherit Attribute
Public NotInheritable Class FaultContractAttribute
Inherits Attribute
継承
FaultContractAttribute
属性

次のコード例は、FaultContractAttribute 操作で SampleMethod の詳細な型と共に SOAP エラーを返すことができることを指定するために、GreetingFault を使用しています。The following code example shows the use of FaultContractAttribute to specify that the SampleMethod operation can return a SOAP fault with the detail type of GreetingFault.

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 rnd = new Random(DateTime.Now.Millisecond);
    int test = rnd.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
  }
}

Imports System.Collections.Generic
Imports System.Net.Security
Imports System.Runtime.Serialization
Imports System.ServiceModel
Imports System.Text

Namespace Microsoft.WCF.Documentation
  <ServiceContract(Namespace:="http://microsoft.wcf.documentation")> _
  Public Interface ISampleService
    <OperationContract, FaultContractAttribute(GetType(GreetingFault), Action:="http://www.contoso.com/GreetingFault", ProtectionLevel:=ProtectionLevel.EncryptAndSign)> _
    Function SampleMethod(ByVal msg As String) As String
  End Interface

  <DataContractAttribute> _
  Public Class GreetingFault
    Private report As String

    Public Sub New(ByVal message As String)
      Me.report = message
    End Sub

    <DataMemberAttribute> _
    Public Property Message() As String
      Get
          Return Me.report
      End Get
      Set(ByVal value As String)
          Me.report = value
      End Set
    End Property
  End Class

  Friend Class SampleService
      Implements ISampleService
  #Region "ISampleService Members"

  Public Function SampleMethod(ByVal msg As String) As String Implements ISampleService.SampleMethod
    Console.WriteLine("Client said: " & msg)
    ' Generate intermittent error behavior.
    Dim rand As New Random(DateTime.Now.Millisecond)
    Dim test As Integer = rand.Next(5)
    If test Mod 2 <> 0 Then
      Return "The service greets you: " & msg
    Else
      Throw New FaultException(Of GreetingFault)(New GreetingFault("A Greeting error occurred. You said: " & msg))
    End If
  End Function

  #End Region
  End Class
End Namespace

次のコード例は、ISampleService の WCF クライアントが、GreetingFault型の FaultException<TDetail> としてこの SOAP エラーを発生させることを示しています。The following code example shows that WCF clients of ISampleService experience this SOAP fault as a FaultException<TDetail> of type GreetingFault.

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();
    }
  }
}

Imports System.ServiceModel
Imports System.ServiceModel.Channels
Imports Microsoft.WCF.Documentation

Public Class Client
  Public Shared Sub Main()
    ' Picks up configuration from the config file.
    Dim wcfClient As New SampleServiceClient()
    Try
      ' Making calls.
      Console.WriteLine("Enter the greeting to send: ")
      Dim greeting As String = 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 timeProblem As TimeoutException
      Console.WriteLine("The service operation timed out. " & timeProblem.Message)
      Console.ReadLine()
      wcfClient.Abort()
    Catch greetingFault As FaultException(Of GreetingFault)
      Console.WriteLine(greetingFault.Detail.Message)
      Console.ReadLine()
      wcfClient.Abort()
    Catch unknownFault As FaultException
      Console.WriteLine("An unknown exception was received. " & unknownFault.Message)
      Console.ReadLine()
      wcfClient.Abort()
    Catch commProblem As CommunicationException
      Console.WriteLine("There was a communication problem. " & commProblem.Message + commProblem.StackTrace)
      Console.ReadLine()
      wcfClient.Abort()
    End Try
  End Sub
End Class

注釈

操作に、操作によって返される明示的な SOAP エラーメッセージとして、サービス操作の Web サービス記述言語 (WSDL) の説明に追加される1つ以上の特定の例外条件を宣言するには、FaultContractAttribute 属性を使用してマークします。Mark an operation with the FaultContractAttribute attribute to declare one or more specific exception conditions that are added to the Web Service Description Language (WSDL) description of the service operation as explicit SOAP fault messages returned by the operation.

すべてのマネージド アプリケーションで、操作エラーは Exception オブジェクトにより表されます。In all managed applications, processing errors are represented by Exception objects. Windows Communication Foundation (WCF) アプリケーションなどの SOAP ベースのアプリケーションでは、サービスメソッドは SOAP エラーメッセージを使用して処理エラー情報を通信します。In SOAP-based applications such as Windows Communication Foundation (WCF) applications, service methods communicate processing error information using SOAP fault messages. WCF アプリケーションは、両方の種類のエラーシステムで実行されるため、クライアントに送信する必要があるマネージ例外情報は、例外から SOAP エラーに変換する必要があります。Because WCF applications execute under both types of error systems, any managed exception information that must be sent to the client must be converted from exceptions into SOAP faults. 既定のサービス例外動作を使用できます。または、例外をエラー メッセージにマッピングするかどうかとそのマッピング方法を明示的に制御できます。You can use the default service exception behaviors, or you can explicitly control whether -- and how -- exceptions are mapped to fault messages. WCF アプリケーションでの例外と SOAP エラーの概要については、「コントラクトとサービスのエラーの指定と処理」を参照してください。For an overview of exceptions and SOAP faults in WCF applications, see Specifying and Handling Faults in Contracts and Services.

サービス操作では、FaultContractAttribute を使用して、通常の操作の過程でクライアントが受け取る可能性のあるすべての SOAP エラーを正式に指定することをお勧めします。It is recommended that service operations use the FaultContractAttribute 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 only that information a client must know is returned in a SOAP fault to minimize information disclosure.

  • Action プロパティは、エラーメッセージのアクションを制御します。The Action property controls the action of the fault message.

  • DetailType プロパティは、エラーメッセージでシリアル化された詳細オブジェクトの型を取得します。The DetailType property gets the type of the detail object serialized in the fault message.

  • Name プロパティと Namespace プロパティは、エラーメッセージの名前と名前空間をそれぞれ制御します。The Name and Namespace properties control the name and namespace, respectively, of the fault message.

  • HasProtectionLevel は、エラーメッセージに保護レベルが指定されているかどうかを示します。存在する場合、ProtectionLevel プロパティは保護レベルを制御します。The HasProtectionLevel indicates whether the fault message has a protection level specified, and if so, the ProtectionLevel property controls that level of protection.

注意事項

エラーメッセージに機密情報が含まれている場合、またはセキュリティ上の問題につながる可能性がある場合は、ProtectionLevel プロパティを設定することを強くお勧めします。If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the ProtectionLevel property be set.

多くのシナリオでは、エラーメッセージの EncryptAndSignProtectionLevel を設定するだけで十分です。For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. 詳細については、「保護レベルについて」を参照してください。For more details, see Understanding Protection Level.

FaultContractAttributeでマークされた操作から指定されたエラーを返すには、操作中にマネージ例外が発生したときに、FaultException<TDetail> (型パラメーターがシリアル化可能なエラー情報) をスローします。To return a specified fault from an operation marked with FaultContractAttribute, throw a FaultException<TDetail> (where the type parameter is the serializable error information) when the managed exception occurs during the operation. WCF クライアントアプリケーションは、クライアント実装でスローされたのと同じ型 (つまり FaultException<TDetail>、typeparameter がシリアル化可能なエラー情報である) として SOAP エラーを格納します。WCF client applications surface the SOAP fault as the same type as was thrown in the client implementation -- that is, as a FaultException<TDetail> (where the typeparameter is the serializable error information). FaultContractAttribute は、双方向のサービス操作と非同期操作のペアに対して SOAP エラーを指定する場合にのみ使用できます。一方向の操作では SOAP エラーがサポートされないため、FaultContractAttributeはサポートされません。The FaultContractAttribute can be used only to specify SOAP faults for two-way service operations and for asynchronous operation pairs; one-way operations do not support SOAP faults and therefore do not support FaultContractAttribute.

注意

エラー情報を伝えるために、任意のシリアル化可能な型を使用できます。You can use any serializable type to convey error information. このバージョンの WCF で唯一の制限は、FaultContractAttribute で指定された型が System.Runtime.Serialization.DataContractSerializerによってシリアル化できる必要があることです。The only restriction in this version of WCF is that types specified in a FaultContractAttribute must be serializable by the System.Runtime.Serialization.DataContractSerializer. DataContractSerializer が提供するシリアル化のサポートについては、「データコントラクトシリアライザー」を参照してください。For the serialization support the DataContractSerializer provides, see Data Contract Serializer.

たとえば、Int32を含む SOAP エラーをクライアントが想定できるように指定するには、その型パラメーターをサービスメソッドの FaultContractAttribute に配置します。For example, to specify that clients can expect a SOAP fault that contains an Int32, place that type parameter in the FaultContractAttribute on your service method.

注意

次のコード例では、ProtectionLevelName、または Namespace プロパティは設定しません。The following code examples do not set the ProtectionLevel, Name, or Namespace properties.

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

次に、サービスメソッドで、型パラメーターがエラー情報を含む型 (上記の場合は Int32) である新しい FaultException<TDetail> をスローします。Then, in your service method, throw a new FaultException<TDetail> where the type parameter is the type that contains the error information (in the above case, a Int32). 例 : For example:

throw new FaultException<int>(4);
Throw New FaultException(Of Integer)(4)

前の例は非常に基本的なものです。System.Int32 コードを使用してほぼすべての情報を渡すことができます。そのため、この詳細の種類は最も役に立ちません。The preceding example is very basic; almost any information can be passed using an System.Int32 code, so this detail type is not the most useful. 通常、WCF アプリケーションは、クライアントのエラー情報要件に固有の詳細な種類を使用して、SOAP エラーを指定します。Typically, WCF applications specify SOAP faults with detail types specific to the error information requirements of the client. より完全な例については、「使用例」のセクションを参照してください。For a more complete example, see the Example section.

注意

Type パラメーターが System.Stringである FaultException<TDetail> を指定すると、クライアントアプリケーションの Detail プロパティに文字列値が割り当てられます。クライアントは、FaultException<TDetail>.ToString メソッドを呼び出すことによってその文字列を取得することはできません。If you specify a FaultException<TDetail> where the type parameter is a System.String, the string value is assigned to the Detail property in the client application; clients cannot retrieve that string by calling the FaultException<TDetail>.ToString method. クライアント アプリケーションが Exception.ToString を呼び出したときにこの文字列値を返すには、操作内で System.ServiceModel.FaultException 例外をスローし、この文字列をコンストラクターに渡します。To have the string value returned when the client application calls Exception.ToString, throw a System.ServiceModel.FaultException exception inside the operation and pass the string to the constructor.

例外または FaultException<TDetail> がスローされたときにアプリケーションの動作を明示的に制御するには、System.ServiceModel.Description.IServiceBehaviorSystem.ServiceModel.Description.IContractBehavior または System.ServiceModel.Description.IEndpointBehaviorSystem.ServiceModel.Dispatcher.IErrorHandler インターフェイスを実装し、それを ChannelDispatcher.ErrorHandlers プロパティに割り当てます。To explicitly control the behavior of the application when an exception or FaultException<TDetail> is thrown, implement the System.ServiceModel.Dispatcher.IErrorHandler interface on an System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior or System.ServiceModel.Description.IEndpointBehavior and assign it to the ChannelDispatcher.ErrorHandlers property. IErrorHandler を使用すると、生成される SOAP エラーと、それをクライアントに送信するかどうかを明示的に制御できます。IErrorHandler enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

デバッグを容易にするには、コードで ServiceBehaviorAttribute.IncludeExceptionDetailInFaultstrue に設定するか、アプリケーション構成ファイルで ServiceDebugBehavior.IncludeExceptionDetailInFaults を使用します。To facilitate debugging, set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults to true in code or you can use the ServiceDebugBehavior.IncludeExceptionDetailInFaults in an application configuration file. 有効な場合は、サービスが自動的に例外情報を呼び出し元に返します。When enabled, the service automatically returns exception information to the caller. これらのエラーは、FaultException の例外としてクライアントに表示されます。These faults appear to the client as FaultException exceptions.

重要

マネージ例外によって内部アプリケーション情報が公開される可能性があるため、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 only recommended as a way of temporarily debugging a service application. さらに、このようにして未処理のマネージド例外を返すメソッドの WSDL には、FaultException<TDetail> 型の String のコントラクトが含まれません。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 String. クライアントは、デバッグ情報を適切に取得するために、不明な 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.

コンストラクター

FaultContractAttribute(Type)

FaultContractAttribute クラスの新しいインスタンスを初期化します。Initializes a new instance of the FaultContractAttribute class.

プロパティ

Action

操作コントラクトの一部として指定された SOAP エラー メッセージのアクションを取得または設定します。Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

DetailType

エラー情報を含むシリアル化可能なオブジェクトの型を取得します。Gets the type of a serializable object that contains error information.

HasProtectionLevel

SOAP エラー メッセージに保護レベルが割り当てられているかどうかを示す値を取得します。Gets a value that indicates whether the SOAP fault message has a protection level assigned.

Name

Web サービス記述言語 (WSDL) でのエラー メッセージの名前を取得または設定します。Gets or sets the name of the fault message in Web Services Description Language (WSDL).

Namespace

SOAP エラーの名前空間を取得または設定します。Gets or sets the namespace of the SOAP fault.

ProtectionLevel

SOAP エラーがバインドに要求する保護レベルを指定します。Specifies the level of protection the SOAP fault requires from the binding.

TypeId

派生クラスで実装されると、この Attribute の一意の識別子を取得します。When implemented in a derived class, gets a unique identifier for this Attribute.

(継承元 Attribute)

メソッド

Equals(Object)

このインスタンスが、指定されたオブジェクトと等価であるかどうかを示す値を返します。Returns a value that indicates whether this instance is equal to a specified object.

(継承元 Attribute)
GetHashCode()

このインスタンスのハッシュ コードを返します。Returns the hash code for this instance.

(継承元 Attribute)
GetType()

現在のインスタンスの Type を取得します。Gets the Type of the current instance.

(継承元 Object)
IsDefaultAttribute()

派生クラスでオーバーライドされるとき、このインスタンスの値が派生クラスの既定値であるかどうかを示します。When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(継承元 Attribute)
Match(Object)

派生クラス内でオーバーライドされたときに、指定したオブジェクトとこのインスタンスが等しいかどうかを示す値を返します。When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(継承元 Attribute)
MemberwiseClone()

現在の Object の簡易コピーを作成します。Creates a shallow copy of the current Object.

(継承元 Object)
ToString()

現在のオブジェクトを表す string を返します。Returns a string that represents the current object.

(継承元 Object)

明示的なインターフェイスの実装

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

一連の名前を対応する一連のディスパッチ識別子に割り当てます。Maps a set of names to a corresponding set of dispatch identifiers.

(継承元 Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

オブジェクトの型情報を取得します。この情報はインターフェイスの型情報の取得に使用できます。Retrieves the type information for an object, which can be used to get the type information for an interface.

(継承元 Attribute)
_Attribute.GetTypeInfoCount(UInt32)

オブジェクトが提供する型情報インターフェイスの数 (0 または 1) を取得します。Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(継承元 Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

オブジェクトによって公開されたプロパティおよびメソッドへのアクセスを提供します。Provides access to properties and methods exposed by an object.

(継承元 Attribute)

適用対象