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.

Imports System
Imports System.Configuration
Imports System.Web
Imports System.Web.Configuration
Imports System.Web.Security
Imports System.Reflection

Namespace Samples.AspNet

    ' Define a custom configuration.

    Public Class CustomConfiguration

        Public Sub New()

        End Sub 'New

        ' Define a custom section.

        Public Class CustomSection
            Inherits ConfigurationSection

            Private Const configString As String = "aString"

            Private Const configInteger As String = "anInteger"

            Private Const configTimeout As String = "aTimeout"

            <ConfigurationProperty(CustomSection.configString, DefaultValue:="default")> _
            Public Property aString() As String

                    Return CStr(Me(CustomSection.configString))
                End Get
                Set(ByVal value As String)
                    Me(CustomSection.configString) = value
                End Set
            End Property

            <ConfigurationProperty(CustomSection.configInteger, DefaultValue:=1)> _
            Public Property anInteger() As Integer

                    Return Fix(Me(CustomSection.configInteger))
                End Get
                Set(ByVal value As Integer)
                    Me(CustomSection.configInteger) = value
                End Set
            End Property

            <ConfigurationProperty(CustomSection.configTimeout)> _
            Public Property aTimeout() As TimeSpan

                    Return CType(Me(CustomSection.configTimeout), TimeSpan)
                End Get
                Set(ByVal value As TimeSpan)
                    Me(CustomSection.configTimeout) = value
                End Set
            End Property
        End Class 'CustomSection

        ' Create a custom section and save it in the
        ' application configuration file.
        Public Sub CreateCustomSection()

            Dim config As Configuration = WebConfigurationManager.OpenWebConfiguration("/ConfigSite")

            Dim section As CustomSection = config.Sections("CustomSection")

            If section Is Nothing Then

                ' Create section and add it to the configuration.
                section = New CustomSection()
                config.Sections.Add("CustomSection", section)
            End If

            ' Assign configuration settings.
            section.aTimeout = TimeSpan.FromSeconds(DateTime.Now.Second)

            section.anInteger = 1500

            section.aString = "Hello World"

            ' Save the changes.

        End Sub 'CreateCustomSection

        ' Get the custom section stored in 
        ' the configuration file.
        Public Function GetCustomSection() As String

            Dim config As Configuration = WebConfigurationManager.OpenWebConfiguration("/ConfigSite")

            Dim section As CustomSection = config.Sections("CustomSection")

            Dim currentSection As String = String.Empty

            If Not (section Is Nothing) Then
                currentSection = HttpContext.Current.Server.HtmlEncode(section.SectionInformation.GetRawXml())

                currentSection = "CustomSection does not exist"
            End If
            Return currentSection

        End Function 'GetCustomSection
    End Class 'CustomConfiguration

End Namespace

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