FaultContractAttribute Класс

Определение

Задает одну или несколько ошибок протокола SOAP, сообщения о которых возвращаются, когда операция службы обнаруживает ошибки обработки.Specifies one or more SOAP faults that are returned when a service operation encounters processing errors.

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.The following code example shows the use of FaultContractAttribute to specify that the SampleMethod operation can return a SOAP fault with the detail type of 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

В следующем примере кода показано, что клиенты WCF, ISampleService воздействующие эту ошибку SOAP, имеют FaultException<TDetail> тип GreetingFault .The following code example shows that WCF clients of ISampleService experience this SOAP fault as a FaultException<TDetail> of type 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, возвращаемые операцией.Mark an operation with the FaultContractAttribute attribute to declare one or more specific exception conditions that are added to the Web Service Description Language (WSDL) description of the service operation as explicit SOAP fault messages returned by the operation.

Во всех управляемых приложениях обработка ошибок представлена объектами Exception.In all managed applications, processing errors are represented by Exception objects. В приложениях на основе SOAP, таких как приложения Windows Communication Foundation (WCF), методы служб обмениваются сведениями об ошибках обработки с помощью сообщений о сбоях SOAP.In SOAP-based applications such as Windows Communication Foundation (WCF) applications, service methods communicate processing error information using SOAP fault messages. Поскольку приложения WCF выполняются в обоих типах систем ошибок, все управляемые сведения об исключениях, которые должны быть отправлены клиенту, должны быть преобразованы из исключений в ошибки SOAP.Because WCF applications execute under both types of error systems, any managed exception information that must be sent to the client must be converted from exceptions into SOAP faults. Можно использовать поведения исключений службы по умолчанию или явно управлять тем, будут ли исключения сопоставляться с сообщениями об ошибках и как будет выполняться это сопоставление.You can use the default service exception behaviors, or you can explicitly control whether -- and how -- exceptions are mapped to fault messages. Общие сведения об исключениях и ошибках SOAP в приложениях WCF см. в разделе Указание и обработка ошибок в контрактах и службах.For an overview of exceptions and SOAP faults in WCF applications, see Specifying and Handling Faults in Contracts and Services.

В операциях службы рекомендуется использовать FaultContractAttribute для формального указания всех ошибок SOAP, которые клиент может получить в нормальном процессе операции.It is recommended that service operations use the FaultContractAttribute to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. Кроме того, чтобы свести к минимуму раскрытие информации, рекомендуется возвращать в сообщении об ошибке SOAP только те сведения, которые необходимо знать клиенту.It is also recommended that only that information a client must know is returned in a SOAP fault to minimize information disclosure.

  • ActionСвойство управляет действием сообщения об ошибке.The Action property controls the action of the fault message.

  • DetailTypeСвойство получает тип объекта детализации, сериализованного в сообщении об ошибке.The DetailType property gets the type of the detail object serialized in the fault message.

  • NameСвойства и Namespace управляют именем и пространством имен, соответственно, из сообщения об ошибке.The Name and Namespace properties control the name and namespace, respectively, of the fault message.

  • HasProtectionLevelУказывает, имеет ли сообщение об ошибке уровень защиты, и, если это так, ProtectionLevel свойство управляет этим уровнем защиты.The HasProtectionLevel indicates whether the fault message has a protection level specified, and if so, the ProtectionLevel property controls that level of protection.

Внимание!

Если сообщение об ошибке содержит конфиденциальную информацию или может привести к проблемам безопасности, настоятельно рекомендуется ProtectionLevel установить свойство.If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the ProtectionLevel property be set.

  • Если явно задано значение ProtectionLevel ProtectionLevel.Sign или, то ProtectionLevel.EncryptAndSign необходимо использовать привязку с включенной безопасностью, используя System.ServiceModel.SecurityMode свойство в привязке или исключение.If you set the ProtectionLevel explicitly to either ProtectionLevel.Sign or ProtectionLevel.EncryptAndSign, then you must use a binding with security enabled using the System.ServiceModel.SecurityMode property on the binding or an exception is thrown.

  • Если выбирается привязка, разрешающая обеспечение безопасности, а свойство ProtectionLevel нигде в контракте не задается, все данные приложений будут шифроваться и подписываться.If you select a binding that enables security and you do not set the ProtectionLevel property anywhere on the contract, all application data will be encrypted and signed.

  • Если выбрана привязка, для которой не включена безопасность (например, System.ServiceModel.BasicHttpBinding отключена безопасность по умолчанию) и не ProtectionLevel задана явно, то никакие данные приложения не будут защищены.If you select a binding that does not have security enabled (for example, the System.ServiceModel.BasicHttpBinding has security disabled by default), and the ProtectionLevel is not explicitly set, then none of the application data will be protected.

Для многих сценариев параметр ProtectionLevel для EncryptAndSign сообщений об ошибках достаточно.For many scenarios setting ProtectionLevel to EncryptAndSign for fault messages is sufficient. Дополнительные сведения см. в разделе Основные сведения об уровне защиты.For more details, see Understanding Protection Level.

Чтобы возвратить указанную ошибку из операции, помеченной как FaultContractAttribute , вызовите исключение FaultException<TDetail> (где параметр типа является сериализуемыми сведениями об ошибке), когда во время операции возникает управляемое исключение.To return a specified fault from an operation marked with FaultContractAttribute, throw a FaultException<TDetail> (where the type parameter is the serializable error information) when the managed exception occurs during the operation. Клиентские приложения WCF выдают ошибку SOAP как тот же тип, который был вызван в реализации клиента, то есть как FaultException<TDetail> (где typeparameter находится вне — сериализуемые сведения об ошибке).WCF client applications surface the SOAP fault as the same type as was thrown in the client implementation -- that is, as a FaultException<TDetail> (where the typeparameter is the serializable error information). FaultContractAttributeМожно использовать только для указания ошибок SOAP для двусторонних операций службы и для пар асинхронных операций. односторонние операции не поддерживают ошибки SOAP и, следовательно, не поддерживают FaultContractAttribute .The FaultContractAttribute can be used only to specify SOAP faults for two-way service operations and for asynchronous operation pairs; one-way operations do not support SOAP faults and therefore do not support FaultContractAttribute.

Примечание

Для передачи информации об ошибках можно использовать любой сериализуемый тип.You can use any serializable type to convey error information. Единственное ограничение в этой версии WCF состоит в том, что типы, указанные в, FaultContractAttribute должны быть сериализуемыми с помощью System.Runtime.Serialization.DataContractSerializer .The only restriction in this version of WCF is that types specified in a FaultContractAttribute must be serializable by the System.Runtime.Serialization.DataContractSerializer. Сведения о поддержке сериализации DataContractSerializer см. в разделе сериализатор контрактов данных.For the serialization support the DataContractSerializer provides, see Data Contract Serializer.

Например, чтобы указать, что клиенты могут рассчитывать на ошибку SOAP, содержащую Int32 , поместите параметр Type в FaultContractAttribute метод службы.For example, to specify that clients can expect a SOAP fault that contains an Int32, place that type parameter in the FaultContractAttribute on your service method.

Примечание

В следующих примерах кода не устанавливаются ProtectionLevel Name свойства, или Namespace .The following code examples do not set the ProtectionLevel, Name, or Namespace properties.

[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 ).Then, in your service method, throw a new FaultException<TDetail> where the type parameter is the type that contains the error information (in the above case, a Int32). Пример:For example:

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

Предыдущий пример является очень базовым; практически любую информацию можно передать с помощью System.Int32 кода, поэтому этот тип сведений не является самым полезным.The preceding example is very basic; almost any information can be passed using an System.Int32 code, so this detail type is not the most useful. Как правило, приложения WCF указывают ошибки SOAP с типами сведений, специфичными для требований клиента к сведениям об ошибках.Typically, WCF applications specify SOAP faults with detail types specific to the error information requirements of the client. Более полный пример см. в подразделе "Пример".For a more complete example, see the Example section.

Примечание

Если указать FaultException<TDetail> , где параметр типа является System.String , строковое значение присваивается свойству Detail в клиентском приложении; клиенты не могут получить эту строку, вызвав FaultException<TDetail>.ToString метод.If you specify a FaultException<TDetail> where the type parameter is a System.String, the string value is assigned to the Detail property in the client application; clients cannot retrieve that string by calling the FaultException<TDetail>.ToString method. Чтобы при вызове клиентским приложением метода Exception.ToString возвращалось строковое значение, необходимо вызывать исключение System.ServiceModel.FaultException внутри операции и передавать строку конструктору.To have the string value returned when the client application calls Exception.ToString, throw a System.ServiceModel.FaultException exception inside the operation and pass the string to the constructor.

Чтобы явно управлять поведением приложения при возникновении исключения или FaultException<TDetail> , реализуйте System.ServiceModel.Dispatcher.IErrorHandler интерфейс в System.ServiceModel.Description.IServiceBehavior System.ServiceModel.Description.IContractBehavior или System.ServiceModel.Description.IEndpointBehavior и присвойте его ChannelDispatcher.ErrorHandlers свойству.To explicitly control the behavior of the application when an exception or FaultException<TDetail> is thrown, implement the System.ServiceModel.Dispatcher.IErrorHandler interface on an System.ServiceModel.Description.IServiceBehavior, System.ServiceModel.Description.IContractBehavior or System.ServiceModel.Description.IEndpointBehavior and assign it to the ChannelDispatcher.ErrorHandlers property. IErrorHandler позволяет явно управлять создаваемой ошибкой SOAP и отправкой ее обратно клиенту.IErrorHandler enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

Чтобы упростить отладку, присвойте параметру значение ServiceBehaviorAttribute.IncludeExceptionDetailInFaults true in в коде или используйте ServiceDebugBehavior.IncludeExceptionDetailInFaults в файле конфигурации приложения.To facilitate debugging, set the ServiceBehaviorAttribute.IncludeExceptionDetailInFaults to true in code or you can use the ServiceDebugBehavior.IncludeExceptionDetailInFaults in an application configuration file. Когда эта функция включена, служба автоматически возвращает вызывающему объекту информацию об исключениях.When enabled, the service automatically returns exception information to the caller. Эти ошибки отображаются в клиенте как FaultException исключения.These faults appear to the client as FaultException exceptions.

Важно!

Поскольку управляемые исключения могут предоставлять внутренние сведения о приложении, ServiceBehaviorAttribute.IncludeExceptionDetailInFaults устанавливать ServiceDebugBehavior.IncludeExceptionDetailInFaults или true разрешать клиентам WCF получать сведения о внутренних исключениях операций службы, включая персональные и другие конфиденциальные сведения.Because managed exceptions can expose internal application information, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information.

Поэтому задавать для свойства ServiceBehaviorAttribute.IncludeExceptionDetailInFaults или ServiceDebugBehavior.IncludeExceptionDetailInFaults значение true рекомендуется только для временной отладки приложения службы.Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is only recommended as a way of temporarily debugging a service application. Кроме того, WSDL для метода, который возвращает такие необработанные управляемые исключения, не содержит контракт для исключения FaultException<TDetail> типа String.In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the FaultException<TDetail> of type String. Клиенты должны рассчитывать на возможность неизвестной ошибки SOAP (возвращается клиентам WCF как System.ServiceModel.FaultException объекты) для правильного получения отладочной информации.Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as System.ServiceModel.FaultException objects) to obtain the debugging information properly.

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

FaultContractAttribute(Type)

Инициализирует новый экземпляр класса FaultContractAttribute.Initializes a new instance of the FaultContractAttribute class.

Свойства

Action

Возвращает или задает действие сообщения об ошибке SOAP, которое задается как компонент контракта операции.Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

DetailType

Возвращает тип сериализуемого объекта, который содержит информацию об ошибке.Gets the type of a serializable object that contains error information.

HasProtectionLevel

Возвращает значение, указывающее, присвоен ли сообщению об ошибке SOAP уровень защиты.Gets a value that indicates whether the SOAP fault message has a protection level assigned.

Name

Возвращает или задает имя сообщения об ошибке в языке WSDL.Gets or sets the name of the fault message in Web Services Description Language (WSDL).

Namespace

Возвращает или задает пространство имен ошибки SOAP.Gets or sets the namespace of the SOAP fault.

ProtectionLevel

Задает уровень защиты, который требуется от привязки для ошибки SOAP.Specifies the level of protection the SOAP fault requires from the binding.

TypeId

В случае реализации в производном классе возвращает уникальный идентификатор для этого атрибута Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

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

Методы

Equals(Object)

Возвращает значение, показывающее, равен ли экземпляр указанному объекту.Returns a value that indicates whether this instance is equal to a specified object.

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

Возвращает хэш-код данного экземпляра.Returns the hash code for this instance.

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

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

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

При переопределении в производном классе указывает, является ли значение этого экземпляра значением по умолчанию для производного класса.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

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

При переопределении в производном классе возвращает значение, указывающее, является ли этот экземпляр равным заданному объекту.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

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

Создает неполную копию текущего объекта Object.Creates a shallow copy of the current Object.

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

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

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

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

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

Сопоставляет набор имен соответствующему набору идентификаторов диспетчеризации.Maps a set of names to a corresponding set of dispatch identifiers.

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

Возвращает сведения о типе объекта, которые можно использовать для получения сведений о типе интерфейса.Retrieves the type information for an object, which can be used to get the type information for an interface.

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

Возвращает количество предоставляемых объектом интерфейсов для доступа к сведениям о типе (0 или 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

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

Предоставляет доступ к открытым свойствам и методам объекта.Provides access to properties and methods exposed by an object.

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

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