FaultContractAttribute Třída

Reference

Definice

Obor názvů:: System.ServiceModel

Sestavení:: System.ServiceModel.Primitives.dll

Sestavení:: System.ServiceModel.dll

Důležité

Některé informace platí pro předběžně vydaný produkt, který se může zásadně změnit, než ho výrobce nebo autor vydá. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Určuje jednu nebo více chyb PROTOKOLU SOAP, které se vrátí, když operace služby narazí na chyby zpracování.

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

Dědičnost: Object

Attribute
FaultContractAttribute

Atributy: AttributeUsageAttribute

Příklady

Následující příklad kódu ukazuje použití FaultContractAttribute k určení, že SampleMethod operace může vrátit chybu SOAP s typem podrobností 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

Následující příklad kódu ukazuje, že klienti WCF této ISampleService chyby 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

Poznámky

Označte operaci atributem FaultContractAttribute , která deklaruje jednu nebo více konkrétních podmínek výjimky, které se přidají do popisu jazyka WSDL (Web Service Description Language) operace služby jako explicitní chybové zprávy SOAP vrácené operací.

Ve všech spravovaných aplikacích jsou chyby zpracování reprezentovány Exception objekty. V aplikacích založených na protokolu SOAP, jako jsou aplikace WCF (Windows Communication Foundation), metody služby komunikují o zpracování informací o chybách pomocí chybových zpráv PROTOKOLU SOAP. Vzhledem k tomu, že aplikace WCF se spouští v obou typech chybových systémů, musí být všechny informace o spravovaných výjimkách, které je nutné odeslat klientovi, převedeny z výjimek na chyby PROTOKOLU SOAP. Můžete použít výchozí chování výjimek služby, nebo můžete explicitně řídit, jestli jsou výjimky - a jak - mapovány na chybové zprávy. Přehled výjimek a chyb SOAP v aplikacích WCF naleznete v tématu Určení a zpracování chyb v kontraktech a službách.

Doporučuje se, aby operace služby používaly FaultContractAttribute k formálnímu určení všech chyb SOAP, které klient může očekávat, že bude v normálním průběhu operace přijímat. Doporučuje se také, aby se informace, které klient musí znát, vrátily v chybě PROTOKOLU SOAP, aby se minimalizovalo zpřístupnění informací.

Vlastnost Action řídí akci chybové zprávy.
Vlastnost DetailType získá typ detail objekt serializované v chybové zprávě.
Vlastnosti Name řídí Namespace název a obor názvů chybové zprávy v uvedeném pořadí.
Určuje HasProtectionLevel , zda má chybová zpráva zadanou úroveň ochrany, a pokud ano, ProtectionLevel vlastnost řídí tuto úroveň ochrany.

Upozornění

Pokud chybová zpráva obsahuje citlivé informace nebo může vést k problémům se zabezpečením, důrazně doporučujeme ProtectionLevel nastavit vlastnost.

Pokud explicitně nastavíte ProtectionLevel buď nebo ProtectionLevel.Sign ProtectionLevel.EncryptAndSign, musíte použít vazbu s povoleným zabezpečením pomocí System.ServiceModel.SecurityMode vlastnosti vazby nebo je vyvolán výjimka.
Pokud vyberete vazbu, která umožňuje zabezpečení a nenastavíte ProtectionLevel vlastnost nikde ve smlouvě, všechna data aplikace budou zašifrována a podepsána.
Pokud vyberete vazbu, která nemá povolené zabezpečení (například System.ServiceModel.BasicHttpBinding ve výchozím nastavení je zakázáno zabezpečení) a ProtectionLevel není explicitně nastavená, nebudou chráněna žádná data aplikace.

Pro mnoho scénářů je ProtectionLevel EncryptAndSign nastavení pro chybové zprávy dostačující. Další podrobnosti najdete v tématu Principy úrovně ochrany.

Pokud chcete vrátit zadanou chybu z operace označené pomocí FaultContractAttribute, vyvoláte FaultException<TDetail> (kde parametr typu je serializovatelné informace o chybě), když během operace dojde ke spravované výjimce. Klientské aplikace WCF zobrazí chybu SOAP jako stejný typ, který byl vyvolán v implementaci klienta – to znamená FaultException<TDetail> jako (kde typeparameter je serializovatelné informace o chybě). Lze FaultContractAttribute použít pouze k určení chyb PROTOKOLU SOAP pro obousměrné operace služby a pro asynchronní dvojice operací; jednosměrné operace nepodporují chyby SOAP, a proto nepodporují FaultContractAttribute.

Poznámka

K předávání informací o chybách můžete použít libovolný serializovatelný typ. Jediným omezením v této verzi WCF je, že typy zadané v a FaultContractAttribute musí být serializovatelné pomocí System.Runtime.Serialization.DataContractSerializer. Informace o podpoře DataContractSerializer serializace naleznete v tématu Data Contract Serializer.

Pokud chcete například určit, že klienti mohou očekávat chybu PROTOKOLU SOAP obsahující Int32parametr typu do FaultContractAttribute metody služby.

Poznámka

Následující příklady kódu nenastavují ProtectionLevel, Nameani Namespace vlastnosti.

[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

Pak ve vaší metodě služby vyvoláte novou FaultException<TDetail> , kde parametr typu je typ, který obsahuje informace o chybě (ve výše uvedeném případě a Int32). Příklad:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Předchozí příklad je velmi základní; téměř všechny informace lze předat pomocí System.Int32 kódu, takže tento typ podrobností není nejužitečnější. Aplikace WCF obvykle určují chyby SOAP s typy podrobností specifické pro požadavky na informace o chybách klienta. Podrobnější příklad najdete v části Příklad.

Poznámka

Pokud zadáte FaultException<TDetail> , kde je parametr System.Stringtypu , řetězcová hodnota je přiřazena vlastnosti Detail v klientské aplikaci; klienti nemohou tento řetězec načíst voláním FaultException<TDetail>.ToString metody. Pokud chcete, aby se hodnota řetězce vrátila při volání Exception.ToStringklientské aplikace , vyvolá výjimku System.ServiceModel.FaultException uvnitř operace a předejte řetězec konstruktoru.

Chcete-li explicitně řídit chování aplikace při výjimce nebo FaultException<TDetail> je vyvolán, implementujte System.ServiceModel.Dispatcher.IErrorHandler rozhraní na System.ServiceModel.Description.IServiceBehaviornebo System.ServiceModel.Description.IEndpointBehavior System.ServiceModel.Description.IContractBehavior a přiřaďte ji vlastnostiChannelDispatcher.ErrorHandlers. IErrorHandler umožňuje explicitně řídit chybu PROTOKOLU SOAP, která je vygenerována a zda ji odeslat zpět klientovi.

Chcete-li usnadnit ladění, nastavte ServiceBehaviorAttribute.IncludeExceptionDetailInFaults na true kód nebo můžete použít ServiceDebugBehavior.IncludeExceptionDetailInFaults konfigurační soubor aplikace. Pokud je tato služba povolená, automaticky vrátí volajícímu informace o výjimce. Tyto chyby se klientovi zobrazují jako FaultException výjimky.

Důležité

Vzhledem k tomu, že spravované výjimky můžou zpřístupnit interní informace o aplikacích, nastavení ServiceBehaviorAttribute.IncludeExceptionDetailInFaults nebo ServiceDebugBehavior.IncludeExceptionDetailInFaults true umožnit klientům WCF získat informace o výjimkách interních operací služby, včetně identifikovatelných osobních údajů nebo jiných citlivých informací.

Proto se nastavení ServiceBehaviorAttribute.IncludeExceptionDetailInFaults nebo ServiceDebugBehavior.IncludeExceptionDetailInFaults nastavení true doporučuje pouze jako způsob dočasného ladění aplikace služby. Kromě toho WSDL pro metodu, která vrací neošetřené spravované výjimky tímto způsobem neobsahuje kontrakt pro FaultException<TDetail> typ String. Klienti musí očekávat, že možnost neznámé chyby SOAP (vrácená klientům WCF jako System.ServiceModel.FaultException objekty) získá správně informace o ladění.

Konstruktory

FaultContractAttribute(Type)

Inicializuje novou instanci FaultContractAttribute třídy.

Vlastnosti

Action	Získá nebo nastaví akci chybové zprávy PROTOKOLU SOAP, která je určena jako součást kontraktu operace.
DetailType	Získá typ serializovatelné objektu, který obsahuje informace o chybě.
HasProtectionLevel	Získá hodnotu, která označuje, zda má chybová zpráva SOAP přiřazenou úroveň ochrany.
Name	Získá nebo nastaví název chybové zprávy ve webové služby Description Language (WSDL).
Namespace	Získá nebo nastaví obor názvů chyby SOAP.
ProtectionLevel	Určuje úroveň ochrany, kterou chyba SOAP vyžaduje z vazby.
TypeId	Při implementaci v odvozené třídě získá jedinečný identifikátor pro tento Attribute. (Zděděno od Attribute)

Metody

Equals(Object)	Vrací hodnotu, která určuje, zda je tato instance rovna zadanému objektu. (Zděděno od Attribute)
GetHashCode()	Vrátí hodnotu hash pro tuto instanci. (Zděděno od Attribute)
GetType()	Type Získá aktuální instanci. (Zděděno od Object)
IsDefaultAttribute()	Při přepsání v odvozené třídě určuje, zda hodnota této instance je výchozí hodnotou odvozené třídy. (Zděděno od Attribute)
Match(Object)	Při přepsání v odvozené třídě vrátí hodnotu, která označuje, zda se tato instance rovná zadanému objektu. (Zděděno od Attribute)
MemberwiseClone()	Vytvoří použádnou kopii aktuálního souboru Object. (Zděděno od Object)
ToString()	Vrátí řetězec, který představuje aktuální objekt. (Zděděno od Object)

Explicitní implementace rozhraní

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)	Mapuje sadu názvů na odpovídající sadu identifikátorů pro rozesílání. (Zděděno od Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)	Načte informace o typu objektu, který lze použít k získání informací o typu rozhraní. (Zděděno od Attribute)
_Attribute.GetTypeInfoCount(UInt32)	Získá počet rozhraní typu informací, které objekt poskytuje (0 nebo 1). (Zděděno od Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)	Poskytuje přístup k vlastnostem a metodám vystaveným objektem. (Zděděno od Attribute)

Platí pro

FaultContractAttribute Třída

Definice

Příklady

Poznámky

Konstruktory

Vlastnosti

Metody

Explicitní implementace rozhraní

Platí pro

Další materiály