typesafe

The past few evenings, I’ve tried to come up with something to shield exceptions in WCF. I am aware that there are quite some posts about this topic already, but I thought I’d share my findings/solution anyway. I’ve ran into a few issues with the approaches I found and learned something doing so…

I wanted this to be simple and yet flexible. The following bullets sum up the base requirements:

• No need to apply FaultContractAttribute to all operations
• Allow the user to map exceptions to faults (type and content) in a straightforward manner
• No coupling whatsoever, no imposed library-use, exception or fault types
• Simple and selective fallback to standard WCF behavior

Test First

Let’s start with a test that illustrates the idea (or skip to the implementation). The scenario is as follows. We have a simple service contract with two operations, one throws a custom ValidationException, the other a NotImplementedException. I have told the exception shielding behavior to shield two types of exceptions:

• ValidationException: should map to a validation fault (including one simple property, but this could be anything, of course)
• Exception: should set the ExceptionDetail, basically this comes down to IncludeExceptionDetailInFaults

Here are the types used to test the exception shielding:

[ServiceContract]
[ShieldExceptions	(
	new[] { typeof(ValidationFault), typeof(ExceptionDetail) },
	new[] { typeof(ValidationException), typeof(Exception) })]
public interface ITestService
{
	[OperationContract] void OperationOne();
	[OperationContract] void OperationTwo();
}

public class TestService : ITestService
{
	public void OperationOne()
	{
		throw new ValidationException() { CustomProperty = "OperationOne finds the request invalid." };
	}

	public void OperationTwo()
	{
		throw new System.NotImplementedException();
	}
}

public class ValidationException : Exception
{
	public string CustomProperty { get; set; }
}

[DataContract]
public class ValidationFault
{
	// .ctor maps exception to fault
	public ValidationFault(ValidationException exception)
	{
		FaultProperty = exception.CustomProperty;
	}

	[DataMember]
	public string FaultProperty { get; set; }
}

Notice the use of ShieldExceptions and the fact that there are no FaultContractAttributes on the operations.

And here is one of the tests (I’ve skipped the rest to reduce bloat) to verify the type of exception thrown in the client thread.

[Test]
[ExpectedException(typeof(FaultException<ValidationFault>))]
public void Calling_operation_that_throws_shielded_validation_exception_should_throw_corresponding_fault_exception_on_client()
{
	// Arrange
	var svc = ChannelFactory<ITestService>.CreateChannel(binding, new EndpointAddress(serviceUri));

	// Act
	svc.OperationOne();
}

As the test fixture above illustrates, you simply need to add the attribute ShieldExceptions with a list of exception types you wish to shield. For every exception you need to specify the corresponding fault (this is checked during validation of the behavior). The order in which you specify exception types should be from most specific to the least; being System.Exception. If you don’t specify System.Exception, you’ll get the standard WCF behavior for all exception you didn’t specify.

The mapping of exceptions to faults is simply done by the means of a constructor. The ShieldExceptions behavior will try to create a fault based on the .ctor. First it tries to find the .ctor with the specific exception type, then with a generic exception type and finally it falls back to the default .ctor.

Implementation

There are three parts to this solution: A custom IContractBehavior implementation, a custom IErrorhandler and an IClientMessageInspector.

The ShieldExceptionsAttribute does a few things. It validates if the specified fault and exception types make sense adds a custom error handler to the ChannelDispatcher and sets the required ExceptionShieldingMessageInspector. Besides adding all this behavior the most important thing the ShieldExceptionsAttribute does is updating the service contract with possible faults. If you check out the generated WSDL, you’ll see that all fault information is included.

public class ShieldExceptionsAttribute : Attribute, IContractBehavior
{
	private readonly Type[] knownFaultTypes;
	private readonly Type[] exceptionTypes;

	public ShieldExceptionsAttribute(Type[] knownFaultTypes, Type[] exceptionTypes)
	{
		this.knownFaultTypes = knownFaultTypes;
		this.exceptionTypes = exceptionTypes;
	}

	public void AddBindingParameters(ContractDescription contractDescription, ServiceEndpoint endpoint, BindingParameterCollection bindingParameters)
	{
		foreach (var op in contractDescription.Operations)
		foreach (var knownFaultType in knownFaultTypes)
		{
			// Add fault contract if it is not yet present
			if (!op.Faults.Any(f => f.DetailType == knownFaultType))
				op.Faults.Add(new FaultDescription(knownFaultType.Name) { DetailType = knownFaultType, Name = knownFaultType.Name });
		}
	}

