System.ServiceModel 4.0.0.0 System.Attribute System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true, Inherited=false)

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 objects. In SOAP-based applications such as indigo1 applications, service methods communicate processing error information using SOAP fault messages. Because indigo2 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 indigo2 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 property controls the action of the fault message.

The property gets the type of the detail object serialized in the fault message.

The and properties control the name and namespace, respectively, of the fault message.

The indicates whether the fault message has a protection level specified, and if so, the property controls that level of protection.

If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the property be set.

If you set the explicitly to either or , then you must use a binding with security enabled using the property on the binding or an exception is thrown.

If you select a binding that enables security and you do not set the 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 has security disabled by default), and the is not explicitly set, then none of the application data will be protected.

For many scenarios setting to for fault messages is sufficient. For more details, see Understanding Protection Level.

To return a specified fault from an operation marked with , throw a (where the type parameter is the serializable error information) when the managed exception occurs during the operation. indigo2 client applications surface the SOAP fault as the same type as was thrown in the client implementation -- that is, as a (where the type parameter 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 indigo2 is that types specified in a must be serializable by the . For the serialization support the provides, see Data Contract Serializer.

For example, to specify that clients can expect a SOAP fault that contains an , place that type parameter in the on your service method.

The following code examples do not set the , , or properties.

code reference: C_FCA#1

Then, in your service method, throw a new where the type parameter is the type that contains the error information (in the above case, a ). For example:

code reference: C_FCA#2

The preceding example is very basic; almost any information can be passed using an code, so this detail type is not the most useful. Typically, indigo2 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 where the type parameter is a , the string value is assigned to the Detail property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor.

To explicitly control the behavior of the application when an exception or is thrown, implement the interface on an , or and assign it to the property. enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client.

To facilitate debugging, set the to true in code or you can use the in an application configuration file. When enabled, the service automatically returns exception information to the caller. These faults appear to the client as exceptions.

Because managed exceptions can expose internal application information, setting or to true can permit indigo2 clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information.

Therefore, setting or 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 of type . Clients must expect the possibility of an unknown SOAP fault (returned to indigo2 clients as objects) to obtain the debugging information properly.

Specifies one or more SOAP faults that are returned when a service operation encounters processing errors.

- Constructor
  4.0.0.0

  The constructor is typically executed by applying the attribute to a service method and specifying a type as the argument in the attribute.

  Initializes a new instance of the class.

  The serializable type that contains error information for the caller.
- Property
  4.0.0.0
  System.String To be added.

  Use to control the action of the SOAP fault message.

  Gets or sets the action of the SOAP fault message that is specified as part of the operation contract.

- Property
  4.0.0.0
  System.Type To be added. To be added.

  Gets the type of a serializable object that contains error information.

- Property
  4.0.0.0
  System.Boolean To be added.

  Use the property to specify whether the SOAP fault message must be encrypted, signed, or both. See the property for details.

  Gets a value that indicates whether the SOAP fault message has a protection level assigned.

- Property
  4.0.0.0
  System.String To be added. To be added.

  Gets or sets the name of the fault message in Web Services Description Language (WSDL).

- Property
  4.0.0.0
  System.String To be added. To be added.

  Gets or sets the namespace of the SOAP fault.

- Property
  4.0.0.0
  System.Net.Security.ProtectionLevel To be added.

  Use the property to specify the degree to which the binding must encrypt, sign, or both when sending the SOAP fault. It is strongly recommended that an operation's fault explicitly decide the security protection level requirements on the contract. The default protection level is , meaning that the SOAP fault message you are defining does not require encryption or a digital signature (although your binding may provide this support if it is configured to do so). If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the property be set to . For more about security issues, see Understanding Protection Level.

  The protection behavior at runtime is the combination of the protection-level properties that have a hierarchical structure. Setting the outermost value establishes the default setting for all narrower scopes unless a different value for a narrower scope is explicitly set. In this case, the outer value remains the default for all narrower scopes with the exception of that specifically set.

  For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed, including fault messages. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed, including fault messages.

  The scopes at which these values are set are:

  The property on .

  The property on .

  When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies .

  Specifies the level of protection the SOAP fault requires from the binding.