FaultContractAttribute Класс

Определение

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

Наследование

Object

Attribute

FaultContractAttribute

Атрибуты

AttributeUsageAttribute

Примеры

Следующий пример кода демонстрирует использование FaultContractAttribute для указания, что операция SampleMethod может возвращать SOAP-ошибку с типом детализации 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

В следующем примере кода показано, что клиенты ISampleService WCF испытывают эту ошибку SOAP в качестве FaultException<TDetail> типа 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

Комментарии

Пометьте операцию с FaultContractAttribute атрибутом, чтобы объявить одно или несколько конкретных условий исключения, добавленных в описание языка описания веб-службы (WSDL), как явные сообщения об ошибке SOAP, возвращаемые операцией.

Во всех управляемых приложениях ошибки обработки представлены объектами Exception . В приложениях на основе SOAP, таких как приложения Windows Communication Foundation (WCF), методы службы обмениваются сведениями об ошибках с помощью сообщений об ошибках SOAP. Так как приложения WCF выполняются в обоих типах систем ошибок, все сведения об управляемом исключении, которые должны быть отправлены клиенту, должны быть преобразованы из исключений в ошибки SOAP. Вы можете использовать поведение исключений службы по умолчанию или явно контролировать, сопоставляются ли исключения с сообщениями об ошибках. Общие сведения об исключениях и сбоях SOAP в приложениях WCF см. в разделе "Указание и обработка ошибок в контрактах и службах".

Рекомендуется, чтобы операции службы использовались FaultContractAttribute для формального указания всех ошибок SOAP, которые клиент может ожидать получать в обычном ходе операции. Также рекомендуется, чтобы только информация, которую клиент должен знать, возвращается в ошибке SOAP, чтобы свести к минимуму раскрытие информации.

• Свойство Action управляет действием сообщения об ошибке.

• Свойство DetailType получает тип объекта сведений, сериализованного в сообщении об ошибке.

• Namespace Свойства Name управляют именем и пространством имен соответственно сообщения об ошибке.

• Указывает HasProtectionLevel , имеет ли сообщение об ошибке указанный уровень защиты, а если да, ProtectionLevel то свойство определяет уровень защиты.

• Если задать явное ProtectionLevelProtectionLevel.Sign значение или , необходимо использовать привязку с включенной безопасностью с помощью System.ServiceModel.SecurityMode свойства привязки или ProtectionLevel.EncryptAndSignисключения.

• Если выбрать привязку, которая обеспечивает безопасность, и вы не задаете ProtectionLevel свойство в любом месте контракта, все данные приложения будут зашифрованы и подписаны.

• Если выбрана привязка, которая не включена безопасность (например, System.ServiceModel.BasicHttpBinding безопасность отключена по умолчанию) и ProtectionLevel не задана явным образом, ни одна из данных приложения не будет защищена.

Для многих сценариев достаточно параметров ProtectionLevelEncryptAndSign для сообщений об ошибках. Дополнительные сведения см. в разделе "Общие сведения о уровне защиты".

Чтобы вернуть указанную ошибку из операции, помеченной с FaultContractAttributeпомощью команды, создайте исключение FaultException<TDetail> (где параметр типа является сериализуемыми сведениями об ошибке) при возникновении управляемого исключения во время операции. Клиентские приложения WCF помещают ошибку SOAP с тем же типом, что и в реализации клиента, т. е. как FaultException<TDetail> (где типпараметр является сериализуемыми сведениями об ошибке). Можно FaultContractAttribute использовать только для указания ошибок SOAP для двусторонних операций службы и для пар асинхронных операций; односторонняя операция не поддерживает ошибки SOAP и поэтому не поддерживает FaultContractAttribute.

Например, чтобы указать, что клиенты могут ожидать ошибку SOAP, содержащую Int32параметр этого типа в FaultContractAttribute методе службы.

[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

Затем в методе службы создается новый FaultException<TDetail> параметр типа, содержащий сведения об ошибке (в приведенном выше случае — a Int32). Рассмотрим пример.

throw new FaultException<int>(4);

Throw New FaultException(Of Integer)(4)

Предыдущий пример очень прост. почти любую информацию можно передать с помощью кода, поэтому этот тип сведений System.Int32 не является наиболее полезным. Как правило, приложения WCF указывают ошибки SOAP с типами сведений, характерными для требований к сведениям об ошибках клиента. Более полный пример см. в разделе "Пример".

Чтобы явно контролировать поведение приложения при возникновении исключения или FaultException<TDetail> создания, реализуйте System.ServiceModel.Dispatcher.IErrorHandler интерфейс в объекте System.ServiceModel.Description.IServiceBehaviorSystem.ServiceModel.Description.IContractBehavior или System.ServiceModel.Description.IEndpointBehavior назначьте его свойствуChannelDispatcher.ErrorHandlers. IErrorHandler позволяет явным образом контролировать сбой SOAP, который создается, и следует ли отправлять его обратно клиенту.

Чтобы упростить отладку, задайте ServiceBehaviorAttribute.IncludeExceptionDetailInFaults значение true в коде или можно использовать ServiceDebugBehavior.IncludeExceptionDetailInFaults в файле конфигурации приложения. При включении служба автоматически возвращает сведения об исключении вызывающей объекту. Эти ошибки отображаются клиентом в качестве FaultException исключений.