FaultContractAttribute FaultContractAttribute FaultContractAttribute FaultContractAttribute Class

Definição

Especifica uma ou mais falhas de SOAP que são retornadas quando uma operação de serviço encontra erros de processamento.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
Herança
FaultContractAttributeFaultContractAttributeFaultContractAttributeFaultContractAttribute
Atributos

Exemplos

O exemplo de código a seguir mostra o uso de FaultContractAttribute para especificar que a operação SampleMethod pode retornar uma falha de SOAP com o tipo de detalhe de 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

O exemplo de código a seguir mostra que os clientes WCF de ISampleService experimentam essa falha de SOAP como um FaultException<TDetail> do tipo GreetingFault.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

Comentários

Marque uma operação com o atributo FaultContractAttribute para declarar uma ou mais condições de exceção específicas que são adicionadas à descrição da WSDL (Web Service Description Language) da operação de serviço como mensagens de falha SOAP explícitas retornadas pela operação.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.

Em todos os aplicativos gerenciados, os erros de processamento são representados por objetos Exception.In all managed applications, processing errors are represented by Exception objects. Em aplicativos baseados em SOAP, como aplicativos Windows Communication Foundation (WCF), os métodos de serviço comunicam informações de erro de processamento usando mensagens de falha de SOAP.In SOAP-based applications such as Windows Communication Foundation (WCF) applications, service methods communicate processing error information using SOAP fault messages. Como os aplicativos WCF são executados em ambos os tipos de sistemas de erro, todas as informações de exceção gerenciadas que devem ser enviadas ao cliente devem ser convertidas de exceções em falhas de 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. Você pode usar os comportamentos de exceção de serviço padrão ou pode controlar explicitamente se--e como as exceções são mapeadas para as mensagens de falha.You can use the default service exception behaviors, or you can explicitly control whether -- and how -- exceptions are mapped to fault messages. Para obter uma visão geral das exceções e falhas de SOAP em aplicativos WCF, consulte especificando e manipulando falhas em contratos e serviços.For an overview of exceptions and SOAP faults in WCF applications, see Specifying and Handling Faults in Contracts and Services.

É recomendável que as operações de serviço usem o FaultContractAttribute para especificar formalmente todas as falhas SOAP que um cliente pode esperar receber no curso normal de uma operação.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. Também é recomendável que apenas as informações que um cliente deve saber sejam retornadas em uma falha de SOAP para minimizar a divulgação de informações.It is also recommended that only that information a client must know is returned in a SOAP fault to minimize information disclosure.

  • A propriedade Action controla a ação da mensagem de falha.The Action property controls the action of the fault message.

  • A propriedade DetailType Obtém o tipo do objeto de detalhe serializado na mensagem de falha.The DetailType property gets the type of the detail object serialized in the fault message.

  • As propriedades Name e Namespace controlam o nome e o namespace, respectivamente, da mensagem de falha.The Name and Namespace properties control the name and namespace, respectively, of the fault message.

  • O HasProtectionLevel indica se a mensagem de falha tem um nível de proteção especificado e, em caso afirmativo, a propriedade ProtectionLevel controla esse nível de proteção.The HasProtectionLevel indicates whether the fault message has a protection level specified, and if so, the ProtectionLevel property controls that level of protection.

Cuidado

Se uma mensagem de falha tiver informações confidenciais ou puder causar problemas de segurança, é altamente recomendável que a propriedade ProtectionLevel seja definida.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.

Para muitos cenários, a configuração ProtectionLevel a EncryptAndSign para mensagens de falha é suficiente.For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. Para obter mais detalhes, consulte noções básicas sobre o nível de proteção.For more details, see Understanding Protection Level.

