5 out of 6 rated this helpful - Rate this topic

How to: Create Custom Configuration Sections Using ConfigurationSection

You can extend ASP.NET configuration settings with XML configuration elements of your own. To do this, you create a custom configuration section handler. The handler must be a .NET Framework class that inherits from the System.Configuration.ConfigurationSection class. The section handler interprets and processes the settings that are defined in XML configuration elements in a specific section of a Web.config file. You can read and write these settings through the handler's properties.

To create a custom configuration section handler

  1. Create a public class that inherits from the System.Configuration.ConfigurationSection class.

  2. Add code to define the section's attributes and elements.

    The following example shows how to create a handler for a custom configuration section named "PageAppearance." The section has a RemoteOnly attribute and Font and Color elements. The code shows how to use string, integer, and Boolean attributes. It also shows how to use string and integer validators for those attributes. (The Boolean attribute is automatically validated.) The validators check the format of the configuration markup at run time and throw exceptions if the values provided for the custom attributes do not meet the specified criteria.

    
    using System;
    using System.Collections;
    using System.Text;
    using System.Configuration;
    using System.Xml;
    
    namespace Samples.AspNet
    {
        public class PageAppearanceSection : ConfigurationSection
        {
            // Create a "remoteOnly" attribute.
            [ConfigurationProperty("remoteOnly", DefaultValue = "false", IsRequired = false)]
            public Boolean RemoteOnly
            {
                get
                { 
                    return (Boolean)this["remoteOnly"]; 
                }
                set
                { 
                    this["remoteOnly"] = value; 
                }
            }
    
            // Create a "font" element.
            [ConfigurationProperty("font")]
            public FontElement Font
            {
                get
                { 
                    return (FontElement)this["font"]; }
                set
                { this["font"] = value; }
            }
    
            // Create a "color element."
            [ConfigurationProperty("color")]
            public ColorElement Color
            {
                get
                {
                    return (ColorElement)this["color"];
                }
                set
                { this["color"] = value; }
            }
        }
    
        // Define the "font" element
        // with "name" and "size" attributes.
        public class FontElement : ConfigurationElement
        {
            [ConfigurationProperty("name", DefaultValue="Arial", IsRequired = true)]
            [StringValidator(InvalidCharacters = "~!@#$%^&*()[]{}/;'\"|\\", MinLength = 1, MaxLength = 60)]
            public String Name
            {
                get
                {
                    return (String)this["name"];
                }
                set
                {
                    this["name"] = value;
                }
            }
    
            [ConfigurationProperty("size", DefaultValue = "12", IsRequired = false)]
            [IntegerValidator(ExcludeRange = false, MaxValue = 24, MinValue = 6)]
            public int Size
            {
                get
                { return (int)this["size"]; }
                set
                { this["size"] = value; }
            }
        }
    
        // Define the "color" element 
        // with "background" and "foreground" attributes.
        public class ColorElement : ConfigurationElement
        {
            [ConfigurationProperty("background", DefaultValue = "FFFFFF", IsRequired = true)]
            [StringValidator(InvalidCharacters = "~!@#$%^&*()[]{}/;'\"|\\GHIJKLMNOPQRSTUVWXYZ", MinLength = 6, MaxLength = 6)]
            public String Background
            {
                get
                {
                    return (String)this["background"];
                }
                set
                {
                    this["background"] = value;
                }
            }
    
            [ConfigurationProperty("foreground", DefaultValue = "000000", IsRequired = true)]
            [StringValidator(InvalidCharacters = "~!@#$%^&*()[]{}/;'\"|\\GHIJKLMNOPQRSTUVWXYZ", MinLength = 6, MaxLength = 6)]
            public String Foreground
            {
                get
                {
                    return (String)this["foreground"];
                }
                set
                {
                    this["foreground"] = value;
                }
            }
    
        }
    
    }
    
    
    

    This example uses the declarative model. A configuration section handler can also be implemented programmatically. For an example, see Classes Used to Create Custom Section Handlers and the System.Configuration.ConfigurationSection class overview.

To add a custom section handler to an ASP.NET configuration file

  1. In the Web.config file, add a sectionGroup element and a section element inside the configSections element, as shown in the following example. The declaration associates the custom section handler with the section name.

    NoteNote

    Nesting a section element in a sectionGroup is optional, but we recommend doing this to help organize configuration data.

    <configuration>
    <!-- Configuration section-handler declaration area. -->
      <configSections>
        <sectionGroup name="pageAppearanceGroup">
          <section 
            name="pageAppearance" 
            type="Samples.AspNet.PageAppearanceSection" 
            allowLocation="true" 
            allowDefinition="Everywhere"
          />
        </sectionGroup>
          <!-- Other <section> and <sectionGroup> elements. -->
      </configSections>
    
      <!-- Configuration section settings area. -->
    
    </configuration>
    

    You can add the section-handler declaration in a different configuration file than the one where you add the custom configuration elements, providing that the configuration file where the section handler is declared is higher in the configuration file hierarchy. If you add the section handler declaration to a configuration file that is outside of your application, you must do the following:

    • Include the assembly that defines the section in the same directory as the Web.config file.

    • Ensure that the type attribute of the section element matches the manifest of the assembly (ensure that you specify both the correct namespace and type name).

    If either of these conditions is not fulfilled, a configuration error will be thrown. For more information, see ASP.NET Configuration File Hierarchy and Inheritance.

  2. Add custom configuration elements in the configuration section settings area of the Web.config file, as shown in the following example:

    <configuration>
    
    <!-- Configuration section-handler declaration area. -->
    
      <!-- Configuration section settings area. -->
      <pageAppearanceGroup>
        <pageAppearance remoteOnly="true">
          <font name="TimesNewRoman" size="18"/>
          <color background="000000" foreground="FFFFFF"/>
        </pageAppearance>
      </pageAppearanceGroup>
    
      <!-- Other configuration settings, such as system.web -->
    
    </configuration>
    

