FaultContractAttribute FaultContractAttribute FaultContractAttribute FaultContractAttribute Class

Definición

Especifica uno o más errores de SOAP que se devuelven cuando se producen errores de procesamiento en una operación de servicio.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
Herencia
FaultContractAttributeFaultContractAttributeFaultContractAttributeFaultContractAttribute
Atributos

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.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

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

Comentarios

Marque una operación con el atributo FaultContractAttribute para declarar una o varias condiciones de excepción específicas que se agregarán a la descripción del Lenguaje de descripción de servicios Web (WSDL) correspondiente a la operación de servicio como mensajes de error de SOAP explícitos devueltos por la operación.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.

En todas las aplicaciones administradas, los errores de procesamiento están representados mediante objetos Exception.In all managed applications, processing errors are represented by Exception objects. En aplicaciones basadas en SOAP, como las aplicaciones de Windows Communication Foundation (WCF), los métodos de servicio comunican la información de errores de procesamiento mediante mensajes de error de SOAP.In SOAP-based applications such as Windows Communication Foundation (WCF) applications, service methods communicate processing error information using SOAP fault messages. Dado que las aplicaciones WCF se ejecutan en ambos tipos de sistemas de error, cualquier información de excepción administrada que se deba enviar al cliente debe convertirse de excepciones a errores 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. 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.You can use the default service exception behaviors, or you can explicitly control whether -- and how -- exceptions are mapped to fault messages. Para obtener información general sobre excepciones y errores de SOAP en aplicaciones WCF, vea especificar y controlar errores en contratos y servicios.For an overview of exceptions and SOAP faults in WCF applications, see Specifying and Handling Faults in Contracts and Services.

Se recomienda que las operaciones de servicio utilicen FaultContractAttribute para especificar formalmente todos los errores de SOAP que un cliente puede esperar recibir en el curso normal de una operación.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. 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.It is also recommended that only that information a client must know is returned in a SOAP fault to minimize information disclosure.

  • La propiedad Action controla la acción del mensaje de error.The Action property controls the action of the fault message.

  • La propiedad DetailType obtiene el tipo del objeto de detalle serializado en el mensaje de error.The DetailType property gets the type of the detail object serialized in the fault message.

  • Las propiedades Name y Namespace controlan el nombre y el espacio de nombres, respectivamente, del mensaje de error.The Name and Namespace properties control the name and namespace, respectively, of the fault message.

  • HasProtectionLevel indica si el mensaje de error tiene un nivel de protección especificado y, en ese caso, será la propiedad ProtectionLevel la que lo controle.The HasProtectionLevel indicates whether the fault message has a protection level specified, and if so, the ProtectionLevel property controls that level of protection.

Precaución

Si un mensaje de error contiene información que es confidencial o puede provocar problemas de seguridad, se recomienda encarecidamente que se defina la propiedad 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.

En muchos escenarios, definir ProtectionLevel en EncryptAndSign para los mensajes del error es suficiente.For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. Para obtener más información, consulte Descripción del nivel de protección.For more details, see Understanding Protection Level.

Para devolver un error especificado desde una operación marcada con FaultContractAttribute, inicie una FaultException<TDetail> (donde el parámetro de tipo es la información de error serializable) cuando la excepción administrada se produce durante la operación.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. Las aplicaciones cliente de WCF surfacean el error de SOAP como el mismo tipo que se produjo en la implementación del cliente, es decir, como FaultException<TDetail> (donde typeparameter es la información de error serializable).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 sólo se puede utilizar para especificar los errores de SOAP para las operaciones de servicio bidireccionales y para los pares de operación asincrónica; las operaciones unidireccionales no admiten los errores de SOAP y, por consiguiente, no admiten 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.

Nota

Puede utilizar cualquier tipo serializable para llevar información de error.You can use any serializable type to convey error information. La única restricción en esta versión de WCF es que los tipos especificados en un FaultContractAttribute deben ser serializables por el 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 la compatibilidad con la serialización que proporciona DataContractSerializer, consulte serializador de contrato de datos.For the serialization support the DataContractSerializer provides, see Data Contract Serializer.

Por ejemplo, para especificar que los clientes pueden esperar un error de SOAP que contiene Int32, coloque ese parámetro de tipo en FaultContractAttribute en el método de servicio.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.

Nota

Los ejemplos de código siguientes no definen las propiedades de ProtectionLevel, Name o 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

