FaultContractAttribute Klasa

Definicja

Przestrzeń nazw:

System.ServiceModel

Zestaw:

System.ServiceModel.Primitives.dll

Zestaw:

System.ServiceModel.dll

Określa co najmniej jedną usterkę protokołu SOAP zwracaną, gdy operacja usługi napotka błędy przetwarzania.

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

Dziedziczenie

Object

Attribute

FaultContractAttribute

Atrybuty

AttributeUsageAttribute

Przykłady

Poniższy przykład kodu pokazuje użycie FaultContractAttribute metody , aby określić, że SampleMethod operacja może zwrócić błąd PROTOKOŁU SOAP z typem szczegółów .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

Poniższy przykład kodu pokazuje, że klienci programu WCF, którzy doświadczają tego błędu ISampleService protokołu SOAP jako FaultException<TDetail> typu 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

Uwagi

Oznacz operację z atrybutem FaultContractAttribute w celu zadeklarowania co najmniej jednego określonego warunków wyjątku, które są dodawane do opisu języka WSDL (Web Service Description Language) operacji usługi jako jawne komunikaty o błędach protokołu SOAP zwrócone przez operację.

We wszystkich zarządzanych aplikacjach błędy przetwarzania są reprezentowane przez Exception obiekty. W aplikacjach opartych na protokole SOAP, takich jak aplikacje Windows Communication Foundation (WCF), metody usług komunikują się z przetwarzaniem informacji o błędach przy użyciu komunikatów o błędach protokołu SOAP. Ponieważ aplikacje WCF są wykonywane w obu typach systemów błędów, wszelkie informacje o wyjątkach zarządzanych, które muszą być wysyłane do klienta, muszą zostać przekonwertowane z wyjątków na błędy protokołu SOAP. Możesz użyć domyślnych zachowań wyjątków usługi lub jawnie kontrolować, czy - i jak - wyjątki są mapowane na komunikaty o błędach. Aby zapoznać się z omówieniem wyjątków i błędów protokołu SOAP w aplikacjach WCF, zobacz Określanie i obsługa błędów w kontraktach i usługach.

Zaleca się, aby operacje usługi używały metody , FaultContractAttribute aby formalnie określić wszystkie błędy protokołu SOAP, które klient może oczekiwać w normalnym przebiegu operacji. Zaleca się również, aby tylko informacje, które klient musi wiedzieć, jest zwracany w błędze protokołu SOAP, aby zminimalizować ujawnienie informacji.

• Właściwość Action kontroluje akcję komunikatu o błędzie.

• Właściwość DetailType pobiera typ obiektu szczegółów serializowanego w komunikacie o błędzie.

• Właściwości Name i Namespace kontrolują odpowiednio nazwę i przestrzeń nazw komunikatu o błędzie.

• Wskazuje HasProtectionLevel , czy komunikat o błędzie ma określony poziom ochrony, a jeśli tak, ProtectionLevel właściwość kontroluje ten poziom ochrony.

Przestroga

Jeśli komunikat o błędzie zawiera informacje poufne lub może prowadzić do problemów z zabezpieczeniami, zdecydowanie zaleca ProtectionLevel się ustawienie właściwości.

• Jeśli jawnie ustawisz ProtectionLevel wartość lub ProtectionLevel.Sign ProtectionLevel.EncryptAndSign, musisz użyć powiązania z włączonymi zabezpieczeniami przy użyciu System.ServiceModel.SecurityMode właściwości powiązania lub zostanie zgłoszony wyjątek.

• Jeśli wybierzesz powiązanie, które włącza zabezpieczenia i nie ustawisz ProtectionLevel właściwości w dowolnym miejscu kontraktu, wszystkie dane aplikacji zostaną zaszyfrowane i podpisane.

• Jeśli wybierzesz powiązanie, które nie ma włączonego zabezpieczeń (na przykład System.ServiceModel.BasicHttpBinding zabezpieczenia są domyślnie wyłączone), a ProtectionLevel ustawienie nie jest jawnie ustawione, żadne dane aplikacji nie będą chronione.