Para retornar uma falha especificada de uma operação marcada com FaultContractAttribute, lance um FaultException<TDetail> (em que o parâmetro de tipo é as informações de erro serializáveis) quando a exceção gerenciada ocorre durante a operação.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. Os aplicativos cliente do WCF superfície a falha de SOAP como o mesmo tipo que foi lançado na implementação do cliente, ou seja, como um FaultException<TDetail> (em que typeparameter é a informação de erro serializável).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). O FaultContractAttribute pode ser usado apenas para especificar falhas de SOAP para operações de serviço bidirecional e para pares de operação assíncronas; as operações unidirecionais não dão suporte a falhas de SOAP e, portanto, não dão suporte a 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.

Observação

Você pode usar qualquer tipo serializável para transmitir informações de erro.You can use any serializable type to convey error information. A única restrição nesta versão do WCF é que os tipos especificados em um FaultContractAttribute devem ser serializáveis pelo 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. Para obter suporte de serialização, o DataContractSerializer fornece, consulte serializador de contrato de dados.For the serialization support the DataContractSerializer provides, see Data Contract Serializer.

Por exemplo, para especificar que os clientes podem esperar uma falha de SOAP que contenha um Int32, coloque esse parâmetro de tipo no FaultContractAttribute em seu método de serviço.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.

Observação

Os exemplos de código a seguir não definem as propriedades ProtectionLevel, Name ou 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

Em seguida, em seu método de serviço, acione um novo FaultException<TDetail> em que o parâmetro de tipo é o tipo que contém as informações de erro (no caso acima, um 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). Por exemplo:For example:

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

O exemplo anterior é muito básico; quase todas as informações podem ser passadas usando um código System.Int32, portanto, esse tipo de detalhe não é o mais útil.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. Normalmente, os aplicativos WCF especificam falhas de SOAP com tipos de detalhes específicos para os requisitos de informações de erro do cliente.Typically, WCF applications specify SOAP faults with detail types specific to the error information requirements of the client. Para obter um exemplo mais completo, consulte a seção de exemplo.For a more complete example, see the Example section.

Observação

Se você especificar um FaultException<TDetail> em que o parâmetro de tipo é um System.String, o valor da cadeia de caracteres será atribuído à propriedade Detail no aplicativo cliente; Os clientes não podem recuperar essa cadeia de caracteres chamando o método 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. Para que o valor da cadeia de caracteres seja retornado quando o aplicativo cliente chama Exception.ToString, lance uma exceção System.ServiceModel.FaultException dentro da operação e passe a cadeia de caracteres para o construtor.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.

Para controlar explicitamente o comportamento do aplicativo quando uma exceção ou FaultException<TDetail> é gerada, implemente a interface System.ServiceModel.Dispatcher.IErrorHandler em um System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior ou System.ServiceModel.Description.IEndpointBehavior e atribua-o à propriedade 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 permite que você controle explicitamente a falha de SOAP gerada e se deseja enviá-la de volta ao cliente.IErrorHandler enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

Para facilitar a depuração, defina o ServiceBehaviorAttribute.IncludeExceptionDetailInFaults como true no código ou você pode usar o ServiceDebugBehavior.IncludeExceptionDetailInFaults em um arquivo de configuração de aplicativo.To facilitate debugging, set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults to true in code or you can use the ServiceDebugBehavior.IncludeExceptionDetailInFaults in an application configuration file. Quando habilitado, o serviço retorna automaticamente informações de exceção ao chamador.When enabled, the service automatically returns exception information to the caller. Essas falhas aparecem para o cliente como exceções FaultException.These faults appear to the client as FaultException exceptions.

Importante

Como as exceções gerenciadas podem expor informações internas do aplicativo, definir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults como true pode permitir que os clientes WCF obtenham informações sobre exceções de operação de serviço interno, incluindo identificação pessoal ou outras confidenciais divulgação.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.

