The ProvideFault( ) method of the extension object is called immediately after any unhandled exception is thrown by the service or any object on the call chain downstream from a service operation. WCF calls ProvideFault( ) before returning control to the client, and before terminating the session (if present) and disposing of the service instance (if required). Because ProvideFault( ) is called on the incoming call thread while the client is still blocked waiting for the operation to complete, you should avoid lengthy execution inside ProvideFault( ).

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {...}

   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {
      //Nothing here - exception will go up as usual
   }
}

public abstract class Message : ...
{
   public static Message CreateMessage(MessageVersion version,
                                       MessageFault fault,string action);
   //More members
}

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {...}
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {
      FaultException<int> faultException = new FaultException<int>(3);
      MessageFault messageFault = faultException.CreateMessageFault( );
      fault = Message.CreateMessage(version,messageFault,faultException.Action);
   }
}

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {...}
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {
      fault = null; //Suppress any faults in contract
   }
}

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

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {...}
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {
      if(error is InvalidOperationException)
      {
         FaultException<InvalidOperationException> faultException =
                                     new FaultException<InvalidOperationException>(
                                     new InvalidOperationException(error.Message));
         MessageFault messageFault = faultException.CreateMessageFault( );
         fault = Message.CreateMessage(version,messageFault,faultException.Action);
      }
   }
}

public static class ErrorHandlerHelper
{
   public static void PromoteException(Type serviceType,
                                       Exception error,
                                       MessageVersion version,
                                       ref Message fault);
   //More members
}

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {...}
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {
      Type serviceType = ...;
      ErrorHandlerHelper.PromoteException(serviceType,error,version,ref fault);
   }
}

The HandleError( ) method of IErrorHandler is defined as:

bool HandleError(Exception error);

HandleError( ) is called by WCF after control returns to the client. HandleError( ) is strictly for service-side use, and nothing it does affects the client in any way. Calling in the background enables you to perform lengthy processing, such as logging to a database without impeding the client.

Because you can have multiple error-handling extensions installed in a list, WCF also enables you to control whether extensions down the list should be used. If HandleError( ) returns false, WCF will continue to call HandleError( ) on the rest of the installed extensions. If HandleError( ) returns true, WCF stops invoking the error-handling extensions. Obviously, most extensions should return false.

The error parameter of HandleError( ) is the original exception thrown. The classic use for HandleError( ) is for logging and tracing, as shown in Example 6-14.

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {
      try
      {
         LogbookServiceClient proxy = new LogbookServiceClient( );
         proxy.Log(...);
         proxy.Close( );
      }
catch
      {}
      finally
      {
         return false;
      }
   }
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)

   {...}
}

The logbook service

The source code available with this book in ServiceModelEx contains a standalone service called LogbookManager that is dedicated to error logging. LogbookManager logs the errors into a SQL Server database. The service contract also provides operations for retrieving the entries in the logbook and clearing the logbook. ServiceModelEx also contains a simple logbook viewer and management tool. In addition to error logging, LogbookManager allows you to log entries explicitly into the logbook, independently of exceptions. The architecture of this framework is depicted in Figure 6-1.

Figure 6-1. The logbook service and viewer

You can automate error logging to LogbookManager using the LogError( ) method of my ErrorHandlerHelper static class:

public static class ErrorHandlerHelper
{
   public static void LogError(Exception error);
   //More members
}

The error parameter is simply the exception you wish to log. LogError( ) encapsulates the call to LogbookManager. For example, instead of the code in Example 6-14, you can simply write a single line:

class MyErrorHandler : IErrorHandler
{
   public bool HandleError(Exception error)
   {
      ErrorHandlerHelper.LogError(error);
      return false;
   }
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {...}
}

In addition to capturing the raw exception information, LogError( ) performs extensive parsing of the exception and other environment variables for a comprehensive record of the error and its related information.

Specifically, LogError( ) captures the following information:

• Where the exception occurred (machine name and host process name)

• The code where the exception took place (the assembly name, the filename, and the line number if debug symbols are provided)

• The type where the exception took place and the member being accessed

• The date and time when the exception occurred

• The exception name and message

Implementing LogError( ) has little to do with WCF, so this method is not shown in this chapter. The code, however, makes extensive use of interesting .NET programming techniques such as string and exception parsing, along with obtaining the environment information. The error information is passed to LogbookManager in a dedicated data contract.

Every channel dispatcher in WCF offers a collection of error extensions:

public class ChannelDispatcher : ChannelDispatcherBase
{
   public Collection<IErrorHandler> ErrorHandlers
   {get;}
   //More members
}

