Understanding Section Handlers - App.config File

• Download demo project - 6.42 Kb
• Download source - 9.48 Kb

Introduction

This article explains configuration section handlers defined in the System.Configuration namespace and explains how to create custom section handlers by implementing the interface IConfigurationSectionHandler.

What we can do with App.config?

A configuration file can contain information that the application reads at run time. We can use configuration sections to specify this information in configuration files. The .NET Framework provides several predefined configuration sections and developers can also create custom configuration sections.

Configuration sections have two parts: a configuration section declaration and the configuration settings. We can put configuration section declarations and configuration settings in the machine configuration file or in the application configuration file. At run time, section handlers, which are classes that implement the IConfigurationSectionHandler interface, read settings in the machine configuration file first, followed by the application configuration file. Depending on the section handler, either the settings in the application file override the settings in the machine file or the settings from both files are merged.

Note: It’s not a good practice to specify application settings in machine.config file.

There are two types of configuration sections:

• Predefined configuration section (appSettings).
• User-Defined configuration section(s).

Predefined configuration Section (appSettings)

The .NET Framework provides a predefined configuration section called appSettings. This section is declared in the Machine.config file as follows:

<section name="appSettings" 
    type="System.Configuration.NameValueFileSectionHandler, 
      System, Version=1.0.5000.0, Culture=neutral, 
      PublicKeyToken=b77a5c561934e089"/>

The sample declaration of the appSettings is:

<appSettings file="appSettings.xml"/>

Application settings are defined in an external file, which should be in the application bin folder.

A sample appSettings.xml is:

<?xml version="1.0" encoding="utf-8"?> 
<appSettings>
    <add key="article" value="Configuration Sections"/>
    <add key="author" value="Palanisamy Veerasingam"/>
</appSettings>

or we can keep the appSettings in the App.config file itself:

<appSettings>
    <add key="author" value="Palanisamy Veerasingam"/>
    <add key="article" value="Configuration Sections"/>   
</appSettings>

ConfigurationSettings.AppSettings is a special property that provides a shortcut to application settings defined in the <appSettings> section of the configuration file. The following example shows how to retrieve the author name defined in the previous configuration section example:

public string GetAuthor()
{
    return (ConfigurationSettings.AppSettings["author"]);
}

User-Defined configuration sections or Custom configuration sections

Declaring custom configuration sections

<configSections>
    <section name="sampleSection"
    type="System.Configuration.SingleTagSectionHandler" />
</configSections>

The <section> element has two properties:

• The name attribute, which is the name of the element that contains the information the section handler reads.
• The type attribute, which is the name of the class that reads the information.

We can specify the following values to this type attribute:

• System.Configuration.NameValueSectionHandler – Provides name-value pair configuration information from a configuration section and returns System.Collections.Specialized.NameValueCollection object.
• System.Configuration.DictionarySectionHandler - Reads key-value pair configuration information for a configuration section and returns System.Collections.Hashtable object.
• System.Configuration.SingleTagSectionHandler - Reads key-value pair configuration information for a configuration section and returns the System.Collections.Hashtable object.
• System.Configuration.IgnoreSectionHandler - Provides a section handler definition for configuration sections read and handled by systems other than System.Configuration. To access this section, we have to parse the whole App.config XML file.
• User defined section handlers, which implement System.Configuration.IConfigurationSectionHandler.

Also, we can use <sectionGroup> tags for more detailed declaration of our sections as follows:

<sectionGroup name="mainGroup">
<sectionGroup name="subGroup">
    <section ...
</sectionGroup>
</sectionGroup>

I hope that by looking at the sample, you can understand the difference between these handlers. I not yet faced a situation to use IgnoreSectionHandler; in that case using a different file will be a good practice, I think so.

Declaring user-defined section handlers

To declare a user-defined section handler, create a class by implementing the interface System.Configuration.IconfigurationSectionHandler.

A sample class declaration is:

public class MyConfigHandler:IconfigurationSectionHandler{…}

There is only one method defined in the interface IconfigurationSectionHandler with the following signature:

object Create (object parent, object configContext, XmlNode section)

• parent - The configuration settings in a corresponding parent configuration section.
• configContext - An HttpConfigurationContext when Create is called from the ASP.NET configuration system. Otherwise, this parameter is reserved and is a null reference.
• section - The XmlNode that contains the configuration information from the configuration file. Provides direct access to the XML contents of the configuration section.
• Return value - A configuration object.

Sample SectionHandler class definition follows:

public class MyConfigHandler:IConfigurationSectionHandler
{
    public MyConfigHandler(){}

    public object Create(object parent, 
           object configContext, System.Xml.XmlNode section)
    {
        CCompanyAddr objCompany=new CCompanyAddr();
        objCompany.CompanyName = section.SelectSingleNode("companyName").InnerText;
        objCompany.DoorNo = section.SelectSingleNode("doorNo").InnerText;
        objCompany.Street = section.SelectSingleNode("street").InnerText;
        objCompany.City = section.SelectSingleNode("city").InnerText;
        objCompany.PostalCode = 
          Convert.ToInt64(section.SelectSingleNode("postalCode").InnerText);
        objCompany.Country = section.SelectSingleNode("country").InnerText;
        return objCompany;
    }
}

CCompanyAddr is another class defined with the above used properties with corresponding private members.

I have declared a section in the App.config file as follows:

<configSections>
    ...
    <sectionGroup name="companyInfo">
    <section name="companyAddress" 
            type="ConfigSections.MyConfigHandler,ConfigSections"/>
    </sectionGroup>

</configSections>

ConfigSections is the name of the namespace.

Then the section is declared in App.config file as follows:

<companyInfo> 
    <companyAddress> 
<companyName>Axxonet Solutions India Pvt Ltd</companyName>
<doorNo>1301</doorNo>
<street>13th Cross, Indira Nagar, 2nd Stage</street>
<city>Bangalore</city>
<postalCode>560038</postalCode>
<country>India</country>
    </companyAddress>
</companyInfo>

To read companyAddress settings from App.config, we have to use the ConfigurationSettings.GetConfig as follows:

CCompanyAddr obj = 
  (CCompanyAddr)ConfigurationSettings.GetConfig("companyInfo/companyAddress");

• ConfigurationSettings.GetConfig - Returns configuration settings for a user-defined configuration section.

Conclusion

I have written a very simple application to understand these section handlers, so I haven’t commented my code. Feel free to reply.