ASP.NET Configuration File Structure (Sections and Section Handlers)
All ASP.NET configuration information resides in .config files. A Machine.config file and a root Web.config file located in a .NET Framework system folder provide default values for all Web sites that run on a server. A Web.config file for each Web site that is in the root folder of the site provides site-specific overrides to those values. Additional Web.config files can be located in a Web site's subfolders to provide overrides that apply specifically to those folders within that site.
A .config file contains XML that has a configuration element as the root node. Information inside this element is grouped into two main areas: the configuration section-handler declaration area, and the configuration section settings area.
A section handler is a .NET Framework class that implements the ConfigurationSection interface. The declaration area identifies the namespace and class name of each section handler class. Section handlers are used to read and set the settings that pertain to a section. The following example shows a simplified view of the XML structure of a Web.config file.
<configuration>
<!-- Configuration section-handler declaration area. -->
<configSections>
<section name="section1" type="section1Handler" />
<section name="section2" type="section2Handler" />
</configSections>
<!-- Configuration section settings area. -->
<section1>
<s1Setting1 attribute1="attr1" />
</section1>
<section2>
<s2Setting1 attribute1="attr1" />
</section2>
<system.web>
<authentication mode="Windows" />
</system.web>
</configuration>
In a Web.config file, sections can appear in the settings area that have not been declared in the declaration area if they are declared in a .config file at a higher level in the configuration hierarchy. For example, the system.web section is declared in the Machine.config file. Therefore, it does not have to be declared in individual, site-level Web.config files. If you declare a section in the Web.config file that is located in the root folder of a Web site, you can include settings for that section without including in Web.config files that are located in subfolders.
Configuration Section-Handler Declarations
The configuration section-handler declaration area is inside the configSections element in .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 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. 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). The following example shows a section-handler class that is mapped to a configuration settings section.
<section name="pages"
type="System.Web.Configuration.PagesSection, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
</section>
You declare a configuration section handler only once. Section handlers for the default ASP.NET configuration sections are already declared in the Machine.config file. The Web.config file for the Web site and other configuration files in ASP.NET applications automatically inherit the configuration handlers that are declared in the Machine.config file. You declare a new section handler only if you want to create a custom section-handler class that handles a custom settings section.
For information about the predefined ASP.NET configuration settings sections, see ASP.NET Configuration Settings. For information about how to define custom settings sections and how to develop your custom 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 the current configuration file or one of the root configuration files contains a configuration section element 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. The versionNumber value for versions 2.0, 3.0, and 3.5 of ASP.NET is v2.0.50727.
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 example expands on the simplified XML shown earlier in this topic by including elements from an actual Web.config file. Comments have been added for clarity and to indicate omissions.
<?xml version="1.0"?>
<configuration>
<!-- Configuration section-handler declaration area. -->
<configSections>
<sectionGroup name="system.web.extensions" type="System.Web.Configuration.SystemWebExtensionsSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<sectionGroup name="scripting" type="System.Web.Configuration.ScriptingSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<section name="scriptResourceHandler" type="System.Web.Configuration.ScriptingScriptResourceHandlerSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication"/>
<sectionGroup name="webServices" type="System.Web.Configuration.ScriptingWebServicesSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<section name="jsonSerialization" type="System.Web.Configuration.ScriptingJsonSerializationSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="Everywhere" />
<!-- Other <section /> elements -->
</sectionGroup>
</sectionGroup>
</sectionGroup>
<!-- A custom section in a custom group. -->
<sectionGroup name="pageAppearanceGroup">
<section name="pageAppearance" type="Samples.AspNet.PageAppearanceSection" allowLocation="true" allowDefinition="Everywhere"/>
</sectionGroup>
<!-- Other section and/or sectionGroup elements. -->
</configSections>
<!-- Configuration section settings area. -->
<!-- Settings for the custom section declared above. -->
<pageAppearanceGroup>
<pageAppearance remoteOnly="true">
<font name="TimesNewRoman" size="18"/>
<color background="000000" foreground="FFFFFF"/>
</pageAppearance>
</pageAppearanceGroup>
<!-- Settings for the default ASP.NET sections. -->
<appSettings/>
<connectionStrings/>
<system.web>
<compilation debug="false">
<assemblies>
<add assembly="System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
<add assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
<add assembly="System.Data.DataSetExtensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
<add assembly="System.Xml.Linq, Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
</assemblies>
</compilation>
<authentication mode="Windows" />
<!-- More elements for system.web -->
</system.web>
<!-- More ASP.NET sections. -->
</configuration>
Editing Issues
Because elements in the configuration sections must be well-formed XML, the elements and attributes are case-sensitive. For information about how to edit configuration settings, 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.
See Also
Tasks
How to: Create Custom Configuration Sections Using ConfigurationSection
How to: Create Custom Configuration Sections Using IConfigurationSectionHandler
Concepts
ASP.NET Configuration File Hierarchy and Inheritance
Other Resources
ASP.NET Web Site Administration