FaultContractAttribute Classe

Définition

Espace de noms:

System.ServiceModel

Assemblys:

System.ServiceModel.dll, System.ServiceModel.Primitives.dll

Paquet:

System.ServiceModel.Primitives v10.0.652802

Source:

FaultContractAttribute.cs

Spécifie une ou plusieurs erreurs 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 montre l’utilisation de FaultContractAttribute pour spécifier que l’opération SampleMethod peut retourner une erreur SOAP avec le type de détail 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

L’exemple de code suivant montre que les clients WCF de ISampleService l’expérience 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 gérées, les erreurs de traitement sont représentées par Exception des objets. 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 à partir 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é que les opérations de service utilisent pour FaultContractAttribute 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 savoir sont retournées dans une erreur 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.

• Namespace Les Name propriétés 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.

Avertissement

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 ProtectionLevel ou ProtectionLevel.EncryptAndSignProtectionLevel.Sign l’autre valeur, 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 ProtectionLevel propriété n’importe où sur le contrat, toutes les données d’application sont chiffrées et signées.

• Si vous sélectionnez une liaison qui n’a pas de sécurité 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 donnée de l’application n’est protégée.

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

Pour renvoyer une erreur spécifiée à partir d’une opération marquée avec FaultContractAttribute, lèvez un FaultException<TDetail> (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ù le typeparameter est les informations d’erreur sérialisables). Il FaultContractAttribute peut être utilisé uniquement 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.

Note

Vous pouvez utiliser n’importe quel type sérialisable pour transmettre des informations d’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 de la DataContractSerializer 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.

Note

Les exemples de code suivants ne définissent pas les propriétés ou NameNamespace les ProtectionLevelproprié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 nouveau FaultException<TDetail> paramètre de type où le paramètre de type est le type qui contient les informations d’erreur (dans le cas ci-dessus, a Int32). Par 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 transmises à 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 relatives aux informations d’erreur du client. Pour obtenir un exemple plus complet, consultez la section Exemple.

Note

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, lèvez une System.ServiceModel.FaultException exception à l’intérieur de l’opération et transmettez 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 la valeur true dans le ServiceBehaviorAttribute.IncludeExceptionDetailInFaults code ou vous pouvez l’utiliser ServiceDebugBehavior.IncludeExceptionDetailInFaults dans un fichier de configuration d’application. Lorsqu’il est activé, le service retourne automatiquement les informations d’exception à l’appelant. Ces erreurs apparaissent au client en tant qu’exceptions FaultException .

Important

Étant donné que les exceptions managées peuvent exposer des informations internes de l'application, définir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults peut permettre aux clients WCF d'obtenir des informations sur les exceptions des opérations de service internes, y compris des informations personnellement identifiables ou d'autres informations sensibles.

Par conséquent, il est uniquement recommandé de définir ServiceBehaviorAttribute.IncludeExceptionDetailInFaults ou ServiceDebugBehavior.IncludeExceptionDetailInFaults sur true comme un moyen de déboguer temporairement une application de service. En outre, le WSDL pour une méthode qui retourne des exceptions managées non gérées de cette façon ne contient pas le contrat pour le FaultException<TDetail> type String. Les clients doivent s’attendre à la possibilité d’une erreur SOAP inconnue (retournée aux clients WCF en tant qu’objets System.ServiceModel.FaultException ) pour obtenir correctement les informations de débogage.

Constructeurs

Nom	Description
FaultContractAttribute(Type)	Initialise une nouvelle instance de la classe FaultContractAttribute.

Propriétés

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