Installing your own custom implementation of IErrorHandler requires merely adding it to the desired dispatcher (usually all of them).

You must add the error extensions before the first call arrives to the service, but after the host constructs the collection of dispatchers. This narrow window of opportunity exists after the host is initialized, but before it is opened. To act in that window, the best solution is to treat error extensions as custom service behaviors, because the behaviors are given the opportunity to interact with the dispatchers at just the right time. As mentioned in Chapter 4, all service behaviors implement the IServiceBehavior interface, defined as:

public interface IServiceBehavior
{
   void AddBindingParameters(ServiceDescription description,
                             ServiceHostBase host,
                             Collection<ServiceEndpoint> endpoints,
                             BindingParameterCollection bindingParameters);

   void ApplyDispatchBehavior(ServiceDescription description,
                              ServiceHostBase host);

   void Validate(ServiceDescription description,ServiceHostBase host);
}

The ApplyDispatchBehavior( ) method is your cue to add the error extensions to the dispatchers. You can safely ignore all other methods of IServiceBehavior and provide empty implementations for them.

In ApplyDispatchBehavior( ), you need to access the collection of dispatchers available in the ChannelDispatchers property of ServiceHostBase:

public class ChannelDispatcherCollection :
                                     SynchronizedCollection<ChannelDispatcherBase>
{}
public abstract class ServiceHostBase : ...
{
   public ChannelDispatcherCollection ChannelDispatchers
   {get;}
   //More members
}

Each item in ChannelDispatchers is of the type ChannelDispatcher. You can add the implementation of IErrorHandler to all dispatchers, or just add it to specific dispatchers associated with a particular binding. Example 6-15 demonstrates adding an implementation of IErrorHandler to all of a service's dispatchers.

class MyErrorHandler : IErrorHandler
{...}

class MyService : IMyContract,IServiceBehavior
{
   public void ApplyDispatchBehavior(ServiceDescription description,
                                     ServiceHostBase host)
{
      IErrorHandler handler = new MyErrorHandler( );
      foreach(ChannelDispatcher dispatcher in host.ChannelDispatchers)
      {
         dispatcher.ErrorHandlers.Add(handler);
      }
   }
   public void Validate(...)
   {}
   public void AddBindingParameters(...)
   {}
   //More members
}

In Example 6-15, the service itself implements IServiceBehavior. In ApplyDispatchBehavior( ), the service obtains the dispatchers collection and adds an instance of the MyErrorHandler class to each dispatcher.

Instead of relying on an external class to implement IErrorHandler, the service class itself can support IErrorHandler directly, as shown in Example 6-16.

class MyService : IMyContract,IServiceBehavior,IErrorHandler
{
   public void ApplyDispatchBehavior(ServiceDescription description,
                                     ServiceHostBase host)
   {
      foreach(ChannelDispatcher dispatcher in host.ChannelDispatchers)
      {
         dispatcher.ErrorHandlers.Add(this);
      }
   }
   public bool HandleError(Exception error)
   {...}

   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {...}
   //More members
}

public class ErrorHandlerBehaviorAttribute : Attribute,IErrorHandler,
                                                                  IServiceBehavior
{
   protected Type ServiceType
   {get;set;}
}

[ErrorHandlerBehavior]
class MyService : IMyContract
{...}

[AttributeUsage(AttributeTargets.Class)]
public class ErrorHandlerBehaviorAttribute : Attribute,IServiceBehavior,
                                                                     IErrorHandler
{
   protected Type ServiceType
   {get;set;}

   void IServiceBehavior.ApplyDispatchBehavior(ServiceDescription description,
                                               ServiceHostBase host)
   {
      ServiceType = description.ServiceType;
      foreach(ChannelDispatcher dispatcher in host.ChannelDispatchers)
      {
         dispatcher.ErrorHandlers.Add(this);
      }
   }
   bool IErrorHandler.HandleError(Exception error)
   {
      ErrorHandlerHelper.LogError(error);
      return false;
   }
   void IErrorHandler.ProvideFault(Exception error,MessageVersion version,
                                   ref Message fault)
   {
      ErrorHandlerHelper.PromoteException(ServiceType,error,version,ref fault);
   }
   void IServiceBehavior.Validate(...)
   {}
   void IServiceBehavior.AddBindingParameters(...)
   {}
}

While the ErrorHandlerBehavior attribute greatly simplifies the act of installing an error extension, the attribute does require the service developer to apply the attribute. It would be nice if the host could add error extensions independently of whether or not the service provides any. However, due to the narrow timing window available for installing extensions, having the host add such an extension requires multiple steps. First, you need to provide an error-handling extension type that supports both IServiceBehavior and IErrorHandler. The implementation of IServiceBehavior will add the error extension to the dispatchers, as shown previously. Next, you must derive a custom host class from ServiceHost and override the OnOpening( ) method defined by the CommunicationObject base class:

