ASP.NET Configuration File Structure (Sections and Section Handlers) 

All ASP.NET configuration information resides inside the configuration element in Web.config files. Configuration information inside this element is grouped into two main areas: the configuration section-handler declaration area and the configuration section settings area.

Configuration Section-Handler Declarations

The configuration section-handler declaration area resides inside the configSections element in Web.config files. It contains ASP.NET configuration section elements where section handlers are declared. These configuration section-handler declarations can be nested in sectionGroup elements to help organize the configuration information. Typically, sectionGroup elements represent the namespace to which the configuration settings apply. For example, all of the ASP.NET configuration section handlers are grouped in the system.web section group, as shown in the following code example.

    <sectionGroup name="system.web"
      type="System.Web.Configuration.SystemWebSectionGroup, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
      <!-- <section /> elements. -->
    </sectionGroup>

There is a section-handler declaration for each configuration section in the configuration section settings area. A section handler is a .NET Framework class that implements the ConfigurationSection interface. Section-handler declarations contain the name of a configuration settings section (such as pages) and the name of the section-handler class that processes configuration data in that section (such as System.Web.Configuration.PagesSection). This is illustrated in the following code example.

      <section name="pages"
        type="System.Web.Configuration.PagesSection, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
      </section>

You need to declare a configuration section handler only once. Section handlers for the default ASP.NET configuration sections are already declared in the default Machine.config file. The root Web.config file and other configuration files in ASP.NET applications automatically inherit the configuration handlers that are declared in the Machine.config file. You only need to declare a new section handler if you create a custom section-handler class that handles a custom settings section.

The predefined ASP.NET configuration settings sections are listed in ASP.NET Configuration Settings. For information about defining your own custom settings sections and developing your own configuration section handlers to manage them, see Classes Used to Create Custom Section Handlers and How to: Create Custom Configuration Sections Using ConfigurationSection.

Configuration Section Settings

The configuration section settings area follows the configuration section-handler declaration area and contains the actual configuration settings.

By default, either internally or in one of the root configuration files, there is a configuration section element specified for every section and sectionGroup element in the configSections area. You can view these defaults in the systemroot\Microsoft.NET\Framework\versionNumber\CONFIG\Machine.config.comments file.

A configuration section element might also contain child elements that are handled by the same section handler as the parent. For example, the following pages element contains a namespaces element that has no corresponding section handler because it is handled by the pages section handler.

  <pages
    buffer="true"
    enableSessionState="true"
    asyncTimeout="45"
  <!-- Other attributes. -->
  >
    <namespaces>
      <add namespace="System" />
      <add namespace="System.Collections" />
    </namespaces>
  </pages>

Example from a Web.config File

The following code example shows where the previous code examples fit into a Web.config file. Notice that the namespaces element of the pages element does not have a configuration section-handler declaration. This is because the System.Web.Configuration.PagesSection section handler handles all child elements of the pages settings section.

<?xml version="1.0" encoding="us-ascii"?>
<configuration>

<!-- Configuration section-handler declaration area. -->
  <configSections>
    <sectionGroup name="system.web"
      type="System.Web.Configuration.SystemWebSectionGroup, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
      <section
        name="pages" 
        type="System.Web.Configuration.PagesSection, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
      />
      <!-- Other <section /> elements. -->
    </sectionGroup>
    <!-- Other <sectionGroup /> and <section /> elements. -->
  </configSections>

<!-- Configuration section settings area. -->
  <pages
    buffer="true"
    enableSessionState="true"
    asyncTimeout="45"
  <!-- Other attributes. -->
  >
    <namespaces>
      <add namespace="System" />
      <add namespace="System.Collections" />
    </namespaces>
  </pages>
  <!-- Other section settings elements. -->

</configuration>

Editing Issues

Because elements in the configuration sections must be well-formed XML, the elements and attributes are case-sensitive. There are many ways to edit configuration settings. For more information, see Editing ASP.NET Configuration Files.

Custom configuration section handlers must be created programmatically before you can use custom section elements in your ASP.NET configuration files. For more information, see How to: Create Custom Configuration Sections Using ConfigurationSection.

Path Attributes in Configuration Files

When referring to a Web application path, path attributes in Web.config files can start with the "~/" shortcut which indicates the application root. For more information, see ASP.NET Web Site Paths.

See Also

Tasks

How to: Create Custom Configuration Sections Using ConfigurationSection
How to: Create Custom Configuration Sections Using IConfigurationSectionHandler

Other Resources

Configuring ASP.NET Applications
ASP.NET Configuration Settings
Configuring Applications