FaultContractAttribute Klas

Definitie

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

Overname

Object

Attribute

FaultContractAttribute

Kenmerken

AttributeUsageAttribute

Voorbeelden

In het volgende codevoorbeeld ziet u het gebruik van FaultContractAttribute om op te geven dat de SampleMethod-bewerking een SOAP-fout kan retourneren met het detailtype 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

In het volgende codevoorbeeld ziet u dat WCF-clients van ISampleService deze SOAP-fout als type FaultException<TDetail>GreetingFaultervaren.

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

Opmerkingen

Markeer een bewerking met het FaultContractAttribute kenmerk om een of meer specifieke uitzonderingsvoorwaarden te declareren die worden toegevoegd aan de WSDL-beschrijving (Web Service Description Language) van de servicebewerking als expliciete SOAP-foutberichten die door de bewerking worden geretourneerd.

In alle beheerde toepassingen worden verwerkingsfouten weergegeven door Exception objecten. In SOAP-toepassingen, zoals Windows Communication Foundation (WCF)-toepassingen, communiceren servicemethoden foutinformatie met behulp van SOAP-foutberichten. Omdat WCF-toepassingen worden uitgevoerd onder beide typen foutsystemen, moeten beheerde uitzonderingsgegevens die naar de client moeten worden verzonden, worden geconverteerd van uitzonderingen naar SOAP-fouten. U kunt het standaardgedrag van service-uitzonderingen gebruiken of u kunt expliciet bepalen of -- en hoe -- uitzonderingen worden toegewezen aan foutberichten. Zie Voor een overzicht van uitzonderingen en SOAP-fouten in WCF-toepassingen opgeven en afhandelen van fouten in contracten en services.

Het wordt aanbevolen om servicebewerkingen te FaultContractAttribute gebruiken om formeel alle SOAP-fouten op te geven die een client in de normale loop van een bewerking kan verwachten. Het wordt ook aanbevolen dat alleen die informatie die een client moet weten, wordt geretourneerd in een SOAP-fout om de openbaarmaking van informatie te minimaliseren.

• De Action eigenschap bepaalt de actie van het foutbericht.

• De DetailType eigenschap haalt het type van het detailobject op dat in het foutbericht wordt geserialiseerd.

• De Name en Namespace eigenschappen bepalen respectievelijk de naam en naamruimte van het foutbericht.

• Hiermee HasProtectionLevel wordt aangegeven of het foutbericht een beveiligingsniveau heeft opgegeven, en zo ja, bepaalt de ProtectionLevel eigenschap dat beveiligingsniveau.

• Als u de ProtectionLevel binding expliciet instelt op of ProtectionLevel.SignProtectionLevel.EncryptAndSign, moet u een binding met beveiliging gebruiken die is ingeschakeld met behulp van de System.ServiceModel.SecurityMode eigenschap voor de binding of er wordt een uitzondering gegenereerd.

• Als u een binding selecteert die beveiliging mogelijk maakt en u de ProtectionLevel eigenschap nergens op het contract instelt, worden alle toepassingsgegevens versleuteld en ondertekend.

• Als u een binding selecteert waarvoor geen beveiliging is ingeschakeld (de beveiliging is bijvoorbeeld System.ServiceModel.BasicHttpBinding standaard uitgeschakeld) en de ProtectionLevel binding niet expliciet is ingesteld, worden geen van de toepassingsgegevens beveiligd.

Voor veel scenario's is het voldoende om foutberichten in te EncryptAndSign stellenProtectionLevel. Zie Understanding Protection Level (Beveiligingsniveau) voor meer informatie.

Als u een opgegeven fout wilt retourneren van een bewerking die is gemarkeerd met FaultContractAttribute, genereert u een FaultException<TDetail> (waarbij de typeparameter de serialiseerbare foutinformatie is) wanneer de beheerde uitzondering optreedt tijdens de bewerking. WCF-clienttoepassingen laten de SOAP-fout zien als hetzelfde type als is opgetreden in de clientimplementatie, dat wil gezegd, als een FaultException<TDetail> (waarbij de typeparameter de serialiseerbare foutinformatie is). De FaultContractAttribute kan alleen worden gebruikt om SOAP-fouten op te geven voor servicebewerkingen in twee richtingen en voor asynchrone bewerkingen; eenmalige bewerkingen bieden geen ondersteuning voor SOAP-fouten en bieden daarom geen ondersteuning FaultContractAttributevoor SOAP-fouten.

Als u bijvoorbeeld wilt opgeven dat clients een SOAP-fout kunnen verwachten die een Int32SOAP-fout bevat, plaatst u die typeparameter in de FaultContractAttribute servicemethode.

[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

Vervolgens genereert u in uw servicemethode een nieuw FaultException<TDetail> type waarbij de typeparameter het type is dat de foutgegevens bevat (in het bovenstaande geval een Int32). Voorbeeld:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Het voorgaande voorbeeld is zeer eenvoudig; bijna alle informatie kan worden doorgegeven met behulp van een System.Int32 code, dus dit detailtype is niet het nuttigst. WCF-toepassingen geven doorgaans SOAP-fouten op met gedetailleerde typen die specifiek zijn voor de vereisten voor foutinformatie van de client. Zie de sectie Voorbeeld voor een volledig voorbeeld.

Als u het gedrag van de toepassing expliciet wilt beheren wanneer er een uitzondering optreedt of FaultException<TDetail> wordt gegenereerd, implementeert u de System.ServiceModel.Dispatcher.IErrorHandler interface op een System.ServiceModel.Description.IServiceBehaviorof System.ServiceModel.Description.IContractBehaviorSystem.ServiceModel.Description.IEndpointBehavior en wijst u deze toe aan de ChannelDispatcher.ErrorHandlers eigenschap. IErrorHandler hiermee kunt u expliciet de SOAP-fout beheren die wordt gegenereerd en of deze naar de client moet worden teruggestuurd.

Als u foutopsporing wilt vergemakkelijken, stelt u de ServiceBehaviorAttribute.IncludeExceptionDetailInFaults in true code in of kunt u het ServiceDebugBehavior.IncludeExceptionDetailInFaults in een toepassingsconfiguratiebestand gebruiken. Wanneer deze functie is ingeschakeld, retourneert de service automatisch uitzonderingsgegevens naar de aanroeper. Deze fouten worden aan de client als FaultException uitzonderingen weergegeven.