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 작업이 GreetingFault의 세부 형식으로 SOAP 오류를 반환할 수 있도록 지정 하는 방법을 보여 줍니다.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 클라이언트가이 SOAP 오류를 GreetingFault형식의 FaultException<TDetail>으로 경험 함을 보여 줍니다.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 오류 메시지로 서비스 작업의 WSDL (웹 서비스 기술 언어) 설명에 추가 되는 특정 예외 조건을 하나 이상 선언 하려면 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. SOAP 기반 애플리케이션에서 Windows Communication Foundation (WCF) 애플리케이션과 같은 서비스 메서드에 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 속성은 오류 메시지에 serialize 된 세부 개체의 형식을 가져옵니다.The DetailType property gets the type of the detail object serialized in the fault message.

  • NameNamespace 속성은 오류 메시지의 이름과 네임 스페이스를 각각 제어 합니다.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.

대부분의 시나리오에서는 오류 메시지에 대 한 ProtectionLevel EncryptAndSign로 설정 해도 충분 합니다.For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. 자세한 내용은 보호 수준 이해를 참조 하세요.For more details, see Understanding Protection Level.

FaultContractAttribute표시 된 작업에서 지정 된 오류를 반환 하려면 작업 중에 관리 되는 예외가 발생할 때 FaultException<TDetail> (형식 매개 변수는 serialize 할 수 있는 오류 정보)를 throw 합니다.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. 즉, 클라이언트 구현에서 throw 된 동일한 형식으로 SOAP 오류는 WCF 클라이언트 애플리케이션 화면으로 FaultException<TDetail> (여기서는 typeparameter은 직렬화 오류 정보).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.

참고

serialize할 수 있는 형식을 사용하여 오류 정보를 전달할 수 있습니다.You can use any serializable type to convey error information. 이 버전의 WCF에서는 FaultContractAttribute에 지정 된 형식을 System.Runtime.Serialization.DataContractSerializer에서 serialize 할 수 있어야 합니다.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에서 제공 하는 serialization 지원에 대 한 자세한 내용은 데이터 계약 직렬 변환기를 참조 하십시오.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.

참고

다음 코드 예에서는 ProtectionLevel, Name또는 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

그런 다음 서비스 메서드에서 새 FaultException<TDetail>을 throw 합니다. 여기서 형식 매개 변수는 오류 정보를 포함 하는 형식 (위 경우 Int32)입니다.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.

참고

형식 매개 변수가 FaultException<TDetail>System.String을 지정하면 문자열 값이 클라이언트 애플리케이션의 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 예외를 throw하고 문자열을 생성자에 전달합니다.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>이 throw될 때 애플리케이션의 동작을 명시적으로 제어하려면 System.ServiceModel.Dispatcher.IErrorHandler, System.ServiceModel.Description.IServiceBehavior 또는 System.ServiceModel.Description.IContractBehavior에서 System.ServiceModel.Description.IEndpointBehavior 인터페이스를 구현하고 이 인터페이스를 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.IncludeExceptionDetailInFaultsServiceDebugBehavior.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 오류의 가능성 (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.

생성자

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

오류 정보가 포함된 serialize할 수 있는 개체의 형식을 가져옵니다.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

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)

적용 대상