NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Custom Configuration Settings

It is possible for you to extend the standard set of settings with some of your own. To do this you will need to create your own Configuration Section Handler. This handler must be a NGWS class that implements the System.Web.Config.IConfigSectionHandler interface. It is responsible for interpreting and processing the XML settings defined within a specific portion of a Config.web file -- and then returning an appropriate configuration object based upon them. This returned configuration object can be any data-structure – it is not limited to any base configuration class or configuration format.

The IConfigSectionHandler interface is defined as:

namespace System.Web.Config
{
   public interface IConfigSectionHandler
   {
      public Object Create(Object parent, 
                           ConfigInput[] input, 
                           String path);
   }
}

IConfigSectionHandler exposes a single method Create that accepts three arguments – parent, input, and path. The parent parameter enables configuration factories to inherit settings calculated by the configuration section handler within a parent directory. The input parameter provides access to the raw XML contents of the configuration file’s setting. The path argument indicates the virtual path to the configuration factory that is responsible for calculating values.

The Create method is passed an array of ConfigInput objects that contain the XML relevant to the requested configuration file section (for example, the standard sections: <htttphandlers>, <sessionstate>, and so forth). An array is passed because it is possible for configuration file authors to partition their configuration data across multiple sections within the file. For example, there could be two <httphandlers> tag sections.

ConfigInput passes in an XML tree that is rooted at the base of the relevant configuration section. For example, a <httphandlers> configuration section handler would be provided a reference to the <httphandlers> element.

Configuration Inheritance

The object-based value returned from a call to Create represents the computed configuration data object for the particular node in the URL hierarchy. It will be passed as the “parent” argument to the configuration section handler handling subnodes deeper within the hierarchy. For instance, the configuration data returned for the URL "/MyApp/Sub1" would be passed as the parent value to the IConfigSectionHandler of "/MyApp/Sub1/Sub2". The only exception is if there is no parent configuration data (for example: when the data is computed by the root handler), in which case the “parent” argument is null.

You can use this value to help calculate subvalues (in which case the data is said to "inherit") or alternatively, ignore these values completely and simply use the current node’s values when calculating the appropriate configuration data.

For example, suppose a developer wanted to compute the configuration data of the <sessionstate> settings for the URL – “/401k/Order/”:

SessionStateConfig config = (SessionStateConfig)
                   Context.GetConfig(“sessionstate”, “/401k/Order/”);

This would result in the below psuedocode being executed:

// <sessionstate> section data handled by
// System.Web.Config.SessionStateConfigHandler
SessionStateConfigHandler sessionHandler = new
                                         SessionStateConfigHandler();

// Default settings for machine (declared in: c:\winnt\complus\Config.web)
inputFirst = InputFrom(“sessionstate”, “c:\winnt\complus\Config.web”);
outputFirst = sessionHandler.Create(null, input, “”);

// Overridden by settings at application level (declared in: c:\401k)
inputSecond = InputFrom(“sessionstate”, “c:\401k\Config.web”);
outputSecond = sessionHandler.Create(outputFirst, inputSecond, “/401k”);

// Overridden by settings at directory level (declared in:
// c:\401k\Order\Config.web)
inputThird = InputFrom(“sessionstate”, “c:\401k\Order\Config.web”);
outputThird = sessionHandler.Create(outputSecond, inputThird,
                                                      “/401k/Order”);

return outputThird;

Configuration Is Threadsafe and Immutable

It is important that you understand that since the configuration system caches the configuration objects returned by configuration section handlers, the configuration objects they generate should be both threadsafe and immutable - so that multiple callers who request the same configuration object get exactly the same results.

In particular, it is very important that a configuration section handler not modify the "parent" argument passed into the Create method. Even if the return value is conceptually just a small modification of the parent, actual modifications must be made on a clone of the parent instead of on the original.