FaultContractAttribute Klass

Definition

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

Arv

Object

Attribute

FaultContractAttribute

Attribut

AttributeUsageAttribute

Exempel

Följande kodexempel visar användningen av FaultContractAttribute för att ange att SampleMethod åtgärden kan returnera ett SOAP-fel med detaljtypen 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

Följande kodexempel visar att WCF-klienter upplever ISampleService det här SOAP-felet som en FaultException<TDetail> av typen 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

Kommentarer

Markera en åtgärd med FaultContractAttribute attributet för att deklarera ett eller flera specifika undantagsvillkor som läggs till i WSDL-beskrivningen (Web Service Description Language) för tjänståtgärden som explicita SOAP-felmeddelanden som returneras av åtgärden.

I alla hanterade program representeras bearbetningsfel av Exception objekt. I SOAP-baserade program som Windows Communication Foundation-program (WCF) kommunicerar tjänstmetoder bearbetning av felinformation med hjälp av SOAP-felmeddelanden. Eftersom WCF-program körs under båda typerna av felsystem måste all hanterad undantagsinformation som måste skickas till klienten konverteras från undantag till SOAP-fel. Du kan använda standardbeteenden för tjänstfel, eller så kan du uttryckligen styra om - och hur - undantag mappas till felmeddelanden. En översikt över undantag och SOAP-fel i WCF-program finns i Ange och hantera fel i kontrakt och tjänster.

Vi rekommenderar att tjänståtgärderna använder FaultContractAttribute för att formellt ange alla SOAP-fel som en klient kan förvänta sig att ta emot under en normal åtgärd. Vi rekommenderar också att endast den information som en klient måste känna till returneras i ett SOAP-fel för att minimera avslöjandet av information.

• Egenskapen Action styr åtgärden för felmeddelandet.

• Egenskapen DetailType hämtar den typ av detaljobjekt som serialiseras i felmeddelandet.

• Egenskaperna Name och Namespace styr namn respektive namnrymd för felmeddelandet.

• HasProtectionLevel Anger om felmeddelandet har en angiven skyddsnivå, och i så fall styr egenskapen den ProtectionLevel skyddsnivån.

• Om du anger ProtectionLevel antingen ProtectionLevel.Sign eller ProtectionLevel.EncryptAndSignmåste du använda en bindning med säkerhet aktiverad med egenskapen System.ServiceModel.SecurityMode på bindningen eller så genereras ett undantag.

• Om du väljer en bindning som möjliggör säkerhet och du inte anger ProtectionLevel egenskapen någonstans i kontraktet krypteras och signeras alla programdata.

• Om du väljer en bindning som inte har säkerhetsaktiverad (till exempel System.ServiceModel.BasicHttpBinding har säkerhet inaktiverad som standard) och inte uttryckligen ProtectionLevel har angetts kommer ingen av programdata att skyddas.

För många scenarier räcker det med att EncryptAndSign ange ProtectionLevel för felmeddelanden. Mer information finns i Förstå skyddsnivå.

Om du vill returnera ett angivet fel från en åtgärd markerad med FaultContractAttributegenererar du en FaultException<TDetail> (där typparametern är den serialiserbara felinformationen) när det hanterade undantaget inträffar under åtgärden. WCF-klientprogram visar SOAP-felet som samma typ som utlöstes i klientimplementeringen, det vill ex. som en FaultException<TDetail> (där typeparametern är den serialiserbara felinformationen). FaultContractAttribute Kan endast användas för att ange SOAP-fel för tvåvägstjänståtgärder och för asynkrona åtgärdspar. Enkelriktade åtgärder stöder inte SOAP-fel och stöder FaultContractAttributedärför inte .

Om du till exempel vill ange att klienter kan förvänta sig ett SOAP-fel som innehåller en Int32, placerar du den typen av parameter i FaultContractAttribute på tjänstmetoden.

[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

I tjänstmetoden genererar du sedan en ny FaultException<TDetail> där typparametern är den typ som innehåller felinformationen (i ovanstående fall en Int32). Ett exempel:

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Föregående exempel är mycket grundläggande; nästan all information kan skickas med hjälp av en System.Int32 kod, så den här detaljtypen är inte den mest användbara. Vanligtvis anger WCF-program SOAP-fel med detaljtyper som är specifika för klientens felinformationskrav. Ett mer komplett exempel finns i avsnittet Exempel.

Om du uttryckligen vill styra programmets beteende när ett undantag eller FaultException<TDetail> utlöses implementerar System.ServiceModel.Dispatcher.IErrorHandler du gränssnittet på en System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior eller System.ServiceModel.Description.IEndpointBehavior och tilldelar det till ChannelDispatcher.ErrorHandlers egenskapen. IErrorHandler gör att du uttryckligen kan kontrollera SOAP-felet som genereras och om du vill skicka tillbaka det till klienten.

För att underlätta felsökning anger du ServiceBehaviorAttribute.IncludeExceptionDetailInFaults till true i kod eller så kan du använda ServiceDebugBehavior.IncludeExceptionDetailInFaults i en programkonfigurationsfil. När den är aktiverad returnerar tjänsten automatiskt undantagsinformation till anroparen. Dessa fel visas för klienten som FaultException undantag.