	public void ApplyClientBehavior(ContractDescription contractDescription, ServiceEndpoint endpoint, ClientRuntime clientRuntime)
	{
		clientRuntime.MessageInspectors.Add(new ExceptionShieldingMessageInspector(knownFaultTypes));
	}

	public void ApplyDispatchBehavior(ContractDescription contractDescription, ServiceEndpoint endpoint, DispatchRuntime dispatchRuntime)
	{
		dispatchRuntime.ChannelDispatcher.ErrorHandlers.Add(new ExceptionShieldingErrorHandler(knownFaultTypes, exceptionTypes));
	}

	public void Validate(ContractDescription contractDescription, ServiceEndpoint endpoint)
	{
		if(knownFaultTypes.Length != exceptionTypes.Length)
			throw new ArgumentException("The ShieldExceptions behavior needs a corresponding exception type for each possible fault to shield.");

		var badType = knownFaultTypes.FirstOrDefault(t => !t.IsDefined(typeof (DataContractAttribute), true));
		if(badType != null)
			throw new ArgumentException(string.Format("The specified fault '{0}' is no data contract. Did you forget to decorate the class with the DataContractAttirbute attribute?", badType));

		var badExceptionType = exceptionTypes.FirstOrDefault(t => t != typeof(Exception) && !t.IsSubclassOf(typeof(Exception)));
		if (badExceptionType != null)
			throw new ArgumentException(string.Format("The specified type '{0}' is not an Exception-derived type.", badExceptionType));
	}
}

Now, every time service operation code throws an exception, the ExceptionShieldingErrorHandler gets called. This handler analyzes the thrown exception and creates the appropriate FaultMessage that can travel back to the client.

public class ExceptionShieldingErrorHandler : IErrorHandler
{
	private readonly Type[] knownFaultTypes;
	private readonly Type[] exceptionTypes;

	public ExceptionShieldingErrorHandler(Type[] knownFaultTypes, Type[] exceptionTypes)
	{
		this.knownFaultTypes = knownFaultTypes;
		this.exceptionTypes = exceptionTypes;
	}

	public bool HandleError(Exception error)
	{
		return true; // session should not be killed, or should it?
	}

	public void ProvideFault(Exception error, MessageVersion version, ref Message fault)
	{
		if (error is FaultException) return;

		var exceptionType = exceptionTypes.FirstOrDefault(t => error.GetType() == t || error.GetType().IsSubclassOf(t));
		if(exceptionType != null)
		{
			var faultType = knownFaultTypes[Array.IndexOf(exceptionTypes, exceptionType)];
			fault = Message.CreateMessage(version, CreateFaultException(faultType, error).CreateMessageFault(), faultType.Name);
		}
	}

	private static FaultException CreateFaultException(Type faultType, Exception exception)
	{
		var ctor = faultType.GetConstructor(new[] { exception.GetType() })   // .ctor with specific exception?
			      ?? faultType.GetConstructor(new[] { typeof(Exception) }); // .ctor with generic exception?

		var detail = ctor != null
			? ctor.Invoke(new[] { exception })
			: faultType.GetConstructor(Type.EmptyTypes).Invoke(null); // fall back to default .ctor

		// Create generic fault exception with detail and reason
		return Activator.CreateInstance(typeof(FaultException<>).MakeGenericType(faultType), detail, "Unhandled exception has been shielded.") as FaultException;
	}
}

The CreateFaultException makes sure the most appropriate .ctor is called. This allows you to map exceptions to faults just by initializing the fault from the constructor.

The final piece of the puzzle is a client message inspector. The fact that I have a IClientMessageInspector, is to work around one of the issues I encountered: When you do not specify a FaultContract attribute on the operation(s) in your ServiceContract, you will always get a non-generic (or should I say generic) FaultException in stead of the expected FaultException<T>, holding the detail. That is, if you use a ChannelFactory to create your proxies, which is something I tend to do whenever I can.

Generating proxies from the WSDL (without re-using types, that is) does not need this message inspection since the code will be based on the WSDL which contains all information.

Without the explicit FaultContractAttribute, there’s only one thing we miss: the client proxy doesn’t know about the fault detail. The reply message will contain it, but the channel will simply ignore it. Using this simple message inspector we can easily ‘fake’ the exact same behavior we have with the FaultContractAttribute: we read the detail ourselves.

public class ExceptionShieldingMessageInspector : IClientMessageInspector
{
	private readonly Type[] knownFaultTypes;

	public ExceptionShieldingMessageInspector(Type[] knownFaultTypes)
	{
		this.knownFaultTypes = knownFaultTypes;
	}

	public object BeforeSendRequest(ref Message request, IClientChannel channel)
	{
		return null; // no correlation required
	}

