FaultContractAttribute Classe

Riferimento

Definizione

Spazio dei nomi:: System.ServiceModel

Assembly:: System.ServiceModel.Primitives.dll

Assembly:: System.ServiceModel.dll

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Consente di specificare uno o più errori SOAP da restituire quando un'operazione di servizio rileva errori di elaborazione.

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.

Attenzione

Se un messaggio di errore contiene informazioni sensibili o che possono causare problemi di sicurezza, è consigliabile impostare la ProtectionLevel proprietà.

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.

Nota

Per trasmettere le informazioni sull'errore è possibile utilizzare qualsiasi tipo serializzabile. L'unica restrizione in questa versione di WCF è che i tipi specificati in un FaultContractAttribute oggetto devono essere serializzabili da System.Runtime.Serialization.DataContractSerializer. Per il supporto DataContractSerializer della serializzazione fornito, vedere Serializzatore di contratti dati.

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

Nota

Gli esempi di codice seguenti non impostano le ProtectionLevelproprietà , Nameo Namespace .

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

Nota

Se si specifica un FaultException<TDetail> oggetto in cui il parametro di tipo è un System.String, il valore stringa viene assegnato alla proprietà Detail nell'applicazione client. I client non possono recuperare tale stringa chiamando il FaultException<TDetail>.ToString metodo . Per fare in modo che il valore della stringa venga restituito quando l'applicazione client chiama il metodo Exception.ToString è sufficiente generare un'eccezione System.ServiceModel.FaultException nell'operazione e passare la stringa al costruttore.

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

Importante

Poiché le eccezioni gestite possono esporre informazioni interne sull'applicazione, l'impostazione ServiceBehaviorAttribute.IncludeExceptionDetailInFaults o ServiceDebugBehavior.IncludeExceptionDetailInFaults per true consentire ai client WCF di ottenere informazioni sulle eccezioni delle operazioni interne del servizio, incluse le informazioni personali o altre informazioni riservate.

Di conseguenza, l'impostazione della proprietà ServiceBehaviorAttribute.IncludeExceptionDetailInFaults o della proprietà ServiceDebugBehavior.IncludeExceptionDetailInFaults su true è consigliabile solo come modalità temporanea di debug di un'applicazione di servizio. Inoltre, il codice WSDL di un metodo che restituisce in questo modo eccezioni gestite senza tuttavia gestirle non contiene il contratto dell'eccezione FaultException<TDetail> di tipo String. I client devono prevedere la possibilità di un errore SOAP sconosciuto (restituito ai client WCF come System.ServiceModel.FaultException oggetti) per ottenere correttamente le informazioni di debug.

Costruttori

FaultContractAttribute(Type)

Inizializza una nuova istanza della classe FaultContractAttribute.

Proprietà

Action	Consente di ottenere o impostare l'azione del messaggio di errore SOAP specificato come parte del contratto dell'operazione.
DetailType	Consente di ottenere il tipo di un oggetto serializzabile contenente le informazioni sull'errore.
HasProtectionLevel	Ottiene un valore che indica se al messaggio di errore SOAP è stato assegnato un livello di protezione.
Name	Consente di ottenere o impostare il nome del messaggio di errore in WSDL (Web Services Description Language).
Namespace	Consente di ottenere o impostare lo spazio dei nomi dell'errore SOAP.
ProtectionLevel	Consente di specificare il livello di protezione che l'associazione deve applicare all'errore SOAP.
TypeId	Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute. (Ereditato da Attribute)

Metodi

Equals(Object)	Restituisce un valore che indica se questa istanza è uguale a un oggetto specificato. (Ereditato da Attribute)
GetHashCode()	Restituisce il codice hash per l'istanza. (Ereditato da Attribute)
GetType()	Ottiene l'oggetto Type dell'istanza corrente. (Ereditato da Object)
IsDefaultAttribute()	In caso di override in una classe derivata, indica se il valore di questa istanza è il valore predefinito per la classe derivata. (Ereditato da Attribute)
Match(Object)	Quando è sottoposto a override in una classe derivata, restituisce un valore che indica se questa istanza equivale a un oggetto specificato. (Ereditato da Attribute)
MemberwiseClone()	Crea una copia superficiale dell'oggetto Object corrente. (Ereditato da Object)
ToString()	Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object)

Implementazioni dell'interfaccia esplicita

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Esegue il mapping di un set di nomi a un set corrispondente di ID dispatch. (Ereditato da Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)	Recupera le informazioni sul tipo relative a un oggetto, che possono essere usate per ottenere informazioni sul tipo relative a un'interfaccia. (Ereditato da Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Recupera il numero delle interfacce di informazioni sul tipo fornite da un oggetto (0 o 1). (Ereditato da Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)	Fornisce l'accesso a proprietà e metodi esposti da un oggetto. (Ereditato da Attribute)

Si applica a

FaultContractAttribute Classe

Definizione

Esempio

Commenti

Costruttori

Proprietà

Metodi

Implementazioni dell'interfaccia esplicita

Si applica a

Risorse aggiuntive