FaultContractAttribute Klasse

Referenz

Definition

Namespace:: System.ServiceModel

Assembly:: System.ServiceModel.Primitives.dll

Assembly:: System.ServiceModel.dll

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Gibt einen oder mehrere SOAP-Fehler an, die zurückgegeben werden, wenn bei einem Dienstvorgang ein Verarbeitungsfehler festgestellt werden.

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

Vererbung: Object

Attribute
FaultContractAttribute

Attribute: AttributeUsageAttribute

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie mit dem FaultContractAttribute angegeben werden kann, dass der SampleMethod-Vorgang einen SOAP-Fehler mit dem Detailtyp GreetingFault zurückgeben kann.

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

Im folgenden Codebeispiel wird gezeigt, dass WCF-Clients ISampleService dieses SOAP-Fehlers als Typ FaultException<TDetail> GreetingFaulterleben.

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

Hinweise

Markieren Sie einen Vorgang mit dem FaultContractAttribute Attribut, um eine oder mehrere bestimmte Ausnahmebedingungen zu deklarieren, die der Beschreibung der Web Service Description Language (WSDL) des Dienstvorgangs als explizite SOAP-Fehlernachrichten hinzugefügt werden, die vom Vorgang zurückgegeben werden.

In allen verwalteten Anwendungen werden Verarbeitungsfehler durch Exception-Objekte dargestellt. In SOAP-basierten Anwendungen wie Windows Communication Foundation (WCF)-Anwendungen kommunizieren Dienstmethoden die Verarbeitung von Fehlerinformationen mithilfe von SOAP-Fehlernachrichten. Da WCF-Anwendungen unter beiden Arten von Fehlersystemen ausgeführt werden, müssen alle verwalteten Ausnahmeinformationen, die an den Client gesendet werden müssen, aus Ausnahmen in SOAP-Fehler konvertiert werden. Sie können die Standard-Dienstausnahmeverhalten verwenden oder aber ausdrücklich steuern, ob und wie Ausnahmen zu Fehlernachrichten zugewiesen werden. Eine Übersicht über Ausnahmen und SOAP-Fehler in WCF-Anwendungen finden Sie unter Angeben und Behandeln von Fehlern in Verträgen und Diensten.

Es wird empfohlen, dass Dienstvorgänge FaultContractAttribute alle SOAP-Fehler angeben, die ein Client im normalen Verlauf eines Vorgangs erhalten kann. Es wird außerdem empfohlen, dass nur die Informationen, die ein Client erhalten muss, in einem SOAP-Fehler zurückgegeben werden, um die Offenlegung von Informationen möglichst gering zu halten.

Die Action Eigenschaft steuert die Aktion der Fehlermeldung.
Die DetailType Eigenschaft ruft den Typ des Detailobjekts in der Fehlermeldung serialisiert ab.
Namespace Die Name Eigenschaften steuern den Namen und den Namespace bzw. den Namen der Fehlermeldung.
Der HasProtectionLevel Gibt an, ob die Fehlermeldung eine Schutzstufe angegeben hat, und falls ja, steuert die ProtectionLevel Eigenschaft die Schutzstufe.

Achtung

Wenn eine Fehlermeldung Informationen enthält, die vertraulich sind oder zu Sicherheitsproblemen führen können, wird dringend empfohlen, dass die ProtectionLevel Eigenschaft festgelegt wird.

Wenn Sie die ProtectionLevel Eigenschaft explizit auf eine ProtectionLevel.Sign oder eine Ausnahme festlegen, ProtectionLevel.EncryptAndSignmüssen Sie eine Bindung mit aktivierter Sicherheit verwenden, indem Sie die Eigenschaft für die System.ServiceModel.SecurityMode Bindung verwenden oder eine Ausnahme ausgelöst wird.
Wählen Sie eine Bindung aus, die Sicherheit aktiviert, und legen Sie im Vertrag keine ProtectionLevel-Eigenschaft fest, werden alle Daten verschlüsselt und signiert.
Wenn Sie eine Bindung auswählen, die keine Sicherheit aktiviert hat (z. B. die System.ServiceModel.BasicHttpBinding Sicherheit ist standardmäßig deaktiviert), und dies ProtectionLevel ist nicht explizit festgelegt, dann wird keine der Anwendungsdaten geschützt.

