What does the IHttpModuleContextContainer attempt to solve?

When you write an IIS module to do some serious stuff, you would most probably would have to devise a strategy to store configuration data, and or runtime state. Many a times, the scope of this information is different depending on what the module is trying to achieve. For instance, if you were writing a module to keep track of all active connections, so as to sample the rate of IO happening on them, and take some action depending on the value (say, tear down connection if IO rate is very low), then you would want to store your runtime context at the connection scope.

Another example where you would need the scope at the url path (metadata path) level, would be if say, you have two different applications under the same site, and the settings for your module is configured differently for these two apps. In this case, your configuration would have to be stored and accessed at the application path level. If you don’t know about the IHttpModuleContextContainer, then, chances are that you either implemented some kind of a global data store, from which you accessed information based on the connectionID in the first example, or metapath in the case of the second example.

What is IHttpModuleContextContainer?

It is IIS’s solution to store and retrieve configuration/state information for a module with very little overhead. At a high level, this is really a store for pointers, with a slot for each module. Every module is handed over a module-ID by the IIS pipeline, when the RegisterModule method is invoked by IIS. This ID is what you would use to access your slot. Now, if IIS gave a module only one slot of all its data needs, then that would be practically useless. What IIS does is, for all the important objects in a request pipeline, every module gets a slot.

Which means, if you were to store something on a per connection basis, you would retrieve the contextContainer from the connectionobject, and then set your relevant information there for future lookup. For data pertaining to the application scope, you would store your data in the ContextContainer for the application object. Below is the list of all interfaces for which a moduleContextContainer is present.

• IHttpSite: Site Scope
• IHttpApplication: Application scope
• IMetadataInfo: Metapath scope
• IHttpContext: Request Scope
• IHttpConnection: Connection Scope

How do I use it?

The objects which needs to be persisted in the context container must inherit from IHttpStoredContext. This interface has a single method CleanupStoredContext, which will be invoked when the parent object is being torn down.

This is the place where the module should clean up the object. A typical implementation just calls delete on the object, and for a ref counted object, perhaps just a dereference.

How is the object cleaned up?

The CleanupStoredContext is invoked by IIS when the parent object is being deleted. When this happens depends on the object itself. For instance, the IHttpContetxt is deleted when the request execution is fully complete.

IHttpSite can be cleaned up when multiple conditions occur: - Worker Process exit (Graceful shutdown) - Config change at the site/global scope.

For IHttpApplication, it is similar to the cleanup conditions for site, except for the fact that it will get recycled when the configuration at the application level changes.

Similar for IMetadataInfo, it is recycled when the configuration at the particular metapath changes.

Typical code flow to store config in IMetadataInfo.

Let’s say the module index for the native module was i.

• On new request, query the IMetadataInfo from the IHttpContext object.
• Check the ContextContainer in IMetadataInfo at slot i

• If the query returned empty:

  • create a new config object (which implementes IHttpStoredContext)
  • Set the object in the ContextContainer at slot i.
  • The set API can return HRESULT “ERROR_ALREADY_EXISTS”, which indicates that some other thread/request already set it while we were attempting to set the object ourselves. This only happens if our native module is not executing under any lock, so all requests are executing in parallel. In this case, the recommended approach is to delete the object allocated by this thread, and query the container for what was already set in it.
  • If set succeeds, nothing more to be done, continue execution.

• Else: Query successful, all is well, just use the object.