The fault contracts are published along with the rest of the service metadata. When a WCF client imports that metadata, the contract definitions contain the fault contracts as well as the fault detailing type definition, including the relevant data contracts. This last point is important if the detailing type is some custom exception type with various dedicated fields.

The client can expect to catch and handle the imported fault types. For example, when you write a client against the contract shown in Example 6-3, the client can catch FaultException<DivideByZeroException>:

CalculatorClient proxy = new CalculatorClient( );
try
{
   proxy.Divide(2,0);
   proxy.Close( );
}

catch(FaultException<DivideByZeroException> exception)
{...}

catch(FaultException exception)
{...}

catch(CommunicationException exception)
{...}

catch(TimeoutException exception)
{...}

catch(Exception exception)
{...}

Note that the client can still encounter communication exceptions, or any other exception thrown by the service.

The client can choose to treat all non-communication service-side exceptions uniformly by simply handling only the FaultException base exception:

CalculatorClient proxy = new CalculatorClient( );
try
{
   proxy.Divide(2,0);
   proxy.Close( );
}

catch(FaultException exception)
{...}

catch(CommunicationException exception)
{...}

Listing an expected error in a fault contract hardly makes it an exceptional unexpected case. As a result, when the service throws an exception listed in a service-side fault contract, the exception will not fault the communication channel. The client can catch that exception and continue using the proxy, or safely close the proxy. This enables the service class to treat the errors listed in the fault contracts differently from regular exceptions, knowing that they will not fault the channel. This ability is not limited to the service class, though. If any downstream .NET class the service invokes throws such an error, it will not fault the channel to the client. The problem is, how can downstream classes know about the fault contracts of the upstream services that call them? Clearly, having this knowledge present downstream introduces undesirable coupling into the system.

To support the ability of a downstream class to throw an exception without faulting the channel, WCF treats any FaultException (or FaultException-derived class) as a special case that does not fault the channel. In fact, WCF does not actually treat FaultException<T> itself as a special case at all—the reason a fault listed in the contract does not fault the channel is because it is derived from FaultException, not because it is listed in the contract.

Even without any fault contracts, the service (or any downstream object it uses) can throw an instance of FaultException directly:

throw new FaultException("Some Reason");

The Message property of the exception object on the client side will be set to the reason construction parameter of FaultException. I call this throwing an unknown fault that will not fault the communication channel, so the client can keep using the proxy as if the exception was part of a fault contract. Throwing an unknown fault also allows the client to handle the exception separately from any other communication error.

The ServiceBehavior attribute offers IncludeExceptionDetailInFaults, a Boolean property defined as:

[AttributeUsage(AttributeTargets.Class)]
public sealed class ServiceBehaviorAttribute : Attribute, ...
{
   public bool IncludeExceptionDetailInFaults
   {get;set;}
   //More members
}

IncludeExceptionDetailInFaults defaults to false. Setting it to true, as in this snippet:

[ServiceBehavior(IncludeExceptionDetailInFaults = true)]
class MyService : IMyContract
{...}

has a similar effect as the code in Example 6-4, only automated. All noncontractual faults and exceptions thrown by the service or any of its downstream objects are propagated to the client and included in the returned fault message for the client program to process them, as in Example 6-5:

[ServiceBehavior(IncludeExceptionDetailInFaults = true)]
class MyService : IMyContract
{
   public void MethodWithError( )
   {
      throw new InvalidOperationException("Some error");
   }
}

Any fault thrown by the service (or its downstream objects) that is listed in the fault contracts is unaffected and is propagated as-is to the client.

Another important difference between using the declarative support for including the fault details compared with manually throwing FaultException<ExceptionDetail> is that it will correctly fault the channel, preventing the client from reusing the proxy (if a transport session was present).

While including all exceptions is beneficial for debugging, great care should be taken to avoid shipping and deploying the service with IncludeExceptionDetailInFaults set to true. To avoid this potential pitfall automatically you can use conditional compilation, as shown in Example 6-6.

public static class DebugHelper
{
   public const bool IncludeExceptionDetailInFaults =
#if DEBUG
      true;
#else
      false;
#endif
}
[ServiceBehavior(IncludeExceptionDetailInFaults =
                 DebugHelper.IncludeExceptionDetailInFaults)]
class MyService : IMyContract
{...}

Obviously, including all exceptions in the fault message contributes greatly in debugging, but it's also useful when you're trying to analyze a problem in an already deployed service. Fortunately, you can set IncludeExceptionDetailInFaults to true both programmatically and administratively in the host config file. To set this behavior programmatically, before opening the host you need to find the service behavior in the service description and set the IncludeExceptionDetailInFaults property:

ServiceHost host = new ServiceHost(typeof(MyService));

ServiceBehaviorAttribute debuggingBehavior =
                      host.Description.Behaviors.Find<ServiceBehaviorAttribute>( );

debuggingBehavior.IncludeExceptionDetailInFaults = true;

host.Open( );

You can streamline this procedure by encapsulating it in ServiceHost<T>, as shown in Example 6-7.

