FaultContractAttribute Classe

Referência

Definição

Namespace:: System.ServiceModel

Assembly:: System.ServiceModel.Primitives.dll

Assembly:: System.ServiceModel.dll

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Especifica uma ou mais falhas de SOAP que são retornadas quando uma operação de serviço encontra erros de processamento.

public ref class FaultContractAttribute sealed : Attribute

[System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true, Inherited=false)]
public sealed class FaultContractAttribute : Attribute

[<System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true, Inherited=false)>]
type FaultContractAttribute = class
    inherit Attribute

Public NotInheritable Class FaultContractAttribute
Inherits Attribute

Herança: Object

Attribute
FaultContractAttribute

Atributos: AttributeUsageAttribute

Exemplos

O exemplo de código a seguir mostra o uso para FaultContractAttribute especificar que a SampleMethod operação pode retornar uma falha SOAP com o tipo de detalhe de 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 do WCF experimentam ISampleService essa falha SOAP como um FaultException<TDetail> tipo 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 FaultContractAttribute atributo para declarar uma ou mais condições de exceção específicas que são adicionadas à descrição da WSDL (Linguagem de Descrição do Serviço Web) da operação de serviço como mensagens de falha SOAP explícitas retornadas pela operação.

Em todos os aplicativos gerenciados, os erros de processamento são representados por Exception objetos. Em aplicativos baseados em SOAP, como aplicativos WCF (Windows Communication Foundation), os métodos de serviço comunicam informações de erro de processamento usando mensagens de falha SOAP. 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 SOAP. Você pode usar os comportamentos de exceção de serviço padrão ou controlar explicitamente se as exceções são mapeadas para mensagens de falha. Para obter uma visão geral de exceções e falhas SOAP em aplicativos WCF, consulte Especificando e tratando falhas em contratos e serviços.

É recomendável que as operações de serviço usem para FaultContractAttribute especificar formalmente todas as falhas SOAP que um cliente pode esperar receber no curso normal de uma operação. Também é recomendável que apenas as informações que um cliente deve saber sejam retornadas em uma falha SOAP para minimizar a divulgação de informações.

A Action propriedade controla a ação da mensagem de falha.
A DetailType propriedade obtém o tipo do objeto de detalhe serializado na mensagem de falha.
As Name propriedades e Namespace o nome e o namespace, respectivamente, da mensagem de falha.
Indica HasProtectionLevel se a mensagem de falha tem um nível de proteção especificado e, se for o caso, a ProtectionLevel propriedade controla esse nível de proteção.

Cuidado

Se uma mensagem de falha levar informações confidenciais ou que podem levar a problemas de segurança, é altamente recomendável que a ProtectionLevel propriedade seja definida.

Se você definir explicitamente ProtectionLevel como ProtectionLevel.Sign ou ProtectionLevel.EncryptAndSign, em seguida, você deve usar uma associação com a segurança habilitada usando a System.ServiceModel.SecurityMode propriedade na associação ou uma exceção é lançada.
Se você selecionar uma associação que habilita a segurança e não definir a ProtectionLevel propriedade em nenhum lugar no contrato, todos os dados do aplicativo serão criptografados e assinados.
Se você selecionar uma associação que não tenha a segurança habilitada (por exemplo, a segurança tem a System.ServiceModel.BasicHttpBinding segurança desabilitada por padrão) e não ProtectionLevel estiver definida explicitamente, nenhum dos dados do aplicativo será protegido.

Para muitos cenários, a configuração ProtectionLevel para EncryptAndSign mensagens de falha é suficiente. Para obter mais detalhes, consulte Noções básicas sobre o nível de proteção.

Para retornar uma falha especificada de uma operação marcada com FaultContractAttribute, lance um FaultException<TDetail> (em que o parâmetro de tipo é a informação de erro serializável) quando a exceção gerenciada ocorrer durante a operação. Os aplicativos cliente WCF exibem a falha SOAP como o mesmo tipo que foi gerado na implementação do cliente , ou seja, como um FaultException<TDetail> (em que o typeparameter é a informação de erro serializável). A FaultContractAttribute opção pode ser usada apenas para especificar falhas SOAP para operações de serviço bidirecionais e para pares de operação assíncronas; as operações unidirecionais não dão suporte a falhas SOAP e, portanto, não dão suporte FaultContractAttribute.

Observação

Você pode usar qualquer tipo serializável para transmitir informações de erro. 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. Para obter suporte à serialização fornecida DataContractSerializer , consulte Serializador de Contrato de Dados.

Por exemplo, para especificar que os clientes podem esperar uma falha SOAP que contém um Int32parâmetro de tipo no FaultContractAttribute método de serviço.

Observação