Für viele Szenarien, die EncryptAndSign für Fehlernachrichten festgelegt ProtectionLevel sind, ist ausreichend. Weitere Details finden Sie unter "Grundlegendes zur Schutzstufe".

Um einen angegebenen Fehler aus einem Vorgang zurückzugeben, der mit FaultContractAttributegekennzeichnet ist, löst einen FaultException<TDetail> (wobei der Typparameter die serialisierbaren Fehlerinformationen ist), wenn die verwaltete Ausnahme während des Vorgangs auftritt. WCF-Clientanwendungen oberflächen den SOAP-Fehler als den gleichen Typ wie in der Clientimplementierung ausgelöst - das heißt, als FaultException<TDetail> (wobei der Typeparameter die serialisierbaren Fehlerinformationen ist). Dies FaultContractAttribute kann nur verwendet werden, um SOAP-Fehler für Zwei-Wege-Dienstvorgänge und für asynchrone Vorgangspaare anzugeben. One-Way-Vorgänge unterstützen KEINE SOAP-Fehler und unterstützen daher keine Unterstützung FaultContractAttribute.

Hinweis

Sie können zur Übermittlung von Fehlerinformationen jeden serialisierbaren Typ verwenden. Die einzige Einschränkung in dieser WCF-Version ist, dass Typen, die in einer FaultContractAttribute Datei angegeben sind, durch die System.Runtime.Serialization.DataContractSerializerserialisierbar sein müssen. Informationen zur Serialisierungsunterstützung finden DataContractSerializer Sie unter Data Contract Serializer.

Wenn Sie beispielsweise angeben möchten, dass Clients einen SOAP-Fehler erwarten können, der einen Int32WERT enthält, platzieren Sie diesen Typparameter in der FaultContractAttribute Dienstmethode.

Hinweis

Die folgenden Codebeispiele legen die ProtectionLevelEigenschaften nicht Namespace fest. Name

