FaultContractAttribute Classe

Definizione

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

Ereditarietà

Object

Attribute

FaultContractAttribute

Attributi

AttributeUsageAttribute

Esempio

Nell'esempio di codice seguente viene illustrato come utilizzare l'attributo FaultContractAttribute per specificare che l'operazione SampleMethod può restituire un errore SOAP contente informazioni dettagliate di tipo 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

Nell'esempio di codice seguente viene illustrato che i client WCF di ISampleService riscontrano questo errore SOAP come 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

Commenti

Contrassegnare un'operazione con l'attributo FaultContractAttribute per dichiarare una o più condizioni di eccezione specifiche aggiunte alla descrizione WSDL (Web Service Description Language) dell'operazione del servizio come messaggi di errore SOAP espliciti restituiti dall'operazione.

Tutte le applicazioni gestite prevedono che gli errori di elaborazione siano rappresentati dagli oggetti Exception. Nelle applicazioni basate su SOAP, ad esempio applicazioni Windows Communication Foundation (WCF), i metodi del servizio comunicano le informazioni sugli errori di elaborazione tramite messaggi di errore SOAP. Poiché le applicazioni WCF vengono eseguite in entrambi i tipi di sistemi di errore, tutte le informazioni sulle eccezioni gestite che devono essere inviate al client devono essere convertite da eccezioni in errori SOAP. È possibile utilizzare i comportamenti predefiniti delle eccezioni di servizio. In alternativa, è possibile stabilire in modo esplicito se convertire le eccezioni in messaggi di errore e, in tal caso, definire le modalità di conversione. Per una panoramica delle eccezioni e degli errori SOAP nelle applicazioni WCF, vedere Specifica e gestione degli errori in Contratti e servizi.

È consigliabile che le operazioni del servizio usino per FaultContractAttribute specificare formalmente tutti gli errori SOAP che un client può aspettarsi di ricevere nel corso normale di un'operazione. Per ridurre al minimo la divulgazione delle informazioni è inoltre consigliabile che negli errori SOAP vengano restituite soltanto le informazioni che il client deve conoscere.

• La Action proprietà controlla l'azione del messaggio di errore.

• La DetailType proprietà ottiene il tipo dell'oggetto dettaglio serializzato nel messaggio di errore.

• Le Name proprietà e Namespace controllano rispettivamente il nome e lo spazio dei nomi del messaggio di errore.

• Indica HasProtectionLevel se il messaggio di errore ha un livello di protezione specificato e, in tal caso, la ProtectionLevel proprietà controlla tale livello di protezione.

• Se si imposta in modo esplicito ProtectionLevel.Sign su ProtectionLevel o ProtectionLevel.EncryptAndSign, è necessario usare un'associazione con sicurezza abilitata usando la System.ServiceModel.SecurityMode proprietà sull'associazione o viene generata un'eccezione.

• Se si seleziona un'associazione protetta e non si imposta la proprietà ProtectionLevel nel contratto, tutti i dati dell'applicazione verranno crittografati e firmati.

• Se si seleziona un'associazione che non dispone di sicurezza abilitata (ad esempio, la System.ServiceModel.BasicHttpBinding sicurezza è disabilitata per impostazione predefinita) e non ProtectionLevel è impostata in modo esplicito, nessuno dei dati dell'applicazione verrà protetto.

Per molti scenari l'impostazione ProtectionLevel su EncryptAndSign per i messaggi di errore è sufficiente. Per altri dettagli, vedere Informazioni sul livello di protezione.

Per restituire un errore specificato da un'operazione contrassegnata con FaultContractAttribute, generare un'eccezione FaultException<TDetail> (dove il parametro di tipo è le informazioni sugli errori serializzabili) quando l'eccezione gestita si verifica durante l'operazione. Le applicazioni client WCF esevolvono l'errore SOAP dello stesso tipo generato nell'implementazione del client, ovvero come in FaultException<TDetail> (dove il typeparameter è le informazioni sugli errori serializzabili). Può FaultContractAttribute essere utilizzato solo per specificare gli errori SOAP per le operazioni a due vie e per le coppie di operazioni asincrone. Le operazioni unidirezionale non supportano gli errori SOAP e pertanto non supportano FaultContractAttribute.

Ad esempio, per specificare che i client possono prevedere un errore SOAP che contiene un Int32parametro di tipo nel FaultContractAttribute metodo del servizio.

[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

Nel metodo del servizio generare quindi un nuovo FaultException<TDetail> elemento in cui il parametro di tipo è il tipo che contiene le informazioni sull'errore (nel caso precedente, un ).Int32 Ad esempio:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

L'esempio precedente è molto semplice; quasi tutte le informazioni possono essere passate usando un System.Int32 codice, quindi questo tipo di dettaglio non è il più utile. In genere, le applicazioni WCF specificano errori SOAP con tipi di dettagli specifici per i requisiti relativi alle informazioni sugli errori del client. Per un esempio più esaustivo, vedere la sezione degli esempi.

Per controllare in modo esplicito il comportamento dell'applicazione quando viene generata un'eccezione o FaultException<TDetail> viene generata, implementare l'interfaccia System.ServiceModel.Dispatcher.IErrorHandler in un System.ServiceModel.Description.IServiceBehaviorSystem.ServiceModel.Description.IContractBehavior oggetto o System.ServiceModel.Description.IEndpointBehavior e assegnarla alla ChannelDispatcher.ErrorHandlers proprietà . IErrorHandler consente di controllare in modo esplicito l'errore SOAP generato e se inviarlo al client.

Per facilitare il debug, impostare su ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true nel codice oppure usare ServiceDebugBehavior.IncludeExceptionDetailInFaults in un file di configurazione dell'applicazione. Quando abilitato, il servizio restituisce automaticamente al chiamante le informazioni sull'eccezione. Questi errori vengono visualizzati nel client come FaultException eccezioni.

Costruttori

Proprietà

Metodi

Implementazioni dell'interfaccia esplicita

Si applica a