Dan Rigsby – Coding Up Style

InstanceContext in Wcf Series:
Part 1: Understanding InstanceContext
Part 2: Extending InstanceContext to store custom state

InstanceContext in WCF seems to be somewhat misunderstood.  I have seen a number of questions on MSDN Forums asking what this is or how it is used.  Conceptually it just represents the running instance of the service. Often times it is helpful to think of InstanceContext along with OperationContext. This is the transverse of OperationContext which is the instance of the client accessing the service.  From the service you can access the OperationContext of the client by simply looking at System.ServiceModel.OperationContext.Current.  This object has reference to the InstanceContext of the service it is accessing.  The InstanceContext derives from CommunicationObject

Methods to Note

1. IncrementManualFlowControlLimit: Increases the number of messages that can be processed by the service instance by a specified about.  This method returns the new limit on the number of messages, after the number to increase by has been added.
2. GetServiceInstance: Returns the instance of the service, or creates a new instance of the service if the service doesn’t exits or has been released.
3. ReleaseServiceInstance:  Releases the service instance.

When ReleaseServiceInstance is called the runtime will disassociate the instance from the InstanceContext and call dispose (is IDisposable is implemented) on the instance. A new instance of the service will be created when a new message arrives of if GetServiceInstance is called. (see here Mahjayar’s Weblog for more details)

Properties to note

1. State: (Derived from CommunicationObject.) Gets a value that indicates the current state of the communication object.
   1. Created: Indicates that the communication object has been instantiated and is configurable, but not yet open or ready for use
   2. Opening: Indicates that the communication object is being transitioned from the Created state to the Opened state.
   3. Opened: Indicates that the communication object is now open and ready to be used.
   4. Closing: Indicates that the communication object is transitioning to the Closed state.
   5. Closed: Indicates that the communication object has been closed and is no longer usable.
   6. Faulted: Indicates that the communication object has encountered an error or fault from which it cannot recover and from which it is no longer usable.
2. Extensions: Gets the collection of extensions associated with the service instance.  These extensions would be classes derived from IExtension<InstanceContext>
3. ManualFlowControlLimit: Gets or sets a limit on the number of messages that can be processed by the instance context.
4. SynchronizationContext: Gets or sets the context used for thread synchronization with the current instance context.
5. IncomingChannels: Gets the sessionful channels that are incoming to the service instance.
6. OutgoingChannels: Gets the sessionful channels that are outgoing from the service instance.

InstanceContextMode

In the ServiceBehaviorAttribute you can set the InstanceContextMode of the service.  This property defines how new service objects are created.  There are three options here:

1. PerSession: A new InstanceContext object is created for each session.  This means a new instance of the service itself is created for every unique client connection. If the channel does not create a session this value behaves as if it were PerCall.
2. PerCall: A new InstanceContext object is created prior to and recycled subsequent to each call.   So a new instance of the service is created for every call even if the calls are coming from the same client.
3. Single: Only one InstanceContext object is used for all incoming calls and is not recycled subsequent to the calls. If a service object does not exist, one is created.

The default option is PerSession, but if you aren’t using a binding that allows sessions, then the behavior will be like that of PerCall. (See here for a list of bindings that support or don’t support sessions).

Here is an example of setting context mode on a server:

[ServiceBehavior(
    InstanceContextMode = InstanceContextMode.Single)]
public class MyService : IMyService
{
    ...
}

Technically whenever the user calls InstanceContext.ReleaseServiceInstance() the runtime will disassociate the instance from the InstanceContext and call dispose (If the instance inherits from IDisposable) on the instance. A new instance will be created when a new message arrives for that endpoint or the user explicitly calls InstanceContext.GetServiceInstance().

Accessing the Instance of a service a client is running on

You might want to access the InstanceContext that a client is running against.  These instances can be different since a new instance could be created PerSession or PerCall.  To access this InstanceContext, you can look at it directly in the current OperationContext:

InstanceContext ic = OperationContext.Current.InstanceContext;

Obtain a unique Id for an InstanceContext

Since each InstanceContext is unique, you can call GetHashCode() on the InstanceContext to get a unique identifier for the InstanceContext.  If you are using PerSession this may be important to ensure that the session is the same:

int serviceInstanceId =
    OperationContext.Current.InstanceContext.GetHashCode();

When might you create your own instance of InstanceContext?

The most common use for this is when using Duplexing.  In a Duplex system, the service can callback to the client via a CallbackContract.  This CallbackContract is much like a service on the client side that is listening for calls from the service on the channel that the client has opened.  This “client callback service” can only be accessed via the same channel it used on the service and therefore only that service has access to it.  In order to create the connection to the duplexed service you must specify an InstanceContext like so:

// "this" represents an object that implements the callback contract IMyDuplexServiceCallback
InstanceContext ic = new InstanceContext(this);
var m_ChannelFactory = new DuplexChannelFactory<IMyDuplexService>(ic);

Basically what we have done here is created a standard connection to the server, and gave it an object (InstanceContext) that represents the “client callback service”.

On the service you can access the “client callback service” via the GetCallbackChannel method like so:

IMyServiceCallback callback =
    OperationContext.Current.GetCallbackChannel<IMyServiceCallback>()

Extending InstanceContext

Like most things in WCF, there are a few ways to extend an InstanceContext:

1. IExtension<InstanceContext>: This interface is used to create objects that can be attached to the InstanceContext through the Extensions property.  These objects can store additional state information or behaviors.  This works off the standard extensible object pattern is used in WCF to either extend existing run-time classes with new functionality or to add new state features to an object.
2. IInstanceContextProvider: Implement to participate in the creation or choosing of a InstanceContext, especially to enable shared sessions.
3. IInstanceContextInitializer: Defines the methods necessary to inspect or modify the creation of InstanceContext objects when required. This is typically added to attach an IExtension<InstanceContext> to the InstanceContext object as a mechanism for passing data throughout an application.

Look for a second part of this post that will explain extending the InstanceContext in more detail.