	public void AfterReceiveReply(ref Message reply, object correlationState)
	{
		if (!reply.IsFault) return;

		var action = reply.Headers.Action;
		var faultType = knownFaultTypes.FirstOrDefault(t => t.Name == action);

		if (faultType != null)
		{
			var detail = ReadFaultDetail(MessageFault.CreateFault(reply, int.MaxValue), faultType);
			var exceptionType = typeof(FaultException<>).MakeGenericType(faultType);
			var faultException = Activator.CreateInstance(exceptionType, detail, "Server exception has been shielded.") as Exception;

			throw faultException;
		}
	}

	private static object ReadFaultDetail(MessageFault reply, Type faultType)
	{
		using (var reader = reply.GetReaderAtDetailContents())
		{
			var serializer = new DataContractSerializer(faultType);
			return serializer.ReadObject(reader);
		}
	}
}

In a previous post I wrote something about putting an NHibernate session in your operation context. Guess what? I ended up never using that implementation because shortly after actually putting that behavior in my app, I decided to make it more generic first.

I thought, what will I do with this or that operation of this or that service? I don’t need this kind of context, I need something else here. I was really not into creating a different behavior (and so on) every time something else needed to be scoped. So I thought, why not just configure the type of the context I want?

End Result

Let’s start with the goal. The end result allows you to configure a certain type of context by adding the following behavior extension to the system.ServiceModel section of your configuration file:

<extensions>
	<behaviorExtensions>

		<add name="callContextBehavior" type="typesafe.ServiceModel.CallContextServiceBehaviorExtensionElement, typesafe.ServiceModel, Version=0.2.0.0, Culture=neutral, PublicKeyToken=b7fa8d8d247605f2"/>
	</behaviorExtensions>
</extensions>
<behaviors>
	<serviceBehaviors>
		<behavior name="behavior">
			<callContextBehavior contextType="[ASSEMBLY QUALIFIED NAME OF CONTEXT TYPE]"/>

		</behavior>
	</serviceBehaviors>
</behaviors>

With this configuration I can ensure that every service operation of a certain service will be able to access the specified type of context. All I have to do is add behaviorConfiguration="behavior" to a service configuration element. I could do the same thing on endpoint level as well (if I add the behaviorExtension to an endpointBehavior).

If you don’t like config, you can alternatively go ahead and apply the behavior by the means of a CallContextBehavior attribute which you can apply on either service or operation level. (Doing so also makes unit testing easier to maintain/write.)

[CallContextBehavior(typeof(MyCallContext))]
public bool OperationHasContext()
{
	return CallContext.Current != null;
}

// or

[CallContextBehavior(typeof(MyCallContext))]
public class TestService : ITestService
{
	// now all operations can assert CallContext.Current != null
}

How do we achieve this?

Basically, you’ll need to do the following…

1. Provide a way to access and create your custom context from your code
2. initialize and dispose the context when required/appropriate
3. allow yourself to apply the context (at various levels)

First thing you need is an interface for you context. Well, technically speaking, you don’t, but I decided to do so to make things more explicit and somewhat safer. I have a context interface (an abstract class, actually) that looks like this:

public abstract class CallContext
{
	[ThreadStatic] // who needs OperationContext? ;-)
	private static CallContext callContext;

	/// <summary>
	/// Gets the context of the current operation.
	/// </summary>

	public static CallContext Current
	{
		get { return callContext; }
		internal set { callContext = value;}
	}

	protected internal abstract void Initialize();
	protected internal abstract void Dispose();
}

The static Current property allows you to access the configured context from your service operation code (that’s the main reason I went for an abstract class opposed to an interface). You’ll only have to cast it to your exact type the moment you need to access it (more on this later).

If you want to create a custom context, all you have to do is inherit from CallContext and override its two methods. It goes without saying that the Initialize method is called right before your service call, and the Dispose method right after.

In case you’re wondering why the CallContext class is not IDisposable (while specifying a Dispose method), I did this so I could hide the method from the service implementation code: operations cannot call it. Besides, it didn’t add any value anyway.

The second part consists of an ICallContextInitializer that makes sure the context gets initialized and disposed when we want it, right before and right after our operation executes.

public class CallContextInitializer : ICallContextInitializer
{
	private readonly Type contextType;

	public CallContextInitializer(Type contextType)
	{
		this.contextType = contextType;
	}

	object ICallContextInitializer.BeforeInvoke(System.ServiceModel.InstanceContext instanceContext, System.ServiceModel.IClientChannel channel, Message message)
	{
		CallContext.Current = Activator.CreateInstance(contextType) as CallContext;