[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

Führen Sie dann in Ihrer Dienstmethode einen neuen FaultException<TDetail> Typ aus, in dem der Typparameter der Typ ist, der die Fehlerinformationen enthält (in dem obigen Fall a Int32). Beispiel:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Das vorherige Beispiel ist sehr einfach; fast alle Informationen können mithilfe eines System.Int32 Codes übergeben werden, sodass dieser Detailtyp nicht die nützlichsten ist. In der Regel geben WCF-Anwendungen SOAP-Fehler mit Detailtypen an, die den Fehlerinformationenanforderungen des Clients spezifisch sind. Ein komplexeres Beispiel finden Sie im Beispielabschnitt.

Hinweis

Wenn Sie einen Ort angeben, an dem der Typparameter ein FaultException<TDetail> System.Stringist, wird der Zeichenfolgenwert der Detaileigenschaft in der Clientanwendung zugewiesen. Clients können diese Zeichenfolge nicht abrufen, indem Sie die FaultException<TDetail>.ToString Methode aufrufen. Damit der Zeichenfolgewert zurückgegeben wird, wenn die Clientanwendung Exception.ToString aufruft, lösen Sie im Vorgang eine System.ServiceModel.FaultException-Ausnahme aus, und übergeben Sie die Zeichenfolge dem Konstruktor.

Um das Verhalten der Anwendung explizit zu steuern, wenn eine Ausnahme FaultException<TDetail> oder ausgelöst wird, implementieren Sie die System.ServiceModel.Dispatcher.IErrorHandler Schnittstelle auf einer System.ServiceModel.Description.IContractBehavior System.ServiceModel.Description.IServiceBehavior System.ServiceModel.Description.IEndpointBehavior Oder oder weisen Sie sie der ChannelDispatcher.ErrorHandlers Eigenschaft zu. IErrorHandler ermöglicht Es Ihnen, den SOAP-Fehler explizit zu steuern, der generiert wird und ob sie an den Client gesendet werden soll.

Um das Debuggen zu erleichtern, legen Sie den ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true Code fest, oder Sie können dies ServiceDebugBehavior.IncludeExceptionDetailInFaults in einer Anwendungskonfigurationsdatei verwenden. Bei Aktivierung gibt der Dienst automatisch Ausnahmeinformationen an den Aufrufer zurück. Diese Fehler werden dem Client als FaultException Ausnahmen angezeigt.

Wichtig

Da verwaltete Ausnahmen interne Anwendungsinformationen, Einstellungen ServiceBehaviorAttribute.IncludeExceptionDetailInFaults oder ServiceDebugBehavior.IncludeExceptionDetailInFaults true WCF-Clients ermöglichen können, Informationen zu Ausnahmen des internen Dienstvorgangs zu erhalten, einschließlich personenbezogener oder anderer vertraulicher Informationen.

Daher wird die Festlegung von ServiceBehaviorAttribute.IncludeExceptionDetailInFaults für ServiceDebugBehavior.IncludeExceptionDetailInFaults oder true nur für das vorübergehende Debuggen einer Dienstanwendung empfohlen. Außerdem beinhaltet die WSDL für eine Methode, die nicht behandelte verwaltete Ausnahmen auf diese Weise zurückgibt, keinen Vertrag für die FaultException<TDetail> vom Typ String. Clients müssen die Möglichkeit eines unbekannten SOAP-Fehlers (zurückgegeben an WCF-Clients als System.ServiceModel.FaultException Objekte) erwarten, um die Debuginformationen ordnungsgemäß abzurufen.

Konstruktoren

FaultContractAttribute(Type)

Initialisiert eine neue Instanz der FaultContractAttribute-Klasse.

Eigenschaften

Action	Ruft die Aktion der SOAP-Fehlernachricht ab, die als Bestandteil des Vorgangsvertrags angegeben wurde, oder legt sie fest.
DetailType	Ruft den Typ eines serialisierbaren Objekts ab, das Fehlerinformationen enthält.
HasProtectionLevel	Ruft einen Wert ab, der angibt, ob der SOAP-Fehlernachricht eine Sicherheitsebene zugewiesen wurde.
Name	Ruft ab oder legt den Namen der Fehlernachricht in WSDL (Web Services Description Language) fest.
Namespace	Ruft den Namespace des SOAP-Fehlers ab oder legt diesen fest.
ProtectionLevel	Gibt die Sicherheitsebene an, die der SOAP-Fehler von der Bindung fordert.
TypeId	Ruft bei Implementierung in einer abgeleiteten Klasse einen eindeutigen Bezeichner für dieses Attribute ab. (Geerbt von Attribute)

Methoden

Equals(Object)	Gibt einen Wert zurück, der angibt, ob diese Instanz gleich einem angegebenen Objekt ist. (Geerbt von Attribute)
GetHashCode()	Gibt den Hashcode für diese Instanz zurück. (Geerbt von Attribute)
GetType()	Ruft den Type der aktuellen Instanz ab. (Geerbt von Object)
IsDefaultAttribute()	Gibt beim Überschreiben in einer abgeleiteten Klasse an, ob der Wert der Instanz der Standardwert für die abgeleitete Klasse ist. (Geerbt von Attribute)
Match(Object)	Beim Überschreiben in einer abgeleiteten Klasse wird ein Wert zurückgegeben, der angibt, ob diese Instanz einem bestimmten Objekt entspricht. (Geerbt von Attribute)
MemberwiseClone()	Erstellt eine flache Kopie des aktuellen Object. (Geerbt von Object)
ToString()	Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt. (Geerbt von Object)

Explizite Schnittstellenimplementierungen

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Ordnet eine Reihe von Namen einer entsprechenden Reihe von Dispatchbezeichnern zu. (Geerbt von Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)	Ruft die Typinformationen für ein Objekt ab, mit deren Hilfe die Typinformationen für eine Schnittstelle abgerufen werden können. (Geerbt von Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Ruft die Anzahl der Schnittstellen mit Typinformationen ab, die von einem Objekt bereitgestellt werden (0 oder 1). (Geerbt von Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)	Stellt den Zugriff auf von einem Objekt verfügbar gemachte Eigenschaften und Methoden bereit. (Geerbt von Attribute)

Gilt für

FaultContractAttribute Klasse

Definition

Beispiele

Hinweise

Konstruktoren

Eigenschaften

Methoden

Explizite Schnittstellenimplementierungen

Gilt für

Zusätzliche Ressourcen