Classes Used to Create Custom Section Handlers

If none of the existing configuration sections meets your needs, you can create custom sections and implement handlers to read and write configuration data. The handler must be a .NET Framework class that extends the ConfigurationSection class.

Note

In the .NET Framework versions 1.0 and 1.1, a configuration section handler had to implement the IConfigurationSectionHandler interface, which is still supported in the .NET Framework version 2.0, but is deprecated.

Custom section handlers can be implemented by using one of two implementation models: the programmatic model or the declarative model.

Programmatic Implementation Model

This model requires that for each section attribute you create a property to get and/or set its value and add it to the internal property collection of the underlying ConfigurationElement base class.

Declarative Implementation Model

This model, which is also called the attributed model, allows you to define a section attribute by using a property and setting attributes. These attributes instruct the ASP.NET configuration system about the property types and their default values. With this information, which is obtained through reflection, the ASP.NET configuration system creates the section property objects and performs the required initialization. For more information about reflection, see Reflection in the .NET Framework.

Classes Used to Create Custom Section Handlers

The following table lists the classes that are used to programmatically create custom section handlers.

In each of the class topics, there are detailed code examples using either or both of the implementation models. Additionally, you can view a simplified declarative code example in How to: Create Custom Configuration Sections Using ConfigurationSection.

Classes used to implement a section handler	Description
ConfigurationSection class	Represents a section within a configuration file. Use the ConfigurationSection to implement a custom section handler type. Extend the ConfigurationSection class to provide custom handling and programmatic access to custom configuration sections. A section registers its handling type with an entry in the configSections element of a configuration file.
ConfigurationSectionCollection class	Represents a collection of related sections within a configuration file. Use the ConfigurationSectionCollection in the creation of custom types that extend the ConfigurationSection class. Additionally, use it when programmatically reading a configuration file through a collection of ConfigurationSection objects.
ConfigurationElementCollection class	Represents a collection of elements within a configuration file. Use the ConfigurationElementCollection to work with a collection of ConfigurationElement objects. Implement this class to add collections of custom ConfigurationElement elements to a ConfigurationSection.
ConfigurationElement class	Represents an element within a configuration file. Use the ConfigurationElement as the base class for the classes representing XML configuration elements, for instance ConfigurationSection. You can extend the ConfigurationElement class to represent a configuration element within a ConfigurationSection. You can also create a ConfigurationElementCollection of ConfigurationElement elements. Every ConfigurationElement object creates an internal ConfigurationPropertyCollection collection of ConfigurationProperty objects that represents either the element attributes or a collection of child elements.
ConfigurationCollectionAttribute class	Declaratively instructs the .NET Framework to instantiate a configuration element property collection. Use the ConfigurationCollectionAttribute to add attributes to a ConfigurationElementCollection property. This instructs the .NET Framework to instantiate the property and to initialize it using your custom ConfigurationElement values.
ConfigurationPropertyCollection class	The ConfigurationPropertyCollection class represents the collection of the ConfigurationProperty objects that can be attributes or ConfigurationElement objects of a configuration element.
ConfigurationProperty class	Represents an attribute or a child of a configuration element. In the case of a simple ConfigurationElement, the ConfigurationProperty objects represent attributes. In the case of more complex configuration elements such as a section containing subsections, the ConfigurationProperty objects can represent ConfigurationElement objects as well as attributes. The ConfigurationProperty class represents an individual configuration setting. This class allows you to get or set the name, type, and default value for a particular configuration entity (attribute or element) and specify whether the attribute is required, is a collection key, or represents a default element collection.
ConfigurationPropertyAttribute class	Declaratively instructs the .NET Framework to instantiate a configuration element property. You use the ConfigurationPropertyAttribute to decorate a configuration element property. This instructs the .NET Framework to instantiate and to initialize the property using the value of the decorating parameter.

See Also

Tasks

How to: Create Custom Configuration Sections Using ConfigurationSection

How to: Create Custom Configuration Sections Using IConfigurationSectionHandler

Concepts

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