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. |
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. |
|
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. |
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. |
|
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. |
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)