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.