ASP.NET Configuration Logical Model

Understanding the organizational principles behind configuration can help you to better use this important system feature. The configuration settings can control an application's behavior at run time, so that you do not necessarily need to rebuild it. This topic describes the logical organization of the ASP.NET configuration sections, the related programming model, and their relationships.


For information about the configuration files' hierarchy or their interdependence, see the documentation areas listed in the See Also section.

A configuration file contains all or some of the following logical areas. If a particular area is not defined, the file in question inherits that area from the parent file in the configuration file hierarchy. The logical areas are:

  • Configuration handlers. This area, delimited by the opening and closing configSections tags, contains the definitions for the handlers associated with the sections. A handler is a class that implements the IConfigurationSectionHandler interface and interprets the settings and related values of the associated configuration section. It is important to note that each section in a configuration file must have a handler. If you include a section without an associated handler, ASP.NET throws an exception.

  • Configuration sections. The configuration sections are the building blocks of a configuration file and contain the actual settings. Each section name should match the name declared in its related section handler. A section can contain multiple settings and other child sections.

  • Configuration section attributes. These are the section attributes defined by names and related values.

  • Configuration groups. You can contain configuration sections in section groups. These groups are used for organizational purposes, and can be defined more than once in a single configuration file if each group contains different sections. One common group is system.web. It contains the definitions for all the configuration sections that apply to ASP.NET. Notice that the name of the group is the same as the .NET Framework namespace System.Web.

A special role is played by the location Element (ASP.NET Settings Schema). The location element specifies the resource that child configuration settings apply to and is also used to lock configuration settings, preventing the settings from being overridden by child configuration files. Refer to Locking Configuration Settings.

Configuration Section Relationships

To effectively use the configuration system, you must understand how the various configuration sections are connected and how they work together. There are two types of relationships between configuration sections:

  • Organizational connection. The simplest connection is the one implied by the configuration file organization. This connection manifests itself as the nesting of configuration sections. Consider for example the compilation section and its subsections, the healthMonitoring section and its subsections, and so on.

  • System connection. A more subtle connection is the one between different non-nested sections. An example is the relationship that exists between authentication and authorization; another is the relationship between securityPolicy and trust; yet another is between authentication and membership.

Configuration Programming Model

The ASP.NET configuration programming model is mainly provided by the types defined in the System.Configuration, System.Web.Configuration, and System.Configuration.Provider namespaces.

These types give you a flexible API that not only allows access to the underlying configuration but also helps you to extend it by allowing the creation of custom sections and handlers.

The following example shows the API flexibility and simplicity by quickly creating a custom section.

using System;
using System.Configuration;
using System.Web;
using System.Web.Configuration;
using System.Web.Security;
using System.Reflection;

namespace Samples.AspNet
    // Define a custom configuration.
    public class CustomConfiguration

        public CustomConfiguration()


        // Define a custom section.
        public class CustomSection : ConfigurationSection

            const string configString = "aString";

            const string configInteger = "anInteger";

            const string configTimeout = "aTimeout";


                DefaultValue = "default")]

            public string aString

                get { return (string)base[CustomSection.configString]; }

                set { base[CustomSection.configString] = value; }



                DefaultValue = 1)]

            public int anInteger

                get { return (int)base[CustomSection.configInteger]; }

                set { base[CustomSection.configInteger] = value; }



            public TimeSpan aTimeout

                get { return (TimeSpan)base[CustomSection.configTimeout]; }

                set { base[CustomSection.configTimeout] = value; }



        // Create a custom section and save it in the
        // application configuration file.
        public void CreateCustomSection()

            Configuration config =

            CustomSection section =
                config.Sections["CustomSection"] as CustomSection;

            if (section == null)

                // Create section and add it to the configuration.
                section = new CustomSection();
                config.Sections.Add("CustomSection", section);


            // Assign configuration settings.
            section.aTimeout = 

            section.anInteger = 1500;

            section.aString = "Hello World";

            // Save the changes.



        // Get the custom section stored in 
        // the configuration file.
        public string GetCustomSection()

            Configuration config =

            CustomSection section =
                config.Sections["CustomSection"] as CustomSection;

            string currentSection = string.Empty;

            if (section != null)
                currentSection = HttpContext.Current.Server.HtmlEncode(

                currentSection = "CustomSection does not exist";

            return currentSection;


You can add the preceding source code to the App_Code directory of a Web application and run it by executing the following example.

[Visual Basic]

Imports System
Imports System.Configuration
Imports System.Web
Imports Samples.AspNet

Partial Class _Default
    Inherits System.Web.UI.Page
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
        ' Create a custom section.
        Dim cc As New CustomConfiguration()

        ' Display the section settings.
        CustomId.Text = cc.GetCustomSection()

    End Sub 'Page_Load
End Class


using System;
using System.Configuration;
using System.Web;
using Samples.AspNet;

public partial class _Default : System.Web.UI.Page 
    protected void Page_Load(object sender, EventArgs e)
        // Create a custom section.
        CustomConfiguration cc = 
            new CustomConfiguration();

        // Display the section settings.
        CustomId.Text = cc.GetCustomSection();

After you run the preceding example, the Web.config file associated with the application contains the following custom section definitions.


      <section name="CustomSection" 
        type="Samples.AspNet.CustomConfiguration+CustomSection, App_Code" />

    <CustomSection aString="Hello World" anInteger="1500" aTimeout="00:00:34" />


Community Additions