Introduction
Custom sections of an ASP.NET Configuration File are customized sections that a developer configures by himself. In this case, the developer also sets their attributes and elements to suit special application needs in terms of settings. These kinds of sections are always located at the top of the configuration files before all others settings. They are wrapped in "<configSections></configSections>" tags. Those kinds of settings are very useful, especially in the case where customized or specific settings are required to be set and the use cases depending on them are so numerous that one cannot enumerate them at all. These kinds of sections have some child elements as are shown in the following table.
The section and the section Group tags need further clarifications about how to define and use them. Therefore, I'll take them one by one and I explain the meaning of each one.
Section
The section ties a configuration section handler to a configuration section element. In this context, the configuration section handler is a class like SingleTagSectionHandler, ApplicationSettingGroup, SystemWebSectionGroup, AuthentificationSection and others that handle sections' elements. Furthermore, you can even create your own configuration section handler. This concept is applied in the both development contexts. I mean the web application and the Windows or client application context. It takes some arguments that I will indicate where each of them should be used either in a web application configuration context or in a windows application configuration context.
Used in both contexts:
- name: The name of the corresponding section
| Element |
Description |
| "clear" |
Removes all references to inherited sections and section groups, allowing only the sections and section groups added by the current given elements. |
| "remove" |
Removes a reference to an inherited section and section group. |
| "section" |
Defines an association between a configuration section handler and a configuration element.
<section name="section name"
type="configuration section handler, assembly file name, version, culture, public key token"
allowDefinition= "Everywhere|MachineOnly|MachineToApplication|MachineToWebRoot"
allowExeDefinition= "MachineOnly|MachineToApplication|MachineToRoamingUser|MachineToLocalUser"
allowLocation="True|False" restartOnExternalChanges="True|False" />
|
| "sectionGroup" |
Defines an association between a configuration section handler and a configuration section. |
Used in both configuration contexts:
- type: It is composed by five elements, the first one represents the class that handles the given section, and it must be a fully qualified class name like "System.Web.Configuration.ConfigurationSection", the second one represents the corresponding assembly name like "System. Configuration", the third element is the version such 1.0.0.0, the fourth one specifies the culture like "en-US" or "en-UK" that represents the (language/region) couple, if no culture has been set then set its value to neutral. And of course, the fifth element is the public key token, this attribute is used for encryption issues, it can have the null value if there is not need to use.
Used only in a windows application configuration context:
- allowExeDefinition: It is optional at the contrast of the two first elements above. It specifies where the configuration section can be defined. It takes four values corresponding to the four situations
- MachineToApplication: Indicates that the section can be configured only in the machine configuration file or in the application configuration file.
- MachineOnly: Indicates that section can be configured only in the machine configuration file.
- MachineToRoamingUser: Indicates that the section can be configured in the machine configuration file or in the configuration file located in the roaming user directory.
- MachineToLocalUser: Indicates that the section can be configured in the machine configuration file or in the configuration file located in the local user directory.
Used only in a web application configuration context:
- allowDefinition: It is almost the same as the previous attribute except that it is used in a web application configuration context. It specifies where the configuration section can be defined. It takes four values too, that correspond to the four situations.
- Everywhere: Indicates that the section can be configured in every location or directory.
- MachineToApplication: Indicates that the section can be configured in the machine configuration file, the web configuration file and in the configuration file located in the root of the web application.
- MachineToWebRoot: Indicates that the section can be configured only in both emplacements, I mean, the configuration file located in the root of the web application and also in the machine configuration file.
- MachineOnly: Indicates that the section can be configured only in the machine configuration file.
Used only in a web application configuration context:
- allowLocation: It is optional. This Boolean attribute indicates whether the section can be used within a location element or not.
Used only in a windows application configuration context:
- restartOnExtenalChanges: It is an optional element too, it indicates whether an application should be restarted after settings have changed.
SectionGroup
It simply represents a group of common specified sections within a configuration file; in other words, it is a sections container and this is very useful for organizational purposes, moreover, it avoids certain naming conflicts. A section group has some arguments that are:
| Element |
Description |
| name |
The section group name, it is required to specify the name of the section group |
| type |
The section group type indicates the configuration section group handler class, the assembly, the version, the culture and the public key token |
This figure gives a clear idea of the data structure wrapped in the "<configSections></configSections>":
![]()
After adding a customized section into the configuration files the following two things happen:
- The section elements are added and wrapped in the "<configSections></configSections>" tags
- The section element(s) is (are) added just after the previous tags.
To discover how to create a custom section and how to handle it, please refer to the part II of this article.