		if (CallContext.Current == null)
			throw new ConfigurationErrorsException(string.Format("The type '{0}' could not be initialized or is no CallContext derived type.", contextType));

		CallContext.Current.Initialize();

		return null; // we don't need no correlation
	}

	void ICallContextInitializer.AfterInvoke(object state)
	{
		// Dispose the context
		if (CallContext.Current != null)
			CallContext.Current.Dispose();
	}
}

Finally we need to apply the ICallContextInitializer to the service operations with a behavior. The following behavior implements IServiceBehavior, IEndpointBehavior and IOperationBehavior. This allows you to choose the granularity of applying the behavior.

public class CallContextServiceBehavior : Attribute, IServiceBehavior, IEndpointBehavior, IOperationBehavior
{
	private readonly Type contextType;

	public CallContextServiceBehavior(Type type)
	{
		contextType = type;
	}

	void IServiceBehavior.ApplyDispatchBehavior(ServiceDescription serviceDescription, ServiceHostBase serviceHostBase)
	{
		foreach (ChannelDispatcher cd in serviceHostBase.ChannelDispatchers)
		foreach (var ed in cd.Endpoints)
		foreach (var operation in ed.DispatchRuntime.Operations)
		{
			operation.CallContextInitializers.Add(new CallContextInitializer(contextType));
		}
	}

	void IEndpointBehavior.ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher)
	{
		foreach (var operation in endpointDispatcher.DispatchRuntime.Operations)
		{
			operation.CallContextInitializers.Add(new CallContextInitializer(contextType));
		}
	}

	void IOperationBehavior.ApplyDispatchBehavior(OperationDescription operationDescription, DispatchOperation dispatchOperation)
	{
		dispatchOperation.CallContextInitializers.Add(new CallContextInitializer(contextType));
	}

	// remainder of the interfaces have no implementation...
}

To enable applying the behavior through the system.ServiceModel configuration section (as in the first listing above), we need to create the following BehaviorExtensionElement.

public class CallContextBehaviorExtensionElement : BehaviorExtensionElement
{
	private ConfigurationPropertyCollection properties;

	public override Type BehaviorType
	{
		get { return typeof(CallContextBehavior); }
	}

	protected override object CreateBehavior()
	{
		Type type = Type.GetType(ContextType);

		if (type == null)
			throw new ConfigurationErrorsException(string.Format("The type '{0}' could not be initialized.", ContextType));

		return new CallContextBehavior(type);
	}

	protected override ConfigurationPropertyCollection Properties
	{
		get
		{
			if (properties == null)
			{
				properties = new ConfigurationPropertyCollection {new ConfigurationProperty("contextType", typeof (string))};
			}
			return properties;
		}
	}

	[ConfigurationProperty("contextType", IsRequired = true)]
	public string ContextType
	{
		get { return (string)base["contextType"]; }
		set { base["contextType"] = value; }
	}

}

Example

To illustrate how it all fits together: The following listing contains a completely self-contained unit test that illustrates the usage and working of the above solution.

[TestFixture]
public class CallContextBehaviorTests
{
	private const string address = "net.pipe://localhost/TestService";

	private ServiceHost host;
	private ITestService service;

	[TestFixtureSetUp]
	public void SetUp()
	{
		host = new ServiceHost(typeof(TestService));
		host.AddServiceEndpoint(typeof(ITestService), new NetNamedPipeBinding(), address);
		host.Open();

		var factory = new ChannelFactory<ITestService>(new NetNamedPipeBinding(), new EndpointAddress(address));
		service = factory.CreateChannel();
	}

	[TestFixtureTearDown]
	public void TearDown()
	{
		host.Close();
	}

	[Test]
	public void CallContext_is_null_by_default()
	{
		Assert.IsTrue(service.OperationWithoutContext());
	}

	[Test]
	public void CallContext_should_be_available_after_applying_service_attribute()
	{
		Assert.IsTrue(service.OperationWithContext());
	}
}

internal class MyCallContext : CallContext
{
	// any property we like

	public new static MyCallContext Current
	{
		get { return CallContext.Current as MyCallContext; }
	}

	protected override void Initialize() { }
	protected override void Dispose() { }
}

[ServiceContract]
internal interface ITestService
{
	[OperationContract]
	bool OperationWithContext();

	[OperationContract]
	bool OperationWithoutContext();
}

internal class TestService : ITestService
{
	[CallContextBehavior(typeof(MyCallContext))]
	public bool OperationWithContext()
	{
		return MyCallContext.Current != null;
	}

	public bool OperationWithoutContext()
	{
		return MyCallContext.Current == null;
	}
}