W przypadku wielu scenariuszy ustawienie wartości ProtectionLevel dla EncryptAndSign komunikatów o błędach jest wystarczające. Aby uzyskać więcej informacji, zobacz Understanding Protection Level (Opis poziomu ochrony).

Aby zwrócić określoną usterkę z operacji oznaczonej FaultContractAttributeza pomocą polecenia , należy zgłosić FaultException<TDetail> (gdzie parametr typu jest serializowalnymi informacjami o błędzie), gdy podczas operacji wystąpi wyjątek zarządzany. Aplikacje klienckie WCF uwidocznić błąd PROTOKOŁU SOAP co ten sam typ, co został zgłoszony w implementacji klienta — czyli jako FaultException<TDetail> (gdzie parametr typeparameter to informacje o błędzie z możliwością serializacji). Może FaultContractAttribute służyć tylko do określania błędów protokołu SOAP dla operacji usługi dwukierunkowej i dla par operacji asynchronicznych; operacje jednokierunkowe nie obsługują błędów PROTOKOŁU SOAP i dlatego nie obsługują FaultContractAttribute.

Uwaga

Aby przekazać informacje o błędach, można użyć dowolnego typu serializacji. Jedynym ograniczeniem w tej wersji programu WCF jest to, że typy określone w elemecie FaultContractAttribute muszą być serializowalne przez System.Runtime.Serialization.DataContractSerializerprogram . Aby uzyskać obsługę DataContractSerializer serializacji zapewnia, zobacz Serializator kontraktu danych.

Aby na przykład określić, że klienci mogą oczekiwać błędu PROTOKOŁU SOAP zawierającego Int32parametr typu , umieść ten parametr typu w FaultContractAttribute metodzie usługi.

Uwaga

Poniższe przykłady kodu nie ustawiają ProtectionLevelwłaściwości , Namelub 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

Następnie w metodzie usługi wyrzuć nowyFaultException<TDetail>, gdzie parametr typu jest typem zawierającym informacje o błędzie (w powyższym przypadku ).Int32 Przykład:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Powyższy przykład jest bardzo podstawowy; prawie wszystkie informacje mogą być przekazywane przy użyciu System.Int32 kodu, więc ten typ szczegółów nie jest najbardziej przydatny. Zazwyczaj aplikacje WCF określają błędy protokołu SOAP ze szczegółowymi typami specyficznymi dla wymagań dotyczących informacji o błędach klienta. Aby uzyskać bardziej kompletny przykład, zobacz sekcję Przykład.

Uwaga

Jeśli określisz FaultException<TDetail> , gdzie parametr typu to System.String, wartość ciągu zostanie przypisana do właściwości Detail w aplikacji klienckiej; klienci nie mogą pobrać tego ciągu przez wywołanie FaultException<TDetail>.ToString metody . Aby wartość ciągu została zwrócona, gdy aplikacja kliencka wywołuje Exception.ToStringmetodę System.ServiceModel.FaultException , należy zgłosić wyjątek wewnątrz operacji i przekazać ciąg do konstruktora.

Aby jawnie kontrolować zachowanie aplikacji, gdy jest zgłaszany wyjątek lub FaultException<TDetail> jest zgłaszany, zaimplementuj System.ServiceModel.Dispatcher.IErrorHandler interfejs na obiekcie System.ServiceModel.Description.IServiceBehaviorSystem.ServiceModel.Description.IContractBehavior lub System.ServiceModel.Description.IEndpointBehavior i przypisz go do ChannelDispatcher.ErrorHandlers właściwości. IErrorHandler Umożliwia jawne sterowanie wygenerowaną błędem protokołu SOAP i informacją o tym, czy należy wysłać ją z powrotem do klienta.

