Export (0) Print
Expand All

Shielding Exceptions at WCF Service Boundaries

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The latest Enterprise Library information can be found at the Enterprise Library site.

In Windows Communication Foundation (WCF), to prevent details of the service implementation from escaping the secure boundary of the service, unknown exceptions should not be sent to the client application. This is controlled through the includeExceptionDetailInFaults attribute in the <serviceDebug> element in the WCF configuration. To enable exception shielding, this attribute must be set to false. If not specified in the configuration file, this property is set to false.

The includeExceptionDetailInFaults configuration setting is used only for unknown or unhandled exceptions. It does not have any effect on known exceptions, where the operation has a FaultContract with the known fault type and the operation throws a FaultException<knownFault> where knownFault is in the fault contract.

Exception shielding helps prevent a Web service from disclosing information about the internal implementation of the service when an exception occurs. The following forces explain why you should use exception shielding:

  • Exception details may contain clues that an attacker can use to exploit resources used by the system.
  • Information related to anticipated exceptions needs to be returned to the client application.
  • Exceptions that occur within a Web service should be logged to support troubleshooting.

Only exceptions that have been sanitized or are safe by design should be returned to the client application. Exceptions that are safe by design do not contain sensitive information in the exception message and they do not contain a detailed stack trace, either of which might reveal sensitive information about the Web service's inner workings. You should use the Exception Shielding pattern to sanitize unsafe exceptions by replacing them with exceptions that are safe by design.

The Exception Handling Application Block includes support for exception shielding at WCF service boundaries. This support consists of the following:

  • The ExceptionShieldingAttribute, which is used to associate exception handing policies with WCF service operations
  • The FaultContractExceptionHandler, which is able to convert an exception to a specific type of Fault Contract and map the desired exception properties into the Fault Contract.

To enable the exception shielding feature in an WCF service

  1. Add references to the following assemblies:
    • Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.dll
    • Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.WCF.dll
    • Microsoft.Practices.EnterpriseLibrary.Common.dll
    • Microsoft.Practices.ObjectBuilder2.dll
  2. Add a Using statement for Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.WCF.
  3. Add the ExceptionShielding attribute to a service implementation class or service contract interface, and specify the name of the exception policy to use as a constructor parameter. If you do not specify the name of a policy in the constructor parameter, or if the specified policy is not defined in configuration, the shielding implementation always looks for a policy named "WCF Exception Shielding."
  4. Add the Exception Handling Application Block configuration sections to the service's Web.config file, and then define the desired exception policies and handlers. The Fault Mapping Exception Handler should be used to map exceptions to fault contracts that are defined on the operation contract. This exception handler is described in the following section.
  5. Implement exception handling logic in your service's client applications to catch the service's possible exceptions and handle them appropriately.

The following code shows the ExceptionShielding attribute applied to a service implementation class, along with its corresponding service contract specifying the fault contracts that may be returned by the operation.

public interface IQuoteService
  QuoteResponseType GetQuote(QuoteRequestType request);

public class QuoteService : IQuoteService
  public QuoteResponseType GetQuote(QuoteRequestType request)
    // Method code here...

When using the Exception Handling Application Block for exception shielding in WCF applications, you can use the Fault Contract Exception Handler to convert a run-time exception to an appropriate Fault Contract type. This exception handler also enables you to map properties from the original exception and the Handling Instance ID to properties in the Fault Contract.

To use the Fault Contract Exception Handler

  1. Create an exception handling policy that includes the appropriate exception types for your application. For more information, see Entering Configuration Information.
  2. Configure the exception type, specifying the PostHandlingAction as ThrowNewException. This means that the application block throws the new exception that has been created by wrapping the original exception. The throw occurs after the entire chain of handlers runs.
  3. Add a new Fault Contract Exception Handler for the specified exception types.
  4. Configure the Fault Contract Exception Handler:
    • Specify the desired Fault Contract Type that should be returned to the client.
    • Add the exception message to be used in the Fault Contract returned to the client.
    • Optionally, configure how properties from the original exception will be mapped to the Fault Contract. In the FaultContractPropertyMapping Editor dialog box, add an item for each property you want to map. The Name property refers to a property name on the Fault Contract. The Source property specifies the name of the property on the original exception from which the value should be retrieved. You can also specify a Source of "{Guid}" to add the current Handling Instance ID to the Fault Contract property.

The Fault Contract Exception Handler will automatically map any properties from the exception to the Fault Contract if their names match and their types are compatible. If you want to prevent this, you can add a mapping with a Name of the Fault Contract property name and a Source with an empty string.

© 2014 Microsoft