FaultContractAttribute Clase

Referencia

Definición

Espacio de nombres:: System.ServiceModel

Ensamblado:: System.ServiceModel.Primitives.dll

Ensamblado:: System.ServiceModel.dll

Importante

Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

Especifica uno o más errores de SOAP que se devuelven cuando se producen errores de procesamiento en una operación de servicio.

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

Herencia: Object

Attribute
FaultContractAttribute

Atributos: AttributeUsageAttribute

Ejemplos

El ejemplo de código siguiente muestra el uso de FaultContractAttribute para especificar que la operación SampleMethod puede devolver un error de SOAP con el tipo de detalle 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

En el ejemplo de código siguiente se muestra que los clientes WCF de ISampleService experimentan este error soap como de 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

Comentarios

Marque una operación con el FaultContractAttribute atributo para declarar una o varias condiciones de excepción específicas que se agregan a la descripción del lenguaje de descripción del servicio web (WSDL) de la operación de servicio como mensajes de error SOAP explícitos devueltos por la operación.

En todas las aplicaciones administradas, los errores de procesamiento están representados mediante objetos Exception. En aplicaciones basadas en SOAP, como aplicaciones de Windows Communication Foundation (WCF), los métodos de servicio comunican la información de procesamiento de errores mediante mensajes de error SOAP. Dado que las aplicaciones WCF se ejecutan en ambos tipos de sistemas de error, cualquier información de excepción administrada que se debe enviar al cliente debe convertirse de excepciones en errores soap. Puede usar los comportamientos de excepción de servicio predeterminados o controlar explícitamente si (y cómo) las excepciones se asignan a los mensajes de error. Para obtener información general sobre las excepciones y los errores de SOAP en las aplicaciones WCF, consulte Especificación y control de errores en contratos y servicios.

Se recomienda que las operaciones de servicio usen FaultContractAttribute para especificar formalmente todos los errores soap que un cliente puede esperar recibir en el curso normal de una operación. Además, se recomienda que sólo se devuelva en un error de SOAP la información que un cliente deba conocer para minimizar la divulgación de información.

La Action propiedad controla la acción del mensaje de error.
La DetailType propiedad obtiene el tipo del objeto de detalle serializado en el mensaje de error.
Las Name propiedades y Namespace controlan el nombre y el espacio de nombres, respectivamente, del mensaje de error.
HasProtectionLevel indica si el mensaje de error tiene un nivel de protección especificado y, si es así, la ProtectionLevel propiedad controla ese nivel de protección.

Precaución

Si un mensaje de error contiene información confidencial o puede provocar problemas de seguridad, se recomienda encarecidamente establecer la ProtectionLevel propiedad .

Si establece explícitamente ProtectionLevel.Sign en ProtectionLevel o ProtectionLevel.EncryptAndSign, debe usar un enlace con la seguridad habilitada mediante la System.ServiceModel.SecurityMode propiedad en el enlace o se produce una excepción.
Si selecciona un enlace que habilita la seguridad y no establece la propiedad ProtectionLevel en cualquier parte del contrato, se cifrarán y firmarán todos los datos de la aplicación.
Si selecciona un enlace que no tiene habilitada la seguridad (por ejemplo, tiene System.ServiceModel.BasicHttpBinding la seguridad deshabilitada de forma predeterminada) y no ProtectionLevel se establece explícitamente, no se protegerá ninguno de los datos de la aplicación.

Para muchos escenarios, establecer en ProtectionLevel EncryptAndSign para los mensajes de error es suficiente. Para obtener más información, consulte Descripción del nivel de protección.

Para devolver un error especificado de una operación marcada con FaultContractAttribute, inicie ( FaultException<TDetail> donde el parámetro type es la información de error serializable) cuando se produce la excepción administrada durante la operación. Las aplicaciones cliente de WCF exponen el error soap que el mismo tipo que se produjo en la implementación del cliente, es decir, como , FaultException<TDetail> que es (donde typeparameter es la información de error serializable). FaultContractAttribute solo se puede usar para especificar errores SOAP para operaciones de servicio bidireccionales y para pares de operaciones asincrónicas; las operaciones unidireccionales no admiten errores SOAP y, por lo tanto, no admiten FaultContractAttribute.

Nota

Puede utilizar cualquier tipo serializable para llevar información de error. La única restricción de esta versión de WCF es que los tipos especificados en un FaultContractAttribute objeto deben ser serializables por .System.Runtime.Serialization.DataContractSerializer Para obtener la compatibilidad DataContractSerializer con la serialización, consulte Serializador de contrato de datos.

Por ejemplo, para especificar que los clientes pueden esperar un error soap que contenga un Int32, coloque ese parámetro de tipo en en el FaultContractAttribute método de servicio.

Nota

Los ejemplos de código siguientes no establecen las ProtectionLevelpropiedades , Nameo Namespace .

