Creating Custom Configuration Settings in ASP.NET

The section contains two <add> tags that define the key/value pairs. You can retrieve the values via the built-in ConfigurationSettings property of the Page object. To begin, create a new Web Form in your project, name it customItems.aspx, and add this code to the Page_Load event:

   Dim aKey As String
   Response.Write("<h3>AppSettings</h3>")
   For Each aKey In ConfigurationSettings.AppSettings.Keys
      Response.Output.WriteLine(aKey & "=" & _
         ConfigurationSettings.AppSettings.Item(aKey))
   Next

Figure 1. ConfigSections: The relationship between configuration file sections, tags, and handlers.

Compile and run the customItems.aspx Web Form. You'll see the <AppSettings> tag values. The loop retrieves all the <add> tags from the <appSettings> section, and displays the key and value attribute values (see the sidebar "TIP: Using the Response.Output.WriteLine Method" for a discussion of how the code writes individual HTML lines). This simple key/value mechanism is perfect for many common needs, such as storing database connection strings at application scope; but it's not robust enough for more complex data. Fortunately, Microsoft also built in a mechanism for creating custom configuration data. Rather than reading a hard-coded list of tags recognized only via code within a specific application, the ASP.NET framework reads one or more <configSections> sections, which define the tag names the framework should expect to find in the remainder of the file and also define a class type and location for handling that particular type of content (see Figure 1).

As the ASP.NET engine parses the configuration file, it builds a list of the possible tags by reading the <configSections> element's <section> tags, each of which contains a name and a type, that define the names of the tags expected in the remainder of the document and a handler for that particular tag. A little experimentation shows you how this works. In the Web.config file for your project, add a new tag just before the ending </configuration> tag in the file.

   <configuration>
      <!—the existing web.config settings here -->
      <customItems>
      </customItems>
   </configuration>

Save the Web.config file and run the project. You'll get an "Unrecognized configuration in section 'customItems'" error. The error occurs because there's no section handler defined for the <customItems> tag. But if you look at the entire Web.config file, there are no handlers defined for any of the tags, which leads to the question: Where are the handlers defined? (If you're performing the steps as you read this article, remove the <customItems> tag from your Web.config file before you continue.)

It turns out that there are two configuration files for every Web application: a root machine.config file, stored in a system folder, and the Web.config file in your application's root folder. You can find the machine.config file in the $System$\Microsoft.NET\Framework\<version>\CONFIG folder, where <version> corresponds to the version of the framework installed and active on your server. The configuration settings in the machine.config file apply to all applications on your server unless overridden by more localized settings. If you look at the machine.config file, you'll see a <configSections> tag containing a set of <section> tags—and those tags define the handlers for the default tags you see in the web.config file. To make the process even simpler to understand, you can further group the <section> tags inside <sectionGroup> tags, each of which defines a set of handlers for related section tags.

The reason I brought up the machine.config file is because there are two ways to add custom tags. You can use one of the default System handler types to parse the content of your custom tags, or you can create your own handler.