Portanto, definir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults como true é recomendado apenas como uma maneira de depurar temporariamente um aplicativo de serviço.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is only recommended as a way of temporarily debugging a service application. Além disso, o WSDL para um método que retorna exceções gerenciadas sem tratamento dessa maneira não contém o contrato para o FaultException<TDetail> do tipo 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. Os clientes devem esperar a possibilidade de uma falha SOAP desconhecida (retornada aos clientes WCF como objetos System.ServiceModel.FaultException) para obter as informações de depuração corretamente.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.

Construtores

FaultContractAttribute(Type) FaultContractAttribute(Type) FaultContractAttribute(Type) FaultContractAttribute(Type)

Inicializa uma nova instância da classe FaultContractAttribute.Initializes a new instance of the FaultContractAttribute class.

Propriedades

Action Action Action Action

Obtém ou define a ação da mensagem de falha de SOAP que é especificada como parte do contrato de operação.Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

DetailType DetailType DetailType DetailType

Obtém o tipo de um objeto serializável que contém informações de erro.Gets the type of a serializable object that contains error information.

HasProtectionLevel HasProtectionLevel HasProtectionLevel HasProtectionLevel

Obtém um valor que indica se a mensagem de falha de SOAP tem um nível de proteção atribuído.Gets a value that indicates whether the SOAP fault message has a protection level assigned.

Name Name Name Name

Obtém ou define o nome da mensagem de falha na linguagem WSDL.Gets or sets the name of the fault message in Web Services Description Language (WSDL).

Namespace Namespace Namespace Namespace

Obtém ou define o namespace da falha de SOAP.Gets or sets the namespace of the SOAP fault.

ProtectionLevel ProtectionLevel ProtectionLevel ProtectionLevel

Especifica o nível de proteção que a falha de SOAP exige da associação.Specifies the level of protection the SOAP fault requires from the binding.

TypeId TypeId TypeId TypeId

Quando implementado em uma classe derivada, obtém um identificador exclusivo para este Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Inherited from Attribute)

Métodos

Equals(Object) Equals(Object) Equals(Object) Equals(Object)

Retorna um valor que indica se essa instância é igual a um objeto especificado.Returns a value that indicates whether this instance is equal to a specified object.

(Inherited from Attribute)
GetHashCode() GetHashCode() GetHashCode() GetHashCode()

Retorna o código hash para essa instância.Returns the hash code for this instance.

(Inherited from Attribute)
GetType() GetType() GetType() GetType()

Obtém o Type da instância atual.Gets the Type of the current instance.

(Inherited from Object)
IsDefaultAttribute() IsDefaultAttribute() IsDefaultAttribute() IsDefaultAttribute()

Quando substituído em uma classe derivada, indica se o valor dessa instância é o valor padrão para a classe derivada.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Inherited from Attribute)
Match(Object) Match(Object) Match(Object) Match(Object)

Quando substituído em uma classe derivada, retorna um valor que indica se essa instância é igual a um objeto especificado.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Inherited from Attribute)
MemberwiseClone() MemberwiseClone() MemberwiseClone() MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Inherited from Object)
ToString() ToString() ToString() ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.Returns a string that represents the current object.

(Inherited from Object)

Implantações explícitas de interface

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

Mapeia um conjunto de nomes para um conjunto correspondente de identificadores de expedição.Maps a set of names to a corresponding set of dispatch identifiers.

(Inherited from Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr) _Attribute.GetTypeInfo(UInt32, UInt32, IntPtr) _Attribute.GetTypeInfo(UInt32, UInt32, IntPtr) _Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Recupera as informações de tipo para um objeto, que pode ser usado para obter as informações de tipo para uma interface.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Inherited from Attribute)
_Attribute.GetTypeInfoCount(UInt32) _Attribute.GetTypeInfoCount(UInt32) _Attribute.GetTypeInfoCount(UInt32) _Attribute.GetTypeInfoCount(UInt32)

Retorna o número de interfaces de informações do tipo que um objeto fornece (0 ou 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Inherited from Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr) _Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr) _Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr) _Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Fornece acesso a propriedades e métodos expostos por um objeto.Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

Aplica-se a