FaultContractAttribute Класс

Ссылка

Определение

Пространство имен:: System.ServiceModel

Сборка:: System.ServiceModel.Primitives.dll

Сборка:: System.ServiceModel.dll

Важно!

Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

Задает одну или несколько ошибок протокола 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

Наследование: 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 то свойство контролирует этот уровень защиты.

Внимание!

Если сообщение об ошибке содержит конфиденциальные сведения или может привести к проблемам безопасности, настоятельно рекомендуется 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 является то, что типы, указанные в a FaultContractAttribute , должны быть сериализуемыми System.Runtime.Serialization.DataContractSerializer. Сведения о поддержке сериализации, которая предоставляется, см. в DataContractSerializer разделе "Сериализатор контракта данных".

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

Примечание

В следующих примерах кода не задаются ProtectionLevel Nameсвойства или 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.IServiceBehavior System.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)

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

FaultContractAttribute Класс

Определение

Примеры

Комментарии

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

Свойства

Методы

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

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

Дополнительные ресурсы