FaultContractAttribute FaultContractAttribute FaultContractAttribute FaultContractAttribute Class

Définition

Spécifie une ou plusieurs fautes SOAP retournées lorsqu'une opération de service rencontre des erreurs de traitement.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
Héritage
FaultContractAttributeFaultContractAttributeFaultContractAttributeFaultContractAttribute
Attributs

Exemples

L'exemple de code suivant illustre l'utilisation de FaultContractAttribute pour spécifier que l'opération SampleMethod peut retourner une erreur SOAP avec le type de détail 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

L’exemple de code suivant montre que les clients WCF de ISampleService rencontrent cette erreur SOAP comme FaultException<TDetail> de type 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

Remarques

Marquez une opération avec l'attribut FaultContractAttribute pour déclarer une ou plusieurs conditions d'exception spécifiques ajoutées à la description WSDL (Web Service Description Language) de l'opération de service comme messages d'erreur SOAP explicites retournés par l'opération.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.

Dans toutes les applications managées, les erreurs de traitement sont représentées par des objets Exception.In all managed applications, processing errors are represented by Exception objects. Dans les applications basées sur SOAP telles que les applications Windows Communication Foundation (WCF), les méthodes de service communiquent les informations d’erreur à l’aide de messages d’erreur SOAP.In SOAP-based applications such as Windows Communication Foundation (WCF) applications, service methods communicate processing error information using SOAP fault messages. Étant donné que les applications WCF s’exécutent sous les deux types de systèmes d’erreur, toutes les informations sur les exceptions managées qui doivent être envoyées au client doivent être converties des exceptions en erreurs 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. Vous pouvez utiliser les comportements d'exception de service par défaut ou vous pouvez contrôler explicitement si (et comment) les exceptions sont mappées aux messages d'erreur.You can use the default service exception behaviors, or you can explicitly control whether -- and how -- exceptions are mapped to fault messages. Pour obtenir une vue d’ensemble des exceptions et des erreurs SOAP dans les applications WCF, consultez spécification et gestion des erreurs dans les contrats et les services.For an overview of exceptions and SOAP faults in WCF applications, see Specifying and Handling Faults in Contracts and Services.

Il est recommandé que les opérations de service utilisent l'FaultContractAttribute pour spécifier de manière formelle toutes les fautes SOAP qu'un client peut s'attendre à recevoir dans le cours normal d'une opération.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. Il est également recommandé que seules les informations qu'un client doit connaître soient retournées dans une faute SOAP pour réduire la divulgation d'informations.It is also recommended that only that information a client must know is returned in a SOAP fault to minimize information disclosure.

  • La propriété Action contrôle l'action du message d'erreur.The Action property controls the action of the fault message.

  • La propriété DetailType obtient le type de l'objet de détail sérialisé dans le message d'erreur.The DetailType property gets the type of the detail object serialized in the fault message.

  • Les propriétés Name et Namespace contrôlent respectivement le nom et l'espace de noms du message d'erreur.The Name and Namespace properties control the name and namespace, respectively, of the fault message.

  • Le HasProtectionLevel indique si le message d'erreur a un niveau de protection spécifié, et si c'est le cas, la propriété ProtectionLevel contrôle ce niveau de protection.The HasProtectionLevel indicates whether the fault message has a protection level specified, and if so, the ProtectionLevel property controls that level of protection.

Attention

Si un message d'erreur contient des informations qui sont sensibles ou peuvent provoquer des problèmes de sécurité, il est fortement recommandé que la propriété ProtectionLevel soit définie.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.

Pour de nombreux scénarios, il est suffisant d'affecter ProtectionLevel à EncryptAndSign pour les messages d'erreur.For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. Pour plus d’informations, consultez comprendre le niveau de protection.For more details, see Understanding Protection Level.

Pour retourner une erreur spécifiée d’une opération marquée avec FaultContractAttribute, levez une exception FaultException<TDetail> (où les informations sérialisables sur l’erreur sont le paramètre de type) lorsque l’exception managée se produit pendant l’opération.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. Les applications clientes WCF surveillent l’erreur SOAP comme étant le même type que celui qui a été levée dans l’implémentation cliente, c’est-à-dire en tant que FaultException<TDetail> (où typeparameter est l’information d’erreur sérialisable).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). L'FaultContractAttribute peut être utilisé uniquement pour spécifier les fautes SOAP pour les opérations de service bidirectionnelles et les paires d'opérations asynchrones ; les opérations unidirectionnelles ne prennent pas en charge les fautes SOAP et ne prennent donc pas en charge 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.

Notes

Vous pouvez utiliser tout type sérialisable pour transmettre des informations sur l'erreur.You can use any serializable type to convey error information. La seule restriction dans cette version de WCF est que les types spécifiés dans un FaultContractAttribute doivent être sérialisables par le 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. Pour la prise en charge de la sérialisation, la DataContractSerializer fournit, consultez sérialiseur de contrat de données.For the serialization support the DataContractSerializer provides, see Data Contract Serializer.

Par exemple, pour spécifier que les clients peuvent attendre une erreur SOAP qui contient un Int32, placez ce paramètre de type dans l’FaultContractAttribute sur votre méthode de service.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.

Notes

Les exemples de code suivants ne définissent pas les propriétés 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

Ensuite, dans votre méthode de service, levez une nouvelle FaultException<TDetail> où le paramètre de type est le type qui contient les informations sur l’erreur (dans le cas ci-dessus, un 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). Par exemple :For example:

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