To programmatically access custom configuration data

  • Get an instance of the custom configuration object and use the GetSection method or the GetSection method to populate it.

    The following example shows an ASP.NET Web page that works with the previous examples to enumerate the attributes and child elements of the custom configuration section.

    
    
    <%@ Page Language="C#" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    
    <script runat="server">
      protected void Page_Load(object sender, EventArgs e)
      {
        Samples.AspNet.PageAppearanceSection config =
            (Samples.AspNet.PageAppearanceSection)System.Configuration.ConfigurationManager.GetSection(
            "pageAppearanceGroup/pageAppearance");
    
        Response.Write("<h2>Settings in the PageAppearance Section:</h2>");
        Response.Write(string.Format("RemoteOnly: {0}<br>", 
            config.RemoteOnly));
        Response.Write(string.Format("Font name and size: {0} {1}<br>",
            config.Font.Name, config.Font.Size));
        Response.Write(
            string.Format("Background and foreground color: {0} {1}<br>",
            config.Color.Background, config.Color.Foreground));
      }
    </script>
    
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head runat="server">
      <title>Custom Configuration Section Example</title>
    </head>
    <body>
      <form id="form1" runat="server">
      <div>
        <h1>
      </div>
      </form>
    </body>
    </html>
    
    
    
Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Much simple, easy configuration framework
Developers, please take a look Cinchoo framework for easy, simple and automatic configuration management for different sources like Xml, Ini, Registry, Database etc. Please visit http://www.cinchoo.com for more information.
This is ALMOST helpful
but my config looks like this: <configuration> <serviceGroup> <services> <service name="DPS Mail Reader" server="local" order="0" /> <service name="DPS Queue Processor" server="local" order="1" /> </services> </serviceGroup> </configuration> How can I loop through these elements?
IConfigurationSectionHandler problem
Tried 'tweaking' this code to store the image sizes for my CMS (to run image resizing against...each site will have different static sizes) and get a complaint that the custom class does not inherit from 'System.Configuration.IConfigurationSectionHandler'.

What could i have done differently that would require this interface to be used instead? AFAFIK i've not added or removed anything, just changed variable names and internal object definitions - nothing that should require a different interface to read the data out. Or have i missed something? What could cause this?
How to get many sections?
If I have more than one pageAppearance section within the pageAppearanceGroup, how can I get them all in ASP.NET side? For instance, if my config file data is something like this, how can I retrieve them all? $0$0 $0 $0 $0<pageAppearanceGroup>$0 $0    <pageAppearance remoteOnly="true">$0 $0        <font name="TimesNewRoman" size="18"/>$0 $0        <color background="000000" foreground="FFFFFF"/>$0 $0    </pageAppearance>$0 $0    <pageAppearance remoteOnly="false">$0 $0        <font name="TimesNewRoman" size="24"/>$0 $0        <color background="000000" foreground="000000"/>$0 $0    </pageAppearance>$0 $0</pageAppearanceGroup>$0 $0
Why doesn't it work in App.Config?
I copied and pasted into Web.Config. No problem, It' s work. But, when I implemented same process for App.Config , occured an error. Why? Error Detail : An error occurred creating the configuration section handler for pageAppearanceGroup/pageAppearance: Could not load type 'Samples.AspNet.PageAppearanceSection' from assembly 'System.Configuration, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.


Change the attribute to the following

<section
name="SomeName"
type="NameSpace.ClassName, AssemblyName"
allowLocation="false"
allowDefinition="Everywhere"
/>

Where assembly name could be the NameSpace name as well or different. just use the .EXE name without the .EXE
Web.Config to App.Config - solution
Problem is in parametr assemblyname. When you build web application your custom configsection class will be in separate DLL assembly. But when you building winform application your custom configsection class will be typicaly in EXE assembly.
Web.Config to App.Config
Tulumen,

If you've moved the custom section from a web.config to an app.config (e.g. from ASP.NET to a WinForms app) you'll need to change the "type" attribute.  The type attribute is the fully qualified object name for the class handling your seciton, followed by a comma, then the assembly name containing the class.  As you're no longer in ASP.NET, the namespace in the type attribute in the example no longer works. 

For example.  I have a custom section in a WinForms app:

<configSections>
  <section name="MySectionName" type="MyNameSpace.MyClass, MyAssemblyName"/>
</configSections>

Read up on on the type attribute if my example isn't enough.  Hope this helps.

b