FaultContractAttribute Класс

Определение

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

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
Наследование
FaultContractAttribute
Атрибуты

Примеры

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

Внимание!

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

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

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

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

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

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

Примечание

Для передачи информации об ошибках можно использовать любой сериализуемый тип. Единственным ограничением в этой версии WCF является то, что типы, указанные в aFaultContractAttribute, должны быть сериализуемыми.System.Runtime.Serialization.DataContractSerializer Сведения о поддержке сериализации, которая DataContractSerializer предоставляется, см. в разделе "Сериализатор контракта данных".

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

Примечание

В следующих примерах кода не задаются ProtectionLevelNameсвойства или Namespace свойства.

[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> место, где параметр типа является типом, содержащим сведения об ошибке (в приведенном выше случае — а Int32). Пример:

throw new FaultException<int>(4);
Throw New FaultException(Of Integer)(4)

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

Примечание

Если указать FaultException<TDetail> , где указан System.Stringпараметр типа, строковое значение присваивается свойству Detail в клиентском приложении; клиенты не могут получить эту строку путем вызова FaultException<TDetail>.ToString метода. Чтобы при вызове клиентским приложением метода Exception.ToString возвращалось строковое значение, необходимо вызывать исключение System.ServiceModel.FaultException внутри операции и передавать строку конструктору.

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

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

Важно!

Так как управляемые исключения могут предоставлять внутренние сведения о приложении, параметр ServiceBehaviorAttribute.IncludeExceptionDetailInFaults или ServiceDebugBehavior.IncludeExceptionDetailInFaults true разрешить клиентам WCF получать сведения об исключениях внутренних операций службы, включая личные или другие конфиденциальные сведения.

Поэтому задавать для свойства ServiceBehaviorAttribute.IncludeExceptionDetailInFaults или ServiceDebugBehavior.IncludeExceptionDetailInFaults значение true рекомендуется только для временной отладки приложения службы. Кроме того, WSDL для метода, который возвращает такие необработанные управляемые исключения, не содержит контракт для исключения FaultException<TDetail> типа String. Клиенты должны ожидать возможности неизвестной ошибки SOAP (возвращенной клиентам WCF в качестве System.ServiceModel.FaultException объектов) для правильного получения сведений об отладке.

Конструкторы

FaultContractAttribute(Type)

Инициализирует новый экземпляр класса FaultContractAttribute.

Свойства

Action

Возвращает или задает действие сообщения об ошибке SOAP, которое задается как компонент контракта операции.

DetailType

Возвращает тип сериализуемого объекта, который содержит информацию об ошибке.

HasProtectionLevel

Возвращает значение, указывающее, присвоен ли сообщению об ошибке SOAP уровень защиты.

Name

Возвращает или задает имя сообщения об ошибке в языке WSDL.

Namespace

Возвращает или задает пространство имен ошибки SOAP.

ProtectionLevel

Задает уровень защиты, который требуется от привязки для ошибки SOAP.

TypeId

В случае реализации в производном классе возвращает уникальный идентификатор для этого атрибута Attribute.

(Унаследовано от Attribute)

Методы

Equals(Object)

Возвращает значение, показывающее, равен ли экземпляр указанному объекту.

(Унаследовано от Attribute)
GetHashCode()

Возвращает хэш-код данного экземпляра.

(Унаследовано от Attribute)
GetType()

Возвращает объект Type для текущего экземпляра.

(Унаследовано от Object)
IsDefaultAttribute()

При переопределении в производном классе указывает, является ли значение этого экземпляра значением по умолчанию для производного класса.

(Унаследовано от Attribute)
Match(Object)

При переопределении в производном классе возвращает значение, указывающее, является ли этот экземпляр равным заданному объекту.

(Унаследовано от Attribute)
MemberwiseClone()

Создает неполную копию текущего объекта Object.

(Унаследовано от Object)
ToString()

Возвращает строку, представляющую текущий объект.

(Унаследовано от Object)

Явные реализации интерфейса

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

Сопоставляет набор имен соответствующему набору идентификаторов диспетчеризации.

(Унаследовано от Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Возвращает сведения о типе объекта, которые можно использовать для получения сведений о типе интерфейса.

(Унаследовано от Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Возвращает количество предоставляемых объектом интерфейсов для доступа к сведениям о типе (0 или 1).

(Унаследовано от Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Предоставляет доступ к открытым свойствам и методам объекта.

(Унаследовано от Attribute)

Применяется к