Os exemplos de código a seguir não definem as propriedades ou Namespace as ProtectionLevel Namepropriedades.

[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, lance um novo FaultException<TDetail> onde o parâmetro de tipo é o tipo que contém as informações de erro (no caso acima, a Int32). Por exemplo:

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 System.Int32 código, portanto, esse tipo de detalhe não é o mais útil. Normalmente, os aplicativos WCF especificam falhas SOAP com tipos de detalhes específicos aos requisitos de informações de erro do cliente. Para obter um exemplo mais completo, consulte a seção Exemplo.

Observação

Se você especificar um FaultException<TDetail> local 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 poderão recuperar essa cadeia de caracteres chamando o FaultException<TDetail>.ToString método. Para que o valor da cadeia de caracteres seja retornado quando o aplicativo cliente chamar Exception.ToString, gere uma System.ServiceModel.FaultException exceção dentro da operação e passe a cadeia de caracteres para o construtor.

Para controlar explicitamente o comportamento do aplicativo quando uma exceção ou FaultException<TDetail> for lançada, implemente a System.ServiceModel.Dispatcher.IErrorHandler interface em um System.ServiceModel.Description.IServiceBehavior System.ServiceModel.Description.IContractBehavior ou System.ServiceModel.Description.IEndpointBehavior atribua-a ChannelDispatcher.ErrorHandlers à propriedade. IErrorHandler permite que você controle explicitamente a falha SOAP gerada e se deseja enviá-la de volta para o cliente.

Para facilitar a depuração, defina o ServiceBehaviorAttribute.IncludeExceptionDetailInFaults código para true o código ou você pode usar o ServiceDebugBehavior.IncludeExceptionDetailInFaults arquivo de configuração em um aplicativo. Quando habilitado, o serviço retorna automaticamente informações de exceção para o chamador. Essas falhas aparecem no cliente como FaultException exceções.

Importante

Como exceções gerenciadas podem expor informações internas do aplicativo, definir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults permitir que true os clientes do WCF obtenham informações sobre exceções de operação de serviço interna, incluindo informações pessoais identificáveis ou outras informações confidenciais.

Portanto, a configuração ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults a definição true só é recomendada como uma forma de depurar temporariamente um aplicativo de serviço. Além disso, o WSDL para um método que retorna exceções gerenciadas sem tratamento dessa forma não contém o contrato do FaultException<TDetail> tipo String. Os clientes devem esperar a possibilidade de uma falha SOAP desconhecida (retornada aos clientes do WCF como System.ServiceModel.FaultException objetos) para obter as informações de depuração corretamente.

Construtores

FaultContractAttribute(Type)

Inicializa uma nova instância da classe FaultContractAttribute.

Propriedades

Action	Obtém ou define a ação da mensagem de falha de SOAP que é especificada como parte do contrato de operação.
DetailType	Obtém o tipo de um objeto serializável que contém informações de erro.
HasProtectionLevel	Obtém um valor que indica se a mensagem de falha de SOAP tem um nível de proteção atribuído.
Name	Obtém ou define o nome da mensagem de falha na linguagem WSDL.
Namespace	Obtém ou define o namespace da falha de SOAP.
ProtectionLevel	Especifica o nível de proteção que a falha de SOAP exige da associação.
TypeId	Quando implementado em uma classe derivada, obtém um identificador exclusivo para este Attribute. (Herdado de Attribute)

Métodos

Equals(Object)	Retorna um valor que indica se essa instância é igual a um objeto especificado. (Herdado de Attribute)
GetHashCode()	Retorna o código hash para a instância. (Herdado de Attribute)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
IsDefaultAttribute()	Quando substituído em uma classe derivada, indica se o valor dessa instância é o valor padrão para a classe derivada. (Herdado de Attribute)
Match(Object)	Quando substituído em uma classe derivada, retorna um valor que indica se essa instância é igual a um objeto especificado. (Herdado de Attribute)
MemberwiseClone()	Cria uma cópia superficial do Object atual. (Herdado de Object)
ToString()	Retorna uma cadeia de caracteres que representa o objeto atual. (Herdado de Object)

Implantações explícitas de interface

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Mapeia um conjunto de nomes para um conjunto correspondente de identificadores de expedição. (Herdado de Attribute)
_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. (Herdado de Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Retorna o número de interfaces de informações do tipo que um objeto fornece (0 ou 1). (Herdado de Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)	Fornece acesso a propriedades e métodos expostos por um objeto. (Herdado de Attribute)

Aplica-se a

FaultContractAttribute Classe

Definição

Exemplos

Comentários

Construtores

Propriedades

Métodos

Implantações explícitas de interface

Aplica-se a

Recursos adicionais