Specifies one or more SOAP faults that are returned when a service operation encounters processing errors.
Assembly: System.ServiceModel (in System.ServiceModel.dll)
Thetype exposes the following members.
|Action||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||Gets a value that indicates whether the SOAP fault message has a protection level assigned.|
|Name||Gets or sets the name of the fault message in Web Services Description Language (WSDL).|
|Namespace||Gets or sets the namespace of the SOAP fault.|
|ProtectionLevel||Specifies the level of protection the SOAP fault requires from the binding.|
|TypeId||When implemented in a derived class, gets a unique identifier for this Attribute. (Inherited from Attribute.)|
|Equals||Infrastructure. Returns a value that indicates whether this instance is equal to a specified object. (Inherited from Attribute.)|
|Finalize||Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)|
|GetHashCode||Returns the hash code for this instance. (Inherited from Attribute.)|
|GetType||Gets the Type of the current instance. (Inherited from Object.)|
|IsDefaultAttribute||When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class. (Inherited from Attribute.)|
|Match||When overridden in a derived class, returns a value that indicates whether this instance equals a specified object. (Inherited from Attribute.)|
|MemberwiseClone||Creates a shallow copy of the current Object. (Inherited from Object.)|
|ToString||Returns a string that represents the current object. (Inherited from Object.)|
|_Attribute.GetIDsOfNames||Maps a set of names to a corresponding set of dispatch identifiers. (Inherited from Attribute.)|
|_Attribute.GetTypeInfo||Retrieves the type information for an object, which can be used to get the type information for an interface. (Inherited from Attribute.)|
|_Attribute.GetTypeInfoCount||Retrieves the number of type information interfaces that an object provides (either 0 or 1). (Inherited from Attribute.)|
|_Attribute.Invoke||Provides access to properties and methods exposed by an object. (Inherited from Attribute.)|
Mark an operation with the 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.
In all managed applications, processing errors are represented by Exception objects. In SOAP-based applications such as applications, service methods communicate processing error information using SOAP fault messages. Because 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. For an overview of exceptions and SOAP faults in applications, see Specifying and Handling Faults in Contracts and Services.
It is recommended that service operations use the to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. It is also recommended that only that information a client must know is returned in a SOAP fault to minimize information disclosure.
The Action property controls the action of the fault message.
The DetailType property gets the type of the detail object serialized in the fault message.
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.
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.
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.
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.
To return a specified fault from an operation marked with , throw a FaultException(Of TDetail) (where the type parameter is the serializable error information) when the managed exception occurs during the operation. client applications surface the SOAP fault as the same type as was thrown in the client implementation -- that is, as a FaultException(Of TDetail) (where the typeparameter is the serializable error information). The 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 .
You can use any serializable type to convey error information. The only restriction in this version of is that types specified in a must be serializable by the System.Runtime.Serialization.DataContractSerializer. For the serialization support the DataContractSerializer provides, see Data Contract Serializer.
For example, to specify that clients can expect a SOAP fault that contains an Int32, place that type parameter in the on your service method.
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. Typically, 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.
If you specify a FaultException(Of 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(Of TDetail).ToString method. 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.
To explicitly control the behavior of the application when an exception or FaultException(Of 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 property. IErrorHandlerenables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.
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. These faults appear to the client as FaultException exceptions.
Because managed exceptions can expose internal application information, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true can permit clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information.
Therefore, setting ServiceBehaviorAttribute.IncludeExceptionDetailInFaults or ServiceDebugBehavior.IncludeExceptionDetailInFaults to true is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the FaultException(Of TDetail) of type String. Clients must expect the possibility of an unknown SOAP fault (returned to clients as System.ServiceModel.FaultException objects) to obtain the debugging information properly.
The following code example shows the use of to specify that the SampleMethod operation can return a SOAP fault with the detail type of GreetingFault.
Imports System 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
The following code example shows that clients of ISampleService experience this SOAP fault as a FaultException(Of TDetail) of type GreetingFault.
Imports System 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
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.