FaultContractAttribute Classe

Référence

Définition

Espace de noms:: System.ServiceModel

Assembly:: System.ServiceModel.Primitives.dll

Assembly:: System.ServiceModel.dll

Important

Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Spécifie une ou plusieurs fautes SOAP retournées lorsqu'une opération de service rencontre des erreurs de traitement.

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

Héritage: Object

Attribute
FaultContractAttribute

Attributs: AttributeUsageAttribute

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.

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 l’expérience ISampleService de cette erreur SOAP en tant que FaultException<TDetail> 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 en tant que messages d’erreur SOAP explicites retournés par l’opération.

Dans toutes les applications managées, les erreurs de traitement sont représentées par des objets Exception. Dans les applications SOAP telles que les applications Windows Communication Foundation (WCF), les méthodes de service communiquent les informations d’erreur de traitement à l’aide de messages d’erreur SOAP. Étant donné que les applications WCF s’exécutent sous les deux types de systèmes d’erreur, toutes les informations d’exception managées qui doivent être envoyées au client doivent être converties d’exceptions en erreurs SOAP. 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. 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.

Il est recommandé d’utiliser les FaultContractAttribute opérations de service pour spécifier formellement toutes les erreurs SOAP qu’un client peut s’attendre à recevoir dans le cours normal d’une opération. 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.

La Action propriété contrôle l’action du message d’erreur.
La DetailType propriété obtient le type de l’objet de détail sérialisé dans le message d’erreur.
Les Name propriétés et Namespace le nom contrôlent respectivement le nom et l’espace de noms du message d’erreur.
Indique HasProtectionLevel si le message d’erreur a un niveau de protection spécifié et, le cas échéant, la ProtectionLevel propriété contrôle ce niveau de protection.

Attention

Si un message d’erreur contient des informations sensibles ou peut entraîner des problèmes de sécurité, il est fortement recommandé de définir la ProtectionLevel propriété.

Si vous définissez explicitement l’une ou ProtectionLevel.EncryptAndSignl’autre ProtectionLevel.Sign ProtectionLevel, vous devez utiliser une liaison avec la sécurité activée à l’aide de la System.ServiceModel.SecurityMode propriété sur la liaison ou une exception est levée.
Si vous sélectionnez une liaison qui active la sécurité et que vous ne définissez pas la propriété ProtectionLevel à quelque endroit du contrat, toutes les données d’application seront chiffrées et signées.
Si vous sélectionnez une liaison dont la sécurité n’est pas activée (par exemple, la System.ServiceModel.BasicHttpBinding sécurité est désactivée par défaut) et que celle-ci ProtectionLevel n’est pas définie explicitement, aucune des données de l’application n’est protégée.

Pour de nombreux scénarios, la définition ProtectionLevel des messages d’erreur EncryptAndSign est suffisante. Pour plus d’informations, consultez Présentation du niveau de protection.

Pour retourner une erreur spécifiée à partir d’une opération marquée avec FaultContractAttribute, lèvez une FaultException<TDetail> exception (où le paramètre de type est les informations d’erreur sérialisables) lorsque l’exception managée se produit pendant l’opération. Les applications clientes WCF mettent en évidence l’erreur SOAP comme le même type que celui qui a été levée dans l’implémentation du client, c’est-à-dire en tant que FaultException<TDetail> (où les paramètres de type sont les informations d’erreur sérialisables). Il FaultContractAttribute ne peut être utilisé que pour spécifier des erreurs SOAP pour les opérations de service bidirectionnelles et pour les paires d’opérations asynchrones ; les opérations unidirectionnelles ne prennent pas en charge les erreurs SOAP et ne prennent donc pas en charge FaultContractAttribute.

Notes

Vous pouvez utiliser tout type sérialisable pour transmettre des informations sur l'erreur. La seule restriction dans cette version de WCF est que les types spécifiés dans un FaultContractAttribute doit être sérialisable par le System.Runtime.Serialization.DataContractSerializer. Pour la prise en charge DataContractSerializer de la sérialisation, consultez Le sérialiseur de contrat de données.

Par exemple, pour spécifier que les clients peuvent s’attendre à une erreur SOAP qui contient un Int32paramètre de type dans la FaultContractAttribute méthode de service.

Notes

Les exemples de code suivants ne définissent pas les propriétés ou Namespace les ProtectionLevel Namepropriétés.

[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, lèvez un nouvel FaultException<TDetail> emplacement où le paramètre de type est le type qui contient les informations d’erreur (dans le cas ci-dessus, a Int32). Exemple :

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

L’exemple précédent est très simple ; presque toutes les informations peuvent être passées à l’aide d’un System.Int32 code, de sorte que ce type de détail n’est pas le plus utile. En règle générale, les applications WCF spécifient des erreurs SOAP avec des types de détails spécifiques aux exigences d’informations d’erreur du client. Pour obtenir un exemple plus complet, consultez la section Exemple.

Notes

Si vous spécifiez un FaultException<TDetail> emplacement où le paramètre de type est un System.String, la valeur de chaîne est affectée à la propriété Detail dans l’application cliente ; les clients ne peuvent pas récupérer cette chaîne en appelant la FaultException<TDetail>.ToString méthode. 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.

Pour contrôler explicitement le comportement de l’application lorsqu’une exception ou FaultException<TDetail> est levée, implémentez l’interface System.ServiceModel.Dispatcher.IErrorHandler sur un System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior ou System.ServiceModel.Description.IEndpointBehavior affectez-la à la ChannelDispatcher.ErrorHandlers propriété. IErrorHandler vous permet de contrôler explicitement l’erreur SOAP générée et de le renvoyer au client.

Pour faciliter le débogage, définissez-le dans le ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true code ou vous pouvez l’utiliser ServiceDebugBehavior.IncludeExceptionDetailInFaults dans un fichier de configuration d’application. En cas d'activation, le service retourne automatiquement les informations sur les exceptions à l'appelant. Ces erreurs apparaissent au client comme FaultException des exceptions.

Important

Étant donné que les exceptions gérées peuvent exposer des informations d’application interne, définir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults true autoriser les clients WCF à obtenir des informations sur les exceptions d’opération de service interne, y compris l’identification personnelle ou d’autres informations sensibles.

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. 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. Les clients doivent s’attendre à ce qu’une erreur SOAP inconnue (retournée aux clients WCF en tant qu’objets System.ServiceModel.FaultException ) obtienne correctement les informations de débogage.

Constructeurs

FaultContractAttribute(Type)

Initialise une nouvelle instance de la classe FaultContractAttribute.

Propriétés

Action	Obtient ou définit l'action du message d'erreur SOAP spécifié dans le cadre du contrat d'opération.
DetailType	Obtient le type d'un objet sérialisable qui contient des informations sur l'erreur.
HasProtectionLevel	Obtient une valeur qui indique si un niveau de protection a été assigné au message d'erreur SOAP.
Name	Obtient ou définit le nom du message d'erreur dans WSDL (Web Services Description Language).
Namespace	Obtient ou définit l'espace de noms de l'erreur SOAP.
ProtectionLevel	Spécifie le niveau de protection que l'erreur SOAP requiert de la liaison.
TypeId	Lors de l'implémentation dans une classe dérivée, obtient un identificateur unique pour l'objet Attribute. (Hérité de Attribute)

Méthodes

Equals(Object)	Retourne une valeur qui indique si cette instance est égale à un objet spécifié. (Hérité de Attribute)
GetHashCode()	Retourne le code de hachage de cette instance. (Hérité de Attribute)
GetType()	Obtient le Type de l'instance actuelle. (Hérité de Object)
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. (Hérité de Attribute)
Match(Object)	En cas de substitution dans une classe dérivée, retourne une valeur indiquant si cette instance équivaut à un objet spécifié. (Hérité de Attribute)
MemberwiseClone()	Crée une copie superficielle du Object actuel. (Hérité de Object)
ToString()	Retourne une chaîne qui représente l'objet actuel. (Hérité de Object)

Implémentations d’interfaces explicites

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Mappe un jeu de noms avec un jeu correspondant d'identificateurs de dispatch. (Hérité de Attribute)
_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. (Hérité de Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Récupère le nombre d'interfaces d'informations de type fourni par un objet (0 ou 1). (Hérité de Attribute)
_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. (Hérité de Attribute)

S’applique à

FaultContractAttribute Classe

Définition

Exemples

Remarques

Constructeurs

Propriétés

Méthodes

Implémentations d’interfaces explicites

S’applique à

Ressources supplémentaires