Creating your own web.config section handler

Introduction

In my previous article I explained how to create your own web.config section that is handled by built-in section handlers. In this article I will show how to create your own section handler that can handle your custom sections.

IConfigurationSectionHandler interface

In order to create your own web.config section handler you need to create a class that implements IConfigurationSectionHandler interface. This interface resides in System.Configuration namespace. The interface consists of a single method called Create with following signature:

public object Create
(object parent, 
object configContext, 
System.Xml.XmlNode section)

The three parameters of the Create method are:

• Parent: This is the parent section
• configContext: This is used internally by ASP.NET and developer's should not use it.
• section: This is the most important parameter because this gives reference to the custom configuration section from the web.config file

Example

Let's assume that you want to put following configuration section in your web.config file:

<ContactInfo> 
<BusinessContact> 
<Contact> 
<ContactName>Some Name</ContactName> 
<ContactEmail>email@somedomain.com</ContactEmail> 
<ContactPhone>12345</ContactPhone> 
</Contact> 
</BusinessContact> 
</ContactInfo>

We will now follow steps outlined below to develop our section handler:

• Create a new project (CustomConfigSectionLib) in VS.NET of type class library
• Add a class to it called MyConfigSectionHandler
• At the top of the class make sure you are using System.Configuration and System.Xml namespace

using System.Configuration; 
using System.Xml;

• Modify the class defination to implement IConfigurationSectionHandler interface

public class 
MyConfigSectionHandler:IConfigurationSectionHandler 
{...}

• Create another class called MyConfig with three public properties (or variables) - ContactName, ContactEmail and ContactPhone

public class MyConfig 
{ 
public string ContactName; 
public string ContactEmail; 
public string ContactPhone; 
}

• The above class will be populated and returned by our configuration section handler when we read the section.
• Put defination of the Create method as shown below:

public object Create(
object parent, object configContext, 
System.Xml.XmlNode section) 
{ 
XmlNode node=section; 
MyConfig config=new MyConfig(); 
config.ContactName=node.ChildNodes[0].ChildNodes[0].Value; 
config.ContactEmail=node.ChildNodes[1].ChildNodes[0].Value; 
config.ContactPhone=node.ChildNodes[2].ChildNodes[0].Value; 
return config; 
}

• In the above code we created an instance of XmlNode class and pointed to the section parameter received. XmlNode class represents a node from an XML document. ASP.NET configuration framework passes the reference of our custom section to Create method.
• We then simply extract various child node values and assign them to an instance of MyConfig class.
• Finally we return the instance of MyConfig class to the caller.

Linking custom section handler and sections

If you observe above code, you will find that nowhere we have linked the custom section handler with the custom section. That needs to be done in web.config file itself and we will do that next.

<configSections>
<sectionGroup name="ContactInfo">
<sectionGroup name="BusinessContact">
<section name="Contact" 
type="CustomConfigSectionLib.MyConfigSectionHandler,
CustomConfigSectionLib"/>
         </sectionGroup>
      </sectionGroup>
   </configSections>

			

We put above markup between <configuration> and <system.web> tags of web.config. Here, we specify that the Contact section should be processed by CustomConfigSectionLib.MyConfigSectionHandler (fully qualified class name is required) class residing in CustomConfigSectionLib assembly. Note that by default VS.NET creates namespace name and assembly name same. Make sure to replace your own assembly name there.

Testing our section handler

In order to test our custom section handler follow these steps:

• Create a new project of type ASP.NET Web Application in VS.NET
• Add a webform to the project and put three labels on it. We will simply display values of our section in these labels.
• Make sure that your code behind uses following namespaces.

using CustomConfigSectionLib; 
using System.Configuration; 

• Add following code to the Page_Load event handler

MyConfig config; 
config=(MyConfig)ConfigurationSettings.GetConfig
("ContactInfo/BusinessContact/Contact"); 
lblName.Text=config.ContactName; 
lblEmail.Text=config.ContactEmail; 
lblPhone.Text=config.ContactPhone; 

• Here, we retrieve the values by calling GetConfig method of ConfigurationSettings class. Note that this method always returns an object and hence we need to typecast it to MyConfig.
• Compile the project and run the web form. You should get values from your configuration section displayed in the page.

Summary

ASP.NET configuration system is flexible enough to allow us create our own configuration sections. These sections can be processed by built-in section handlers or your own handler. In order to create your own section handler, you need to implement IConfigurationSectionHandler in some of your class. The Create() method of the interface provides access to your custom settings as XmlNode. Finally, you let ASP.NET know about your handler via <configSections> section.