I am currently involved in a new CSD project where we have just started to discuss some basic architecture and design aspects. We still have A LOT to talk about, but some things are already pretty certain: WCF (no doubt!), NHibernate (many vendors to support), general principles (separation of concerns, etc.),…

One of the first things that come to mind with the above combination (WCF & NHibernate, that is) is data session management (or data context for LINQ, same issue there). In an ASP.Net application you’ll probably go for a request-scoped ISession whose lifetime you manage through an HttpModule or so.

WCF is actually very similar, except that you’ve got more options in terms of instance and concurrency management, to name a few. However, since a per-call model is considered the most valid option in most cases, we can focus on the similar case.

After some experimenting, and going through the (still very few) examples on the subject I came up with the following first attempt to extend WCF:

1. Implement a simple ICallContextInitializer to manage the scope and lifetime of the (potentially needed) NHibernate session:

public class NHibernateContext : ICallContextInitializer
{
    private static readonly ISessionFactory sessionFactory
        = new Configuration().BuildSessionFactory();

    [ThreadStatic] // who needs OperationContext? ;-)
    private static ISession session;

    /// <summary>
    /// Gets the NHibernate session for the current
    /// service operation/thread.
    /// </summary>
    public static ISession Session
    {
        get
        {
            // lazy init (we might not always need it)
            if (session == null)
                session = sessionFactory.OpenSession();
            return session;
        }
    }

    object ICallContextInitializer.BeforeInvoke(
        System.ServiceModel.InstanceContext instanceContext,
        System.ServiceModel.IClientChannel channel,
        System.ServiceModel.Channels.Message message)
    {
        Debug.Assert(session == null);
        return null; // we don't need no correlation
    }

    void ICallContextInitializer.AfterInvoke(object state)
    {
        // Dispose the session if it as created
        if (session != null)
            session.Dispose();
    }
}

I decided to provide lazy initialization of the ISession. This allows you to apply the service behavior (see later) without having to worry about potential overhead; if the operation does not go to the database, no behavior is added. Asserting that the thread-scoped session variable is null, is to make sure the behavior is applied no more than once and the operation is running in ConcurrencyMode.Single. Finally, the AfterInvoke makes sure the session (if any) is disposed of.

2. Create a service behavior that assures the above ICallContextInitializer is added to the service operation(s).

public class NHibernateServiceBehavior : Attribute, IServiceBehavior
{
    public void ApplyDispatchBehavior(
        ServiceDescription serviceDescription,
        ServiceHostBase serviceHostBase)
    {
        foreach (ChannelDispatcher cd in
            serviceHostBase.ChannelDispatchers)
        {
            foreach (EndpointDispatcher ed in cd.Endpoints)
            {
                foreach (DispatchOperation operation in
                    ed.DispatchRuntime.Operations)
                {
                    operation.CallContextInitializers.Add(
                       new NHibernateContext());
                }
            }
        }
    }

    public void AddBindingParameters(
        ServiceDescription serviceDescription,
        ServiceHostBase serviceHostBase,
        System.Collections.ObjectModel.Collection endpoints,
        BindingParameterCollection bindingParameters) { }

    public void Validate(ServiceDescription serviceDescription,
        ServiceHostBase serviceHostBase) { }

}

You might ask yourself why I chose to use a service behavior and not just an operation behavior (since that’s basically what I’m doing). Well, the main reason is that I wanted as much flexibility as available and service behaviors are the only behaviors that allow all configuration options: through attributes, .Net configuration files or explicitly coded.

With the above behavior in place you can simply call and work with your session, probably not straight from your service code, but through a Repository maybe. Just call NHibernateContext.Session and you’re done.

One last (optional) thing to make sure .Net configuration files really are an option for applying our service behavior is a BehaviorExtensionElement:

public class NHibernateServiceBehaviorExtensionElement :
    BehaviorExtensionElement
{
    public override Type BehaviorType
    {
        get { return typeof(NHibernateServiceBehavior); }
    }

    protected override object CreateBehavior()
    {
        return new NHibernateServiceBehavior();
    }
}

This allows you to apply the behavior as follows.

<services>
      <service name="[namespace].SomeService" behaviorConfiguration="nhibernateBehaviorCfg" >
      ...
      </service>

   </services>
   <extensions>
      <behaviorExtensions>
         <add name="nhibernateBehavior" type="[namespace].NHibernateExtesionConfigurationElement, <assemblyName>, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
      </behaviorExtensions>

   </extensions>
   <behaviors>
      <serviceBehaviors>
         <behavior name=" nhibernateBehaviorCfg ">
         <nhibernateBehavior /> ... </behavior>

      </serviceBehaviors>
   </behaviors>
</system.serviceModel>