Aby ułatwić debugowanie, ustaw wartość ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true na w kodzie lub możesz użyć elementu ServiceDebugBehavior.IncludeExceptionDetailInFaults w pliku konfiguracji aplikacji. Po włączeniu usługa automatycznie zwraca informacje o wyjątku do elementu wywołującego. Te błędy są wyświetlane klientowi jako FaultException wyjątki.

Ważne

Ponieważ wyjątki zarządzane mogą uwidaczniać informacje o aplikacji wewnętrznej, ustawienie ServiceBehaviorAttribute.IncludeExceptionDetailInFaults lub ServiceDebugBehavior.IncludeExceptionDetailInFaults true zezwalać klientom WCF na uzyskiwanie informacji o wyjątkach operacji usługi wewnętrznej, w tym danych osobowych lub innych poufnych.

W związku z tym ustawienie lub ServiceDebugBehavior.IncludeExceptionDetailInFaults ustawienie ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true jest zalecane tylko jako sposób tymczasowego debugowania aplikacji usługi. Ponadto język WSDL dla metody zwracającej nieobsługiwane wyjątki zarządzane w ten sposób nie zawiera kontraktu Stringtypu FaultException<TDetail> . Klienci muszą oczekiwać, że w celu poprawnego uzyskania informacji o debugowaniu mogą wystąpić nieznane błędy protokołu SOAP (zwrócone do klientów WCF jako System.ServiceModel.FaultException obiekty).

Konstruktory

FaultContractAttribute(Type)

Inicjuje nowe wystąpienie klasy FaultContractAttribute.

Właściwości

Action	Pobiera lub ustawia akcję komunikatu o błędzie PROTOKOŁU SOAP określonego w ramach kontraktu operacji.
DetailType	Pobiera typ obiektu z możliwością serializacji, który zawiera informacje o błędzie.
HasProtectionLevel	Pobiera wartość wskazującą, czy komunikat o błędzie protokołu SOAP ma przypisany poziom ochrony.
Name	Pobiera lub ustawia nazwę komunikatu o błędzie w języku opisu usług sieci Web (WSDL).
Namespace	Pobiera lub ustawia przestrzeń nazw błędu SOAP.
ProtectionLevel	Określa poziom ochrony, który wymaga błędu PROTOKOŁU SOAP od powiązania.
TypeId	Po zaimplementowaniu w klasie pochodnej pobiera unikatowy identyfikator dla tego Attributeelementu . (Odziedziczone po Attribute)

Metody

Equals(Object)	Zwraca wartość wskazującą, czy to wystąpienie jest równe podanemu obiektowi. (Odziedziczone po Attribute)
GetHashCode()	Zwraca wartość skrótu dla tego wystąpienia. (Odziedziczone po Attribute)
GetType()	Type Pobiera wartość bieżącego wystąpienia. (Odziedziczone po Object)
IsDefaultAttribute()	W przypadku zastąpienia w klasie pochodnej wskazuje, czy wartość tego wystąpienia jest wartością domyślną klasy pochodnej. (Odziedziczone po Attribute)
Match(Object)	Po przesłonięciu w klasie pochodnej zwraca wartość wskazującą, czy to wystąpienie jest równe określonemu obiektowi. (Odziedziczone po Attribute)
MemberwiseClone()	Tworzy płytkią kopię bieżącego Objectelementu . (Odziedziczone po Object)
ToString()	Zwraca ciąg reprezentujący bieżący obiekt. (Odziedziczone po Object)

Jawne implementacje interfejsu

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Zestaw nazw jest mapowany na odpowiedni zestaw identyfikatorów wysyłania. (Odziedziczone po Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)	Pobiera informacje o typie dla obiektu, który może służyć do pobierania informacji o typie dla interfejsu. (Odziedziczone po Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Pobiera informację o liczbie typów interfejsów, jakie zawiera obiekt (0 lub 1). (Odziedziczone po Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)	Umożliwia dostęp do właściwości i metod udostępnianych przez obiekt. (Odziedziczone po Attribute)