A continuación, en su método de servicio, inicie un nuevo FaultException<TDetail> donde el parámetro de tipo es el tipo que contiene la información del error (en el caso anterior, 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 ejemplo:For example:

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

El ejemplo anterior es muy básico; se puede pasar casi cualquier tipo de información utilizando un código System.Int32, por lo que este tipo de detalle no es el más ú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, las aplicaciones WCF especifican errores de SOAP con tipos de detalle específicos de los requisitos de información de error del cliente.Typically, WCF applications specify SOAP faults with detail types specific to the error information requirements of the client. Para obtener un ejemplo más completo, consulte la sección Ejemplo.For a more complete example, see the Example section.

Nota

Si especifica FaultException<TDetail> donde el parámetro de tipo es System.String, se asignará el valor de la cadena a la propiedad Detail en la aplicación cliente. Los clientes no pueden recuperar esa cadena llamando al 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 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.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 explícitamente el comportamiento de la aplicación cuando se inicia una excepción o una FaultException<TDetail>, implemente la interfaz System.ServiceModel.Dispatcher.IErrorHandler en un System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior o System.ServiceModel.Description.IEndpointBehavior y asígnesela a la propiedad 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 controlar explícitamente el error de SOAP que se genera y si se devuelve al cliente.IErrorHandler enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

Para facilitar la depuración, establezca el ServiceBehaviorAttribute.IncludeExceptionDetailInFaults en true en el código o puede usar el @no__t 2 en un archivo de configuración de la aplicación.To facilitate debugging, set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults to true in code or you can use the ServiceDebugBehavior.IncludeExceptionDetailInFaults in an application configuration file. Cuando se habilita, el servicio devuelve automáticamente información de excepción al autor de la llamada.When enabled, the service automatically returns exception information to the caller. Estos errores aparecen en el cliente como excepciones FaultException.These faults appear to the client as FaultException exceptions.

Importante

Dado que las excepciones administradas pueden exponer información interna de la aplicación, si se establece ServiceBehaviorAttribute.IncludeExceptionDetailInFaults o ServiceDebugBehavior.IncludeExceptionDetailInFaults en true se puede permitir que los clientes de WCF obtengan información sobre las excepciones internas de operaciones de servicio, incluidos los identificadores personales u otros tipos de datos. informaciones.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.

Por consiguiente, establecer ServiceBehaviorAttribute.IncludeExceptionDetailInFaults o ServiceDebugBehavior.IncludeExceptionDetailInFaults en true solo está recomendado como una manera de depurar temporalmente una aplicación de servicio.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is only recommended as a way of temporarily debugging a service application. 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.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. Los clientes deben esperar la posibilidad de un error de SOAP desconocido (devuelto a los clientes de WCF como objetos System.ServiceModel.FaultException) para obtener la información de depuración correctamente.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.

Constructores

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

Inicializa una nueva instancia de la clase FaultContractAttribute.Initializes a new instance of the FaultContractAttribute class.

Propiedades

Action Action Action Action

Obtiene o establece la acción del mensaje de error de SOAP que se especifica como parte del contrato de la operación.Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

DetailType DetailType DetailType DetailType

Obtiene el tipo de un objeto serializable que contiene información de error.Gets the type of a serializable object that contains error information.

HasProtectionLevel HasProtectionLevel HasProtectionLevel HasProtectionLevel

Obtiene un valor que indica si el mensaje de error de SOAP tiene un nivel de protección asignado.Gets a value that indicates whether the SOAP fault message has a protection level assigned.

Name Name Name Name

Obtiene o establece el nombre del mensaje de error en el Lenguaje de descripción de servicios Web (WSDL).Gets or sets the name of the fault message in Web Services Description Language (WSDL).

Namespace Namespace Namespace Namespace

Obtiene o establece el espacio de nombres del error de SOAP.Gets or sets the namespace of the SOAP fault.

ProtectionLevel ProtectionLevel ProtectionLevel ProtectionLevel

Especifica el nivel de protección que el error de SOAP requiere del enlace.Specifies the level of protection the SOAP fault requires from the binding.

TypeId TypeId TypeId TypeId

Cuando se implementa en una clase derivada, obtiene un identificador único 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)

Devuelve un valor que indica si esta instancia es igual que un objeto especificado.Returns a value that indicates whether this instance is equal to a specified object.

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

Devuelve el código hash de esta instancia.Returns the hash code for this instance.

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

Obtiene el Type de la instancia actual.Gets the Type of the current instance.

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

Si se reemplaza en una clase derivada, indica si el valor de esta instancia es el valor predeterminado de la clase 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)

Cuando se invalida en una clase derivada, devuelve un valor que indica si esta instancia es igual a un 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()

Crea una copia superficial del objeto Object actual.Creates a shallow copy of the current Object.

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

Devuelve una cadena que representa el objeto actual.Returns a string that represents the current object.

(Inherited from Object)

Implementaciones de interfaz explícitas

_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)

Asigna un conjunto de nombres a un conjunto correspondiente de identificadores de enví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)

Obtiene la información de tipos de un objeto, que puede utilizarse para obtener la información de tipos de una interfaz.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)

Recupera el número de interfaces de información de tipo que proporciona un objeto (0 ó 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)

Proporciona acceso a las propiedades y los métodos expuestos por un objeto.Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

Se aplica a