WCF Extensibility – IInstanceContextProvider

Article
02/06/2012

This post is part of a series about WCF extensibility points. For a list of all previous posts and planned future ones, go to the index page .

And we’re now back in the middle of the WCF runtime, and at the last few posts for this series. This time we’ll look at the instance context provider. The instance context represents the service which is running, but often (as most inner components in WCF) you don’t need to know anything about them, until you do. Unfortunately the MSDN documentation for the instance context isn’t very clear (it lists what it has, but doesn’t show many examples on where it can be used), but I’ve found that the post on instance context from Dan Rigsby to be a good introduction on the topic, where he lists some usages and properties of that class, so I won’t repeat that here.

The instance context provider, represented by the aptly named interface IInstanceContextProvider, is a way for a service to change how those contexts can be created. Similar to the IInstanceProvider (which defines how instances of the service class are created), it allows for tweaking the context creation, sharing of contexts between multiple calls, among other things, but the canonical usage of the instance context provider is to allow the sharing of service sessions between different clients.

Public implementations in WCF

As with most runtime extensibility points, there are no public implementations in WCF. There are three internal ones, however, which are chosen depending on the value of the InstanceContextMode property of a ServiceBehaviorAttribute which can be applied to the service class – you can use a tool such as ILSpy or Reflector to get more information on the implementation of those classes.

InstanceContextMode.PerCall: the internal class System.ServiceModel.Dispatcher.PerCallInstanceContextProvider will be chosen.
InstanceContextMode.PerSession (default): the internal class System.ServiceModel.Dispatcher.PerSessionInstanceContextProvider will be chosen.
InstanceContextMode.Single: the internal class System.ServiceModel.Dispatcher.SingletonInstanceContextProvider will be chosen.

Note that when a custom IInstanceContextProvider is set in the dispatch runtime, the instance context mode set in the service behavior attribute is ignored.

Interface definition

public interface IInstanceContextProvider
{
InstanceContext GetExistingInstanceContext(Message message, IContextChannel channel);
void InitializeInstanceContext(InstanceContext instanceContext, Message message, IContextChannel channel);
bool IsIdle(InstanceContext instanceContext);
void NotifyIdle(InstanceContextIdleCallback callback, InstanceContext instanceContext);
}

The first method in the instance context provider to be called is GetExistingInstanceContext, whenever a new message arrives to the service. For that message the provider can either return an existing instance context which will be reused, or return null (or Nothing) – in that case, a new instance context is created by the WCF runtime and passed to the InitializeInstanceContext method, so that it can be properly initialized. Notice that each new instance context created by the runtime counts towards the ServiceThrottle.MaxConcurrentInstances quota.

When the WCF runtime is done with the instance context, it will call IsIdle to check whether the instance context can be disposed. If the method return true, then the context will be closed and recycled, and the number of concurrent instances (bound by ServiceThrottle.MaxConcurrentInstances) will be decremented. If the method returns false, then NotifyIdle will be called. In this case, the runtime will pass a callback that the instance context provider must call whenever the instance context is done and ready to be recycled. When the callback is invoked, the runtime will again invoke IsIdle to check whether it can dispose and recycle the instance context.

How to add instance context providers

Instance context providers apply only at the server side, and they’re bound to the DispatchRuntime object. They’re typically added in endpoint or service behaviors, as shown in the example below.

class MyBehavior : IEndpointBehavior
{
public void ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher)
{
endpointDispatcher.DispatchRuntime.InstanceContextProvider = new MyInstanceContextProvider();
}
}

Real world scenario: simulating sessions in session-less bindings

The canonical usage of the instance context provider (and the one in the WCF samples) is for two different client to be able to share a session object on the server. I decided to improve on that example, to, beside enable sharing session, also enable it to happen in bindings which don’t support sessions (such as BasicHttpBinding). In this example I’m using a custom SOAP header to identify the session, but another scenario where this could definitely be useful would be where a cookie was used for identification.

Anyway, let’s revive once again the calculator. But this time, to make things more interesting for sessions, let’s make it a calculator which works with postfix operators, using the Reverse Polish notation (RPN). So instead of having the usual operations taking two parameters, our contract is shown below. The operation Enter adds a parameter to a stack, and the operations take the top two parameters from the stack, process them, and store the result back in the stack.

public interface IStackCalculator
{
[OperationContract]
void Enter(double value);
[OperationContract]
double Add();
[OperationContract]
double Subtract();
[OperationContract]
double Multiply();
[OperationContract]
double Divide();
}

And example helps to understand this concept. If we want to calculate ((4*5) / (3+2)), we’d call the following operations:

Enter(4)
Enter(5)
Multiply()
Enter(3)
Enter(2)
Add()
Divide()

Now, this new calculator has a concept of a stack. If we use a normal session-less binding (such as BasicHttpBinding or WebHttpBinding) to implement this contract, the operation calls would fail, because every call goes to a new instance (thus the stack would be empty). We cannot use the InstanceContextMode.PerSession property of the ServiceBehaviorAttribute, because for session-less bindings this is essentially the same as InstanceContextMode.Single. We could also have a static stack, but in this case the operations by two different clients would clobber each other. What we really need is to simulate a session over those bindings which don’t support them (notice that another way to do that is to create a protocol channel that changes the shape of the underlying channel from session-less to session-full; but as I mentioned before, if you can avoid writing channels, you should do always go for the alternative).

The approach I’m using in this sample is to keep a session alive for some time after the last message for that session arrived. This way, the client can send a series of messages which share the same header, and if they arrive close enough to each other, they will get the same instance context in the server (and consequently the same service instance). Each time a new message for that session is processed, the “expiration” of the session is extended. A background thread keeps checking the sessions to see which ones are expired, and marks those which are for removal.

Before we move on, the usual disclaimer: this is a sample for illustrating the topic of this post, this is not production-ready code. I tested it for a few contracts and it worked, but I cannot guarantee that it will work for all scenarios – please let me know if you find a bug or something missing. There are some security implications in keeping multiple instance contexts alive for a certain time period which are not addressed (if many different clients connect to the server, it would quickly exceed its MaxConcurrentInstances quota). Also, as usual, error checking has been kept to a minimum.

First, let’s look at the service code – it’s not as trivial as the “normal” calculator, but it’s quite simple nonetheless. Since the service class doesn’t need to deal with sessions itself (that’s why we’re using a custom instance context provider), it just implements the stack calculator as it normally would.

public class StackCalculator : IStackCalculator
{
Stack<double> values = new Stack<double>();
public void Enter(double value)
{
this.values.Push(value);
Console.WriteLine("Adding {0} to stack - {1}", value, GetStack());
}
public double Add()
{
return this.Process((x, y) => x + y, "+");
}
public double Subtract()
{
return this.Process((x, y) => x - y, "-");
}
public double Multiply()
{
return this.Process((x, y) => x * y, "*");
}
public double Divide()
{
return this.Process((x, y) => x / y, "/");
}
private double Process(Func<double, double, double> operation, string symbol)
{
double op2 = this.values.Pop();
double op1 = this.values.Pop();
double result = operation(op1, op2);
this.values.Push(result);
Console.WriteLine("{0} {1} {2} = {3} - {4}", op1, symbol, op2, result, GetStack());
return result;
}
private string GetStack()
{
StringBuilder sb = new StringBuilder();
sb.Append('[');
sb.Append(string.Join(",", this.values));
sb.Append(']');
return sb.ToString();
}
}

The test program will just use the channel factory and channel as it would in a session-full scenario, but this time it will use a session-less binding, BasicHttpBinding – but we’ll add an endpoint behavior which will do the trick with the instance contexts. The client code is also similar, but we’ll use an operation context scope to add a header to all requests from the client, so that all the requests can go to the same server session.

static void Main(string[] args)
{
string baseAddress = "https://" + Environment.MachineName + ":8000/Service";
ServiceHost host = new ServiceHost(typeof(StackCalculator), new Uri(baseAddress));
var binding = new BasicHttpBinding();
ServiceEndpoint endpoint = host.AddServiceEndpoint(typeof(IStackCalculator), binding, "");
endpoint.Behaviors.Add(new SharedSessionEndpointBehavior());
host.Open();
Console.WriteLine("Host opened");
ChannelFactory<IStackCalculator> factory = new ChannelFactory<IStackCalculator>(binding, new EndpointAddress(baseAddress));
IStackCalculator proxy = factory.CreateChannel();
using (new OperationContextScope((IContextChannel)proxy))
{
OperationContext.Current.OutgoingMessageHeaders.Add(
MessageHeader.CreateHeader(
Constants.HeaderName,
Constants.HeaderNamespace,
"abcdef"));
proxy.Enter(2);
proxy.Enter(3);
proxy.Add();
proxy.Enter(4);
proxy.Subtract();
Console.WriteLine();
}
}

The endpoint behavior will add our custom instance context provider to the runtime. And like the “official” sample, it will also add a message inspector which will be used to notify our session that the call has completed.

class SharedSessionEndpointBehavior : IEndpointBehavior
{
public void ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher)
{
SharedSessionInstanceContextProvider extension = new SharedSessionInstanceContextProvider();
endpointDispatcher.DispatchRuntime.InstanceContextProvider = extension;
endpointDispatcher.DispatchRuntime.MessageInspectors.Add(extension);
}
}

Now, for the instance context provider class. The class stores a dictionary of instance contexts keyed by the identifier send by the client. When a new message arrives, we first try to fetch the header to find if the client sent any session identifier. If it did, we check if the session is active. If it is, we’ll retrieve a SharedInstanceContextInfo from the instance context extension list (see more about extensions in the previous post) and increment the number of instances which are using it. The extension object is a perfect place for this scenario, since it will live alongside the instance context object. If we didn’t find a session for the client (either because it didn’t send any identifier, or because there’s no instance context for the given identifier), then the method returns null, which signals WCF that it’s time to create a new instance context for that request.

class SharedSessionInstanceContextProvider : IInstanceContextProvider, IDispatchMessageInspector
{
private readonly static object SyncRoot = new object();
Dictionary<string, InstanceContext> instanceContexts = new Dictionary<string, InstanceContext>();
Thread expirationThread;
public InstanceContext GetExistingInstanceContext(Message message, IContextChannel channel)
{
int headerIndex = message.Headers.FindHeader(Constants.HeaderName, Constants.HeaderNamespace);
if (headerIndex >= 0)
{
string instanceId = message.Headers.GetHeader<string>(headerIndex);
lock (SyncRoot)
{
if (this.instanceContexts.ContainsKey(instanceId))
{
InstanceContext context = this.instanceContexts[instanceId];
SharedInstanceContextInfo info = context.Extensions.Find<SharedInstanceContextInfo>();
info.IncrementBusyCount();
return context;
}
}
}
return null;
}
}

If the previous method (GetExistingInstanceContext) returns null, then WCF will create a new instance context, and pass it to the instance context provider so that it can be initialized. In this method, we first try to fetch the instance id send by the client; if there is none, we just create a new random one, then create a SharedInstanceContextInfo which will live alongside with the instance context as one of its extensions – this is similar to the code from the official sample. But to use the timed expiration, we’ll increment the “busy count” of the context info twice – one for the request which caused the new context to be created, and one so that the context will always be “alive”, until the expiration thread finally marks it down. We then add the new instance context to the provider’s dictionary, and start the expiration thread, if it hasn’t yet. Finally, the code will add a handler to the Closing event of the context: when WCF decides that it’s time to recycle it, we’ll be notified and we can remove it from the provider’s dictionary.

public void InitializeInstanceContext(InstanceContext instanceContext, Message message, IContextChannel channel)
{
string instanceId;
int headerIndex = message.Headers.FindHeader(Constants.HeaderName, Constants.HeaderNamespace);
if (headerIndex >= 0)
{
instanceId = message.Headers.GetHeader<string>(headerIndex);
}
else
{
instanceId = Guid.NewGuid().ToString();
}
SharedInstanceContextInfo info = new SharedInstanceContextInfo(instanceId, instanceContext);
info.IncrementBusyCount(); // one for the current caller
info.IncrementBusyCount(); // one for the expiration timer
instanceContext.Extensions.Add(info);
lock (SyncRoot)
{
this.instanceContexts.Add(instanceId, instanceContext);
if (this.expirationThread == null)
{
this.expirationThread = new Thread(RemoveExpiredInstanceContexts);
this.expirationThread.Start();
}
}
instanceContext.Closing += delegate(object sender, EventArgs e)
{
lock (SyncRoot)
{
this.instanceContexts.Remove(instanceId);
if (this.instanceContexts.Count == 0)
{
this.expirationThread.Abort();
this.expirationThread = null;
}
}
};
}

The expiration thread method is a simple loop which every second looks at the instance contexts in the provider’s dictionary. If the context info associated with it is expired, then the context is marked to be removed, which is done by decrementing the “busy count” one last time so that it reaches zero.

private void RemoveExpiredInstanceContexts()
{
try
{
while (true)
{
lock (SyncRoot)
{
List<SharedInstanceContextInfo> toRemove = new List<SharedInstanceContextInfo>();
foreach (var key in this.instanceContexts.Keys)
{
InstanceContext context = this.instanceContexts[key];
SharedInstanceContextInfo info = context.Extensions.Find<SharedInstanceContextInfo>();
toRemove.Add(info);
}
foreach (var info in toRemove)
{
if (info.IsExpired())
{
info.DecrementBusyCount(); // let it get to 0
}
}
}
Thread.CurrentThread.Join(1000); // check again in 1 second
}
}
catch (ThreadAbortException) { }
}

The last two methods in the IInstanceContextProvider interface simply delegate the processing to the context info associated with the extension.

public bool IsIdle(InstanceContext instanceContext)
{
var info = instanceContext.Extensions.Find<SharedInstanceContextInfo>();
return info.IsIdle;
}
public void NotifyIdle(InstanceContextIdleCallback callback, InstanceContext instanceContext)
{
SharedInstanceContextInfo info = instanceContext.Extensions.Find<SharedInstanceContextInfo>();
info.SetIdleCallback(callback);
}

You recall that the instance context provider also implements IDispatchMessageInspector – and we use its methods to decrement the “busy count” for the instance context information (which was incremented on either GetExistingInstanceContext or InitializeInstanceContext).

public object AfterReceiveRequest(ref Message request, IClientChannel channel, InstanceContext instanceContext)
{
return instanceContext;
}
public void BeforeSendReply(ref Message reply, object correlationState)
{
InstanceContext instanceContext = (InstanceContext)correlationState;
SharedInstanceContextInfo info = instanceContext.Extensions.Find<SharedInstanceContextInfo>();
info.DecrementBusyCount();
}

That’s the instance context provider. A lot of the processing, though, happens on the extension class, SharedInstanceContextInfo, which is shown below. It stores the instance context associated with it, its expiration time and the number of active calls (plus the expiration one) in the “busy count”.

class SharedInstanceContextInfo : IExtension<InstanceContext>
{
internal static readonly int SecondsToIdle = 10;
DateTime expiration;
int busyCount;
InstanceContext instanceContext;
InstanceContextIdleCallback idleCallback;
public SharedInstanceContextInfo(InstanceContext instanceContext)
{
this.instanceContext = instanceContext;
this.UpdateExpiration();
this.busyCount = 0;
}
}

The busy / idle operations are interesting in the extension. Whenever a new message arrives, the instance context provider will increment the busy count in the extension. When the message processing finishes (on the dispatch message inspector), or with the expiration thread finds the instance context to be expired, they will decrement the busy count. Once it reaches zero, if any callback had been set by the WCF runtime, it will be called, which will cause WCF to call IsIdle again and, unless new messages arrived for the same instance identifier, the instance context will be marked for recycling.

public void IncrementBusyCount()
{
this.busyCount++;
}
public void DecrementBusyCount()
{
this.busyCount--;
this.CheckIdle();
}
public void SetIdleCallback(InstanceContextIdleCallback callback)
{
this.idleCallback = callback;
this.CheckIdle();
}
private void CheckIdle()
{
if (this.busyCount == 0 && this.idleCallback != null)
{
InstanceContextIdleCallback callback = this.idleCallback;
this.idleCallback = null;
if (callback != null)
{
try
{
this.IsIdle = true;
callback(this.instanceContext);
}
finally
{
this.IsIdle = false;
}
}
}
}

And that’s it. On the code gallery I’ve augmented the test program to perform more operations: have multiple instance contexts at the same time, verify that the sessions actually expire after a certain time, and other examples.

Coming up

Initializer interfaces in the WCF runtime

[Code in this post]

[Back to the index]