L’exemple précédent est très élémentaire ; presque toutes les informations peuvent être passées à l’aide d’un code System.Int32, ce type de détail n’est donc pas le plus utile.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. En règle générale, les applications WCF spécifient des erreurs SOAP avec les types de détails spécifiques aux spécifications d’informations d’erreur du client.Typically, WCF applications specify SOAP faults with detail types specific to the error information requirements of the client. Pour obtenir un exemple plus complet, consultez la section Exemple.For a more complete example, see the Example section.

Notes

Si vous spécifiez une FaultException<TDetail> où le paramètre de type est une System.String, la valeur de chaîne est assignée à la propriété Detail dans l’application cliente ; les clients ne peuvent pas récupérer cette chaîne en appelant la méthode 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. Pour que la valeur de chaîne soit retournée lorsque l'application cliente appelle Exception.ToString, levez une exception System.ServiceModel.FaultException dans l'opération et passez la chaîne au constructeur.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.

Pour contrôler explicitement le comportement de l'application lorsqu'une exception ou FaultException<TDetail> est levé, implémentez l'interface System.ServiceModel.Dispatcher.IErrorHandler sur un System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior ou System.ServiceModel.Description.IEndpointBehavior et assignez-la à la propriété 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 vous permet de contrôler explicitement l’erreur SOAP générée et s’il faut la renvoyer au client.IErrorHandler enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

Pour faciliter le débogage, affectez la ServiceBehaviorAttribute.IncludeExceptionDetailInFaults à true dans le code ou vous pouvez utiliser le ServiceDebugBehavior.IncludeExceptionDetailInFaults dans un fichier de configuration de l’application.To facilitate debugging, set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults to true in code or you can use the ServiceDebugBehavior.IncludeExceptionDetailInFaults in an application configuration file. En cas d'activation, le service retourne automatiquement les informations sur les exceptions à l'appelant.When enabled, the service automatically returns exception information to the caller. Ces erreurs apparaissent au client sous forme d'exceptions FaultException.These faults appear to the client as FaultException exceptions.

Important

Étant donné que les exceptions managées peuvent exposer des informations d’application internes, la définition de ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults à true peut permettre aux clients WCF d’obtenir des informations sur les exceptions d’opération de service interne, y compris l’identification personnelle ou d’autres éléments sensibles informations.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.

Par conséquent, l'affectation de la valeur ServiceBehaviorAttribute.IncludeExceptionDetailInFaults à ServiceDebugBehavior.IncludeExceptionDetailInFaults ou true est uniquement recommandée comme une façon de déboguer temporairement une application de service.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is only recommended as a way of temporarily debugging a service application. De plus, le WSDL pour une méthode qui retourne des exceptions managées non prises en charge de cette façon ne contient pas le contrat pour le FaultException<TDetail> de type 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. Les clients doivent attendre une erreur SOAP inconnue (retournée aux clients WCF en tant qu’objets System.ServiceModel.FaultException) pour obtenir correctement les informations de débogage.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.

Constructeurs

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

Initialise une nouvelle instance de la classe FaultContractAttribute.Initializes a new instance of the FaultContractAttribute class.

Propriétés

Action Action Action Action

Obtient ou définit l'action du message d'erreur SOAP spécifié dans le cadre du contrat d'opération.Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

DetailType DetailType DetailType DetailType

Obtient le type d'un objet sérialisable qui contient des informations sur l'erreur.Gets the type of a serializable object that contains error information.

HasProtectionLevel HasProtectionLevel HasProtectionLevel HasProtectionLevel

Obtient une valeur qui indique si un niveau de protection a été assigné au message d'erreur SOAP.Gets a value that indicates whether the SOAP fault message has a protection level assigned.

Name Name Name Name

Obtient ou définit le nom du message d'erreur dans WSDL (Web Services Description Language).Gets or sets the name of the fault message in Web Services Description Language (WSDL).

Namespace Namespace Namespace Namespace

Obtient ou définit l'espace de noms de l'erreur SOAP.Gets or sets the namespace of the SOAP fault.

ProtectionLevel ProtectionLevel ProtectionLevel ProtectionLevel

Spécifie le niveau de protection que l'erreur SOAP requiert de la liaison.Specifies the level of protection the SOAP fault requires from the binding.

TypeId TypeId TypeId TypeId

Lors de l'implémentation dans une classe dérivée, obtient un identificateur unique pour l'objet Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Inherited from Attribute)

Méthodes

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

Retourne une valeur qui indique si cette instance est égale à un objet spécifié.Returns a value that indicates whether this instance is equal to a specified object.

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

Retourne le code de hachage de cette instance.Returns the hash code for this instance.

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

Obtient le Type de l'instance actuelle.Gets the Type of the current instance.

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

En cas de substitution dans une classe dérivée, indique si la valeur de cette instance est la valeur par défaut pour la classe dérivée.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)

En cas de substitution dans une classe dérivée, retourne une valeur indiquant si cette instance équivaut à un objet spécifié.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()

Crée une copie superficielle de l'objet Object actuel.Creates a shallow copy of the current Object.

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

Retourne une chaîne qui représente l'objet actuel.Returns a string that represents the current object.

(Inherited from Object)

Implémentations d’interfaces explicites

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

Mappe un jeu de noms avec un jeu correspondant d'identificateurs de dispatch.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)

Récupère les informations de type pour un objet, qui peuvent être utilisées pour obtenir les informations de type d'une 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)

Récupère le nombre d'interfaces d'informations de type fourni par un objet (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)

Fournit l'accès aux propriétés et aux méthodes exposées par un objet.Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

S’applique à