public abstract class CommunicationObject : ICommunicationObject
{
   protected virtual void OnOpening( );
   //More members
}
public abstract class ServiceHostBase : CommunicationObject ,...
{...}
public class ServiceHost : ServiceHostBase,...
{...}

In OnOpening( ), you need to add the custom error-handling type to the collection of service behaviors in the service description. That behaviors collection was described in Chapter 1 and Chapter 4:

public class Collection<T> : IList<T>,...
{
   public void Add(T item);
   //More members
}
public abstract class KeyedCollection<K,T> : Collection<T>
{...}
public class KeyedByTypeCollection<I> : KeyedCollection<Type,I>
{...}
public class ServiceDescription
{
   public KeyedByTypeCollection<IServiceBehavior> Behaviors
   {get;}
}
public abstract class ServiceHostBase : ...
{
   public ServiceDescription Description
   {get;}
   //More members
}

This sequence of steps is already encapsulated and automated in ServiceHost<T>:

public class ServiceHost<T> : ServiceHost
{
   public void AddErrorHandler(IErrorHandler errorHandler);
   public void AddErrorHandler( );
   //More members
}

ServiceHost<T> offers two overloaded versions of the AddErrorHandler( ) method. The one that takes an IErrorHandler object will internally associate it with a behavior, so you can provide it with any class that supports just IErrorHandler, not IServiceBehavior:

class MyService : IMyContract
{...}

class MyErrorHandler : IErrorHandler
{...}

ServiceHost<MyService> host = new ServiceHost<MyService>( );
host.AddErrorHandler(new MyErrorHandler( ));
host.Open( );

The AddErrorHandler( ) method that takes no parameters will install an error-handling extension that uses ErrorHandlerHelper, just as if the service class was decorated with the ErrorHandlerBehavior attribute:

class MyService : IMyContract
{...}

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

Actually, for this last example, ServiceHost<T> does internally use an instance of the ErrorHandlerBehavior attribute.

Example 6-18 shows the implementation of the AddErrorHandler( ) method.

public class ServiceHost<T> : ServiceHost
{
   class ErrorHandlerBehavior : IServiceBehavior,IErrorHandler
   {
      IErrorHandler m_ErrorHandler;

      public ErrorHandlerBehavior(IErrorHandler errorHandler)
      {
         m_ErrorHandler = errorHandler;
      }
      void IServiceBehavior.ApplyDispatchBehavior(ServiceDescription description,
                                                  ServiceHostBase host)
      {
foreach(ChannelDispatcher dispatcher in host.ChannelDispatchers)
         {
            dispatcher.ErrorHandlers.Add(this);
         }
      }
      bool IErrorHandler.HandleError(Exception error)
      {
         return m_ErrorHandler.HandleError(error);
      }
      void IErrorHandler.ProvideFault(Exception error,MessageVersion version,
                                      ref Message fault)
      {
         m_ErrorHandler.ProvideFault(error,version,ref fault);
      }
      //Rest of the implementation
   }

   List<IServiceBehavior> m_ErrorHandlers = new List<IServiceBehavior>( );

   public void AddErrorHandler(IErrorHandler errorHandler)
   {
      if(State == CommunicationState.Opened)
      {
         throw new InvalidOperationException("Host is already opened");
      }
      IServiceBehavior errorHandlerBehavior =
                                             new ErrorHandlerBehavior(errorHandler);
      m_ErrorHandlers.Add(errorHandlerBehavior);
   }
   public void AddErrorHandler( )
   {
      AddErrorHandler(new ErrorHandlerBehaviorAttribute( ));
   }
   protected override void OnOpening( )
   {
      foreach(IServiceBehavior behavior in m_ErrorHandlers)
      {
         Description.Behaviors.Add(behavior);
      }
      base.OnOpening( );
   }
   //Rest of the implementation
}

To avoid forcing the provided IErrorHandler reference to also support IServiceBehavior, ServiceHost<T> defines a private nested class called ErrorHandlerBehavior. ErrorHandlerBehavior implements both IErrorHandler and IServiceBehavior. To construct ErrorHandlerBehavior, you need to provide it with an implementation of IErrorHandler. That implementation is saved for later use. The implementation of IServiceBehavior adds the instance itself to the error-handler collection of all dispatchers. The implementation of IErrorHandler simply delegates to the saved construction parameter. ServiceHost<T> defines a list of IServiceBehavior references in the m_ErrorHandlers member variable. The AddErrorHandler( ) method that accepts an IErrorHandler reference uses it to construct an instance of ErrorHandlerBehavior and then adds it to m_ErrorHandlers. The AddErrorHandler( ) method that takes no parameter uses an instance of the ErrorHandlerBehavior attribute, because the attribute is merely a class that supports IErrorHandler. Finally, the OnOpening( ) method iterates over m_ErrorHandlers, adding each behavior to the behaviors collection.