public class ServiceHost<T> : ServiceHost
{
   public bool IncludeExceptionDetailInFaults
   {
      set
      {
         if(State == CommunicationState.Opened)
         {
            throw new InvalidOperationException("Host is already opened");
         }
         ServiceBehaviorAttribute debuggingBehavior =
                            Description.Behaviors.Find<ServiceBehaviorAttribute>( );
         debuggingBehavior.IncludeExceptionDetailInFaults = value;
      }
      get
      {
         ServiceBehaviorAttribute debuggingBehavior =
                            Description.Behaviors.Find<ServiceBehaviorAttribute>( );
         return debuggingBehavior.IncludeExceptionDetailInFaults;
      }
   }
   //More members
}

Using ServiceHost<T> is trivial and readable:

ServiceHost<MyService> host = new ServiceHost<MyService>( );
host.IncludeExceptionDetailInFaults = true;
host.Open( );

To apply this behavior administratively, add a custom behavior section in the host config file and reference it in the service definition, as shown in Example 6-8.

<system.serviceModel>
   <services>
     <service name = "MyService" behaviorConfiguration = "Debugging">
        ...
     </service>
   </services>
   <behaviors>
      <serviceBehaviors>
         <behavior name = "Debugging">
            <serviceDebug includeExceptionDetailInFaults = "true"/>
         </behavior>
      </serviceBehaviors>
   </behaviors>
</system.serviceModel>

The advantage of administrative configuration in this case is the ability to toggle the behavior in production post-deployment without affecting the service code.

While including the exception details in the fault is a useful diagnostic technique, it is a cumbersome programming model: the client has to take extra steps to extract the error information out of the ExceptionDetail object. More deterring is the fact that the client must use a single massive catch statement (that catches a single FaultException<ExceptionDetail>) to catch all possible exceptions, and sort them all inside the catch statement. In the world of .NET, this is akin to always catching a mere Exception, and avoiding cascading catch statements.

In addition, when writing a test client, you want to know as much as possible about the original exception that happened on the service side, since your test cases are predicated on producing specific errors. The test client could extract the original exception from the ExceptionDetail object and recursively build the inner exception chain. However, that would be tedious and redundant, and it would require repeated code on every use of the service by the test client. It is therefore better to encapsulate these steps in the proxy using C# 3.0 extensions. To that end, I wrote the ExtractException( ) extension method to FaultException<ExceptionDetail>, defined as:

public static class DebugHelper
{
   public static Exception ExtractException(
                                      this FaultException<ExceptionDetail> fault);
   //More members
}

The implementation of FaultException<ExceptionDetail> has nothing to do with WCF, so I won't show it here (but it is available with ServiceModelEx). The best way of using the extension is to encapsulate it within the proxy, as shown in Example 6-9.

[ServiceContract]
interface IMyContract
{
   [OperationContract]
   void MethodWithError( );
}
class MyContractClient : ClientBase<IMyContract>,IMyContract
{
   public MyContractClient( )
   {}
   /* More constructors */

   public void MethodWithError( )
   {
      try
      {
         Channel.MethodWithError( );
      }
      catch(FaultException<ExceptionDetail> exception)
      {
         Abort( );
         throw exception.ExtractException( );
      }
   }
}

In Example 6-9, in the case of a FaultException<ExceptionDetail>, the proxy aborts itself (to prevent the proxy from being used again) regardless of whether a transport session is present or how exactly the service threw the exception. The proxy uses the extension method to throw the extracted exception, allowing the client to catch the raw CLR exception. For example, for this service definition in debug mode:

[ServiceContract]
interface IMyContract
{
   [OperationContract]
   void MyMethod( );
}

[ServiceBehavior(IncludeExceptionDetailInFaults =
                 DebugHelper.IncludeExceptionDetailInFaults)]
class MyService : IMyContract
{
public void MyMethod( )
   {
      throw new InvalidOperationException( );
   }
}

when using the proxy from Example 6-9, the client can expect to catch an InvalidOperationException:

MyContractClient proxy = new MyContractClient( );
try
{
   proxy.MyMethod( );
}
catch(InvalidOperationException exception)
{...}

While the callback can use the same technique shown in Example 6-4 to manually include the exception in the fault message, the CallbackBehavior attribute provides the Boolean property IncludeExceptionDetailInFaults, which can be used to include all non-contract exceptions in the message:

[AttributeUsage(AttributeTargets.Class)]
public sealed class CallbackBehaviorAttribute : Attribute,...
{
   public bool IncludeExceptionDetailInFaults
   {get;set;}
   //More members
}

As for the service, including the exceptions is instrumental in debugging:

[CallbackBehavior(IncludeExceptionDetailInFaults =
                  DebugHelper.IncludeExceptionDetailInFaults)]
class MyClient : IMyContractCallback
{
   public void OnCallBack( )
   {
      ...
      throw new InvalidOperationException( );
   }
}

You can also configure this behavior administratively in the client config file:

<client>
   <endpoint ... behaviorConfiguration = "Debug"
   ...
   />
</client>
<behaviors>
   <endpointBehaviors>
      <behavior name = "Debug">
         <callbackDebug includeExceptionDetailInFaults = "true"/>
      </behavior>
   </endpointBehaviors>
</behaviors>

Note the use of the endpointBehaviors tag to affect the client's callback endpoint.