FaultContractAttribute FaultContractAttribute FaultContractAttribute FaultContractAttribute Class

Definizione

Consente di specificare uno o più errori SOAP da restituire quando un'operazione di servizio rileva errori di elaborazione.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
Ereditarietà
FaultContractAttributeFaultContractAttributeFaultContractAttributeFaultContractAttribute
Attributi

Esempi

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

Esempio di codice seguente mostra che i client WCF di ISampleService verificarsi questo errore SOAP come un FaultException<TDetail> di tipo 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
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

L'attributo FaultContractAttribute può essere utilizzato contrassegnare un'operazione di servizio al fine di dichiarare una o più condizioni di eccezione specifiche aggiunte alla descrizione WSDL (Web Service Description Language) dell'operazione come messaggi di errore SOAP espliciti restituiti dall'operazione.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.

Tutte le applicazioni gestite prevedono che gli errori di elaborazione siano rappresentati dagli oggetti Exception.In all managed applications, processing errors are represented by Exception objects. Nelle applicazioni basate su SOAP, ad esempio le applicazioni di Windows Communication Foundation (WCF), informazioni sugli errori di elaborazione tramite messaggi di errore SOAP vengono comunicate dai metodi di servizio.In SOAP-based applications such as Windows Communication Foundation (WCF) applications, service methods communicate processing error information using SOAP fault messages. Poiché le applicazioni WCF vengono eseguite con entrambi i tipi di sistemi di errore, eventuali informazioni sulle eccezioni gestite che devono essere inviati al client devono essere convertite da eccezioni in errori 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. È 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.You can use the default service exception behaviors, or you can explicitly control whether -- and how -- exceptions are mapped to fault messages. Per una panoramica di eccezioni ed errori SOAP in applicazioni WCF, vedere se si specifica e gestione degli errori in contratti e servizi.For an overview of exceptions and SOAP faults in WCF applications, see Specifying and Handling Faults in Contracts and Services.

È consigliabile che le operazioni di servizio utilizzino l'attributo FaultContractAttribute per specificare formalmente tutti gli errori SOAP che un client prevede di ricevere durante il normale funzionamento di un'operazione.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. Per ridurre al minimo la divulgazione delle informazioni è inoltre consigliabile che negli errori SOAP vengano restituite soltanto le informazioni che il client deve conoscere.It is also recommended that only that information a client must know is returned in a SOAP fault to minimize information disclosure.

  • La proprietà Action controlla l'azione del messaggio di errore.The Action property controls the action of the fault message.

  • La proprietà DetailType consente di ottenere il tipo dell'oggetto dettaglio serializzato contenuto nel messaggio di errore.The DetailType property gets the type of the detail object serialized in the fault message.

  • Le proprietà Name e Namespace controllano rispettivamente il nome e lo spazio dei nomi del messaggio di errore.The Name and Namespace properties control the name and namespace, respectively, of the fault message.

  • La proprietà HasProtectionLevel indica se per il messaggio di errore è stato specificato un livello di protezione e, in tal caso, la proprietà ProtectionLevel controlla tale livello di protezione.The HasProtectionLevel indicates whether the fault message has a protection level specified, and if so, the ProtectionLevel property controls that level of protection.

Attenzione

Se un messaggio di errore contiene informazioni riservate o può comportare problemi di sicurezza, è consigliabile impostare la proprietà ProtectionLevel.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.

In molti casi per proteggere i messaggi di errore è sufficiente impostare la proprietà ProtectionLevel su EncryptAndSign.For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. Per altre informazioni, vedere Understanding Protection Level.For more details, see Understanding Protection Level.

Affinché un'operazione contrassegnata con l'attributo FaultContractAttribute restituisca un determinato errore quando durante l'operazione si verifica un'eccezione gestita è possibile generare un'eccezione FaultException<TDetail> in cui il parametro di tipo corrisponde alle informazioni sull'errore serializzabile.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. Le applicazioni client WCF della superficie di attacco dell'errore SOAP come lo stesso tipo perché è stata generata nell'implementazione client, vale a dire, come un FaultException<TDetail> (dove il typeparameter rappresenta le informazioni sull'errore serializzabile).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'attributo FaultContractAttribute può essere utilizzato solo per specificare errori SOAP relativi a operazioni di servizio bidirezionali e a coppie di operazioni asincrone. Le operazioni unidirezionali non supportano gli errori SOAP e pertanto non supportano l'attributo 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.

Nota

Per trasmettere le informazioni sull'errore è possibile utilizzare qualsiasi tipo serializzabile.You can use any serializable type to convey error information. L'unica restrizione in questa versione di WCF è che i tipi specificati una FaultContractAttribute deve essere serializzabile dal 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. Per il supporto della serializzazione di DataContractSerializer offre, vedere serializzatore dei contratti dati.For the serialization support the DataContractSerializer provides, see Data Contract Serializer.

Ad esempio, per specificare che i client possono ricevere un errore SOAP contenente un elemento di tipo Int32 è sufficiente includere tale parametro di tipo nell'attributo FaultContractAttribute del metodo di servizio.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.

Nota

Negli esempi di codice seguenti le proprietà ProtectionLevel, Name e Namespace non vengono impostate.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

Nel metodo di servizio è quindi possibile generare una nuova eccezione FaultException<TDetail> in cui il parametro di tipo corrisponde al tipo contenente le informazioni sull'errore. Nell'esempio precedente, tale tipo è 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). Ad esempio:For example:

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