The client-side callback object can also provide an implementation of IErrorHandler for error handling. Compared with the service-error extensions, the main difference is that to install the callback extension you need to use the IEndpointBehavior interface, defined as:

public interface IEndpointBehavior
{
   void AddBindingParameters(ServiceEndpoint endpoint,
                             BindingParameterCollection bindingParameters);
   void ApplyClientBehavior(ServiceEndpoint endpoint,
                            ClientRuntime clientRuntime);
   void ApplyDispatchBehavior(ServiceEndpoint endpoint,
                              EndpointDispatcher endpointDispatcher);
   void Validate(ServiceEndpoint endpoint);
}

IEndpointBehavior is the interface all callback behaviors support. The only relevant method for the purpose of installing an error extension is the ApplyClientBehavior( ) method, which lets you associate the error extension with the single dispatcher of the callback endpoint. The clientRuntime parameter is of the type ClientRuntime, which offers the CallbackDispatchRuntime property of the type DispatchRuntime. The DispatchRuntime class offers the ChannelDispatcher property, with its collection of error handlers:

public sealed class ClientRuntime
{
   public DispatchRuntime CallbackDispatchRuntime
   {get;}
   //More members
}
public sealed class DispatchRuntime
{
   public ChannelDispatcher ChannelDispatcher
   {get;}
   //More members
}

As with a service-side error-handling extension, you need to add to that collection your custom error-handling implementation of IErrorHandler.

The callback object itself can implement IEndpointBehavior, as shown in Example 6-19.

class MyErrorHandler : IErrorHandler
{...}

class MyClient : IMyContractCallback,IEndpointBehavior
{
   public void OnCallBack( )
   {...}

   void IEndpointBehavior.ApplyClientBehavior(ServiceEndpoint serviceEndpoint,
                                              ClientRuntime clientRuntime)
   {
      IErrorHandler handler = new MyErrorHandler( );

      clientRuntime.CallbackDispatchRuntime.ChannelDispatcher.ErrorHandlers.
                                                                      Add(handler);
   }

   void IEndpointBehavior.AddBindingParameters(...)
   {}
   void IEndpointBehavior.ApplyDispatchBehavior(...)
   {}
   void IEndpointBehavior.Validate(...)
   {}
   //More members
}

Instead of using an external class for implementing IErrorHandler, the callback class itself can implement IErrorHandler directly:

class MyClient : IMyContractCallback,IEndpointBehavior,IErrorHandler
{
   public void OnCallBack( )
   {...}

   void IEndpointBehavior.ApplyClientBehavior(ServiceEndpoint serviceEndpoint,
                                              ClientRuntime clientRuntime)
   {
      clientRuntime.CallbackDispatchRuntime.ChannelDispatcher.ErrorHandlers.Add
(this);
   }
   public bool HandleError(Exception error)
   {...}
   public void ProvideFault(Exception error,MessageVersion version,
                            ref Message fault)
   {...}
   //More members
}

public class CallbackErrorHandlerBehaviorAttribute : ErrorHandlerBehaviorAttribute,
                                                                  IEndpointBehavior
{
   public CallbackErrorHandlerBehaviorAttribute(Type clientType);
}

[CallbackErrorHandlerBehavior(typeof(MyClient))]
class MyClient : IMyContractCallback
{
   public void OnCallBack( )
   {...}
}

public class CallbackErrorHandlerBehaviorAttribute : ErrorHandlerBehaviorAttribute,
                                                                  IEndpointBehavior
{
   public CallbackErrorHandlerBehaviorAttribute(Type clientType)
   {
      ServiceType = clientType;
   }
   void IEndpointBehavior.ApplyClientBehavior(ServiceEndpoint serviceEndpoint,
                                              ClientRuntime clientRuntime)
   {
      clientRuntime.CallbackDispatchRuntime.ChannelDispatcher.ErrorHandlers.Add
(this);
   }
   void IEndpointBehavior.AddBindingParameters(...)
   {}
   void IEndpointBehavior.ApplyDispatchBehavior(...)
   {}
   void IEndpointBehavior.Validate(...)
   {}
}