[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

A continuación, en el método de servicio, inicie un nuevo FaultException<TDetail> donde el parámetro type es el tipo que contiene la información de error (en el caso anterior, ).Int32 Por ejemplo:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

El ejemplo anterior es muy básico; casi cualquier información se puede pasar mediante un System.Int32 código, por lo que este tipo de detalle no es el más útil. Normalmente, las aplicaciones WCF especifican errores SOAP con tipos de detalle específicos de los requisitos de información de error del cliente. Para obtener un ejemplo más completo, consulte la sección Ejemplo.

Nota

Si especifica un FaultException<TDetail> donde el parámetro type es , System.Stringel valor de cadena se asigna a la propiedad Detail de la aplicación cliente; los clientes no pueden recuperar esa cadena llamando al FaultException<TDetail>.ToString método . Para que se devuelva el valor de la cadena cuando la aplicación cliente llama a Exception.ToString, se inicia una excepción System.ServiceModel.FaultException dentro de la operación y se pasa la cadena al constructor.

Para controlar explícitamente el comportamiento de la aplicación cuando se produce una excepción o FaultException<TDetail> se produce, implemente la System.ServiceModel.Dispatcher.IErrorHandler interfaz en o System.ServiceModel.Description.IEndpointBehavior System.ServiceModel.Description.IServiceBehavior System.ServiceModel.Description.IContractBehavior y asígnela a la ChannelDispatcher.ErrorHandlers propiedad . IErrorHandler permite controlar explícitamente el error soap que se genera y si se devuelve al cliente.

Para facilitar la depuración, establezca en ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true en el código o puede usar en ServiceDebugBehavior.IncludeExceptionDetailInFaults un archivo de configuración de aplicación. Cuando se habilita, el servicio devuelve automáticamente información de excepción al autor de la llamada. Estos errores aparecen en el cliente como FaultException excepciones.

Importante

Dado que las excepciones administradas pueden exponer información interna de la aplicación, establecer ServiceBehaviorAttribute.IncludeExceptionDetailInFaults o ServiceDebugBehavior.IncludeExceptionDetailInFaults para true permitir que los clientes WCF obtengan información sobre las excepciones de operaciones de servicio internas, incluida la identificación personal u otra información confidencial.

Por consiguiente, establecer ServiceBehaviorAttribute.IncludeExceptionDetailInFaults o ServiceDebugBehavior.IncludeExceptionDetailInFaults en true solo está recomendado como una manera de depurar temporalmente una aplicación de servicio. Además, el WSDL de un método que devuelve excepciones administradas no controladas de esta manera no contiene el contrato para la FaultException<TDetail> de tipo String. Los clientes deben esperar la posibilidad de un error SOAP desconocido (devuelto a los clientes WCF como System.ServiceModel.FaultException objetos) para obtener la información de depuración correctamente.

Constructores

FaultContractAttribute(Type)

Inicializa una nueva instancia de la clase FaultContractAttribute.

Propiedades

Action	Obtiene o establece la acción del mensaje de error de SOAP que se especifica como parte del contrato de la operación.
DetailType	Obtiene el tipo de un objeto serializable que contiene información de error.
HasProtectionLevel	Obtiene un valor que indica si el mensaje de error de SOAP tiene un nivel de protección asignado.
Name	Obtiene o establece el nombre del mensaje de error en el Lenguaje de descripción de servicios Web (WSDL).
Namespace	Obtiene o establece el espacio de nombres del error de SOAP.
ProtectionLevel	Especifica el nivel de protección que el error de SOAP requiere del enlace.
TypeId	Cuando se implementa en una clase derivada, obtiene un identificador único para este Attribute. (Heredado de Attribute)

Métodos

Equals(Object)	Devuelve un valor que indica si esta instancia es igual que un objeto especificado. (Heredado de Attribute)
GetHashCode()	Devuelve el código hash de esta instancia. (Heredado de Attribute)
GetType()	Obtiene el Type de la instancia actual. (Heredado de Object)
IsDefaultAttribute()	Si se reemplaza en una clase derivada, indica si el valor de esta instancia es el valor predeterminado de la clase derivada. (Heredado de Attribute)
Match(Object)	Cuando se invalida en una clase derivada, devuelve un valor que indica si esta instancia es igual a un objeto especificado. (Heredado de Attribute)
MemberwiseClone()	Crea una copia superficial del Object actual. (Heredado de Object)
ToString()	Devuelve una cadena que representa el objeto actual. (Heredado de Object)

Implementaciones de interfaz explícitas

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Asigna un conjunto de nombres a un conjunto correspondiente de identificadores de envío. (Heredado de Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)	Obtiene la información de tipos de un objeto, que puede utilizarse para obtener la información de tipos de una interfaz. (Heredado de Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Recupera el número de interfaces de información de tipo que proporciona un objeto (0 ó 1). (Heredado de Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)	Proporciona acceso a las propiedades y los métodos expuestos por un objeto. (Heredado de Attribute)

Se aplica a

FaultContractAttribute Clase

Definición

Ejemplos

Comentarios

Constructores

Propiedades

Métodos

Implementaciones de interfaz explícitas

Se aplica a

Recursos adicionales