FaultContractAttribute Třída

Definice

Obor názvů:

System.ServiceModel

Sestavení:

System.ServiceModel.dll, System.ServiceModel.Primitives.dll

Balíček:

System.ServiceModel.Primitives v10.0.652802

Zdroj:

FaultContractAttribute.cs

Určuje jednu nebo více chyb PROTOKOLU SOAP, které se vrátí, když při operaci služby dojde k chybám 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 mají zkušenosti s ISampleService touto chybou FaultException<TDetail> SOAP jako 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 specifických podmínek výjimky, které jsou přidány 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í zpracování informací o chybách pomocí chybových zpráv PROTOKOLU SOAP. Vzhledem k tomu, že aplikace WCF se spouštějí v obou typech chybových systémů, všechny informace o spravovaných výjimkách, které se musí odeslat klientovi, musí být převedeny z výjimek na chyby 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 PROTOKOLU SOAP, které klient může očekávat v normálním průběhu operace. Doporučuje se také, aby se v důsledku minimalizace zpřístupnění informací vrátily pouze informace, které musí klient znát, v chybě PROTOKOLU SOAP.

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

• 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ď ProtectionLevel.Sign nebo 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á, žádná data aplikace nebudou chráněna.

Pro mnoho scénářů nastavení ProtectionLevelEncryptAndSign chybových zpráv stačí. Další podrobnosti najdete v tématu Principy úrovně ochrany.

Chcete-li vrátit zadanou chybu z operace označené FaultContractAttributepomocí , vyvolte FaultException<TDetail> (kde parametr typu je serializovatelné informace o chybě), když spravovaná výjimka nastane během operace. Klientské aplikace WCF zobrazí chybu SOAP jako stejný typ, který byl vyvolán v implementaci klienta – to znamená jako FaultException<TDetail> (kde typeparameter je serializovatelné informace o chybě). FaultContractAttribute Lze použít pouze k určení chyb PROTOKOLU SOAP pro obousměrné operace služby a pro páry asynchronních 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 objektu FaultContractAttribute musí být serializovatelné System.Runtime.Serialization.DataContractSerializerpomocí . Podpora serializace DataContractSerializer poskytuje naleznete v tématu Serializátor kontraktu dat.

Chcete-li například určit, že klienti mohou očekávat chybu SOAP, která obsahuje Int32parametr FaultContractAttribute typu v metodě služby.

Poznámka:

Následující příklady kódu nenastavují ProtectionLevelName, nebo 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 v metodě služby vyvolá novou FaultException<TDetail> , kde parametr typu je typ, který obsahuje informace o chybě (v předchozím případě a Int32). Napří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, kde FaultException<TDetail> je System.Stringparametr typu , řetězcová hodnota je přiřazena vlastnosti Detail v klientské aplikaci; klienti nemohou načíst tento řetězec voláním FaultException<TDetail>.ToString metody. Chcete-li, aby se řetězcová hodnota vrátila při volání Exception.ToStringklientské aplikace , vyvolá System.ServiceModel.FaultException výjimku uvnitř operace a předejte řetězec konstruktoru.

Pokud chcete explicitně řídit chování aplikace při výjimce nebo FaultException<TDetail> je vyvolán, implementujte System.ServiceModel.Dispatcher.IErrorHandler rozhraní na objektu System.ServiceModel.Description.IServiceBehaviornebo System.ServiceModel.Description.IContractBehaviorSystem.ServiceModel.Description.IEndpointBehavior jej přiřaďte k ChannelDispatcher.ErrorHandlers vlastnosti. IErrorHandler umožňuje explicitně řídit chybu SOAP, která je vygenerována a zda ji odeslat zpět klientovi.

Pokud chcete usnadnit ladění, nastavte ServiceBehaviorAttribute.IncludeExceptionDetailInFaults hodnotu true v kódu nebo ji můžete použít ServiceDebugBehavior.IncludeExceptionDetailInFaults v konfiguračním souboru aplikace. Pokud je tato služba povolená, volajícímu automaticky vrátí 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 aplikaci, nastavení ServiceBehaviorAttribute.IncludeExceptionDetailInFaults nebo ServiceDebugBehavior.IncludeExceptionDetailInFaultstrue umožnit klientům WCF získat informace o výjimkách operací interní služby, včetně identifikovatelných osobních nebo jiných citlivých informací.

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

Konstruktory

Name	Description
FaultContractAttribute(Type)	Inicializuje novou instanci FaultContractAttribute třídy.

Vlastnosti

Name	Description
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ě.
Name	Získá nebo nastaví název chybové zprávy v wsDL (Web Services Description Language).
Namespace	Získá nebo nastaví obor názvů chyby SOAP.