L'esempio precedente è molto semplice. Poiché il tipo System.Int32 consente di passare quasi qualsiasi tipo di informazione, questo tipo di dettaglio non è molto 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. In genere, le applicazioni WCF specificano errori SOAP con i tipi di dettaglio specifici per i requisiti di informazioni di errore del client.Typically, WCF applications specify SOAP faults with detail types specific to the error information requirements of the client. Per un esempio più esaustivo, vedere la sezione degli esempi.For a more complete example, see the Example section.

Nota

Se si specifica un'eccezione FaultException<TDetail> in cui il parametro di tipo è System.String, il valore della stringa è assegnato alla proprietà Detail dell'applicazione client. I client non possono recuperare tale stringa chiamando il metodo 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. 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.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.

Per controllare in modo esplicito il comportamento dell'applicazione quando viene generata un'eccezione o un'eccezione FaultException<TDetail>, implementare l'interfaccia System.ServiceModel.Dispatcher.IErrorHandler su un comportamento System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior o System.ServiceModel.Description.IEndpointBehavior e quindi assegnarla alla proprietà 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 Consente di controllare in modo esplicito l'errore SOAP generato e stabilire se inviarlo al client.IErrorHandler enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

Per facilitare il debug, impostare il ServiceBehaviorAttribute.IncludeExceptionDetailInFaults al true nel codice oppure è possibile usare il ServiceDebugBehavior.IncludeExceptionDetailInFaults in un file di configurazione dell'applicazione.To facilitate debugging, set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults to true in code or you can use the ServiceDebugBehavior.IncludeExceptionDetailInFaults in an application configuration file. Quando abilitato, il servizio restituisce automaticamente al chiamante le informazioni sull'eccezione.When enabled, the service automatically returns exception information to the caller. Il client considera questi errori come eccezioni FaultException.These faults appear to the client as FaultException exceptions.

Importante

Poiché le eccezioni gestite possono esporre informazioni interne dell'applicazione, se si imposta ServiceBehaviorAttribute.IncludeExceptionDetailInFaults oppure ServiceDebugBehavior.IncludeExceptionDetailInFaults a true può consentire ai client WCF per ottenere informazioni sulle eccezioni delle operazioni di servizio interno, tra cui personale informazioni personali o comunque riservate.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.

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.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is only recommended as a way of temporarily debugging a service application. 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.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. 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.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.

Costruttori

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

Inizializza una nuova istanza della classe FaultContractAttribute.Initializes a new instance of the FaultContractAttribute class.

Proprietà

Action Action Action Action

Consente di ottenere o impostare l'azione del messaggio di errore SOAP specificato come parte del contratto dell'operazione.Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

DetailType DetailType DetailType DetailType

Consente di ottenere il tipo di un oggetto serializzabile contenente le informazioni sull'errore.Gets the type of a serializable object that contains error information.

HasProtectionLevel HasProtectionLevel HasProtectionLevel HasProtectionLevel

Ottiene un valore che indica se al messaggio di errore SOAP è stato assegnato un livello di protezione.Gets a value that indicates whether the SOAP fault message has a protection level assigned.

Name Name Name Name

Consente di ottenere o impostare il nome del messaggio di errore in WSDL (Web Services Description Language).Gets or sets the name of the fault message in Web Services Description Language (WSDL).

Namespace Namespace Namespace Namespace

Consente di ottenere o impostare lo spazio dei nomi dell'errore SOAP.Gets or sets the namespace of the SOAP fault.

ProtectionLevel ProtectionLevel ProtectionLevel ProtectionLevel

Consente di specificare il livello di protezione che l'associazione deve applicare all'errore SOAP.Specifies the level of protection the SOAP fault requires from the binding.

TypeId TypeId TypeId TypeId

Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Inherited from Attribute)

Metodi

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

Restituisce un valore che indica se questa istanza è uguale a un oggetto specificato.Returns a value that indicates whether this instance is equal to a specified object.

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

Restituisce il codice hash per l'istanza.Returns the hash code for this instance.

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

Ottiene l'oggetto Type dell'istanza corrente.Gets the Type of the current instance.

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

In caso di override in una classe derivata, indica se il valore di questa istanza è il valore predefinito per la classe derivata.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)

Quando è sottoposto a override in una classe derivata, restituisce un valore che indica se questa istanza equivale a un oggetto specificato.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()

Crea una copia superficiale dell'oggetto Object corrente.Creates a shallow copy of the current Object.

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

Restituisce una stringa che rappresenta l'oggetto corrente.Returns a string that represents the current object.

(Inherited from Object)

Implementazioni dell'interfaccia esplicita

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

Esegue il mapping di un set di nomi a un set corrispondente di ID 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)

Recupera le informazioni sul tipo relative a un oggetto, che possono essere usate per ottenere informazioni sul tipo relative a un'interfaccia.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)

Recupera il numero delle interfacce di informazioni sul tipo fornite da un oggetto (0 o 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)

Fornisce l'accesso a proprietà e metodi esposti da un oggetto.Provides access to properties and methods exposed by an object.

(Inherited from Attribute)

Si applica a