ASP.NET Syntax ASP.NET Configuration Sections
Defines an association between a configuration section handler and a configuration element.
<section name = "section name"
type = "configuration section handler class, assembly file name, version, culture, public key token"
allowDefinition= "Everywhere | MachineOnly | MachineToApplication | MachineToWebRoot"
allowLocation = "true | false"
restartOnExternalChanges = "true | false" />
The following sections describe attributes, child elements, and parent elements.
| Attribute |
Description |
| allowDefinition |
Optional Boolean attribute.
Applies to ASP.NET applications only.
Specifies which configuration file the section can be used in.
This attribute can be one of the following values ( defined in the ConfigurationAllowDefinition enumeration ) in order of decreasing scope.
| Value |
Description |
| Everywhere |
Allows the section to be configured in any configuration file or directory, as follows:
- Machine.config.
- Root Web.config.
- Web.config for an application.
- Virtual directory.
- Physical sub-directory in the application.
If no allowDefinition attribute is used, Everywhere is assumed. This is the default. |
| MachineToApplication |
Allows the section to be configured in one of the following files:
- Machine.config.
- Root Web.config.
- Web.config for an application.
This excludes Web.config files in virtual directories or a physical subdirectory in the application. |
| MachineToWebRoot |
Allows the section to be configured in one of the following files:
- Machine.config.
- Root Web.config.
Both the Machine.config and root Web.config files are located in %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG. |
| MachineOnly |
Allows the section to be configured only in the Machine.config file, which is located in %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG. |
|
| allowExeDefinition |
Optional Boolean attribute.
Applies to .NET Framework client applications only.
Specifies which configuration file the section can be used in.
This attribute can be one of the following values ( defined in the ConfigurationAllowExeDefinition enumeration ) in order of decreasing scope.
| Value |
Description |
| MachineToApplication |
Allows the section to be configured in one of the following files:
- Machine.config.
- Application configuration.
|
| MachineToRoamingUser |
|
| MachineToLocalUser |
|
| MachineOnly |
Allows the section to be configured only in the Machine.config file, which is located in %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG. |
|
| allowLocation |
Optional Boolean attribute.
Applies to ASP.NET applications only.
Specifies whether the section can be used within the location element.
The default is True. |
| name |
Required String attribute.
Specifies the name of the configuration section or element that is associated with the configuration section handler that is specified in the type attribute. This is the name of the element as it appears in the section settings area of the configuration file. |
| restartOnExternalChanges |
Optional Boolean attribute.
Does not apply to ASP.NET applications.
Specifies whether the application should restart, if the configuration data for the section changes. |
| type |
Required String attribute.
Specifies the name of the configuration section handler class that handles the processing of the configuration settings in the section or element that is specified in the name attribute. Use the following format:
type = "Fully qualified class name, assembly file name, version, culture, public key token"
The definition must match the assembly reference. For example, if the version number in the following example syntax does not match the assembly, an error occurs.
type = "MyConfigSectionHandler.MyHandler, MyCustomConfigurationHandler,
Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
The assembly file must be located in the same application directory as the Web.config file that defines the assembly file. In the case of the root Web.config file or the Machine.config file, the assembly file must be in %SystemRoot%\Microsoft.NET\Framework\version. |
None.
| Element |
Description |
| configuration |
Specifies the required root element in every configuration file that is used by the common language runtime and the .NET Framework applications. |
| configSections |
Specifies configuration section and namespace declarations. |
| sectionGroup |
Defines an association between a configuration section handler and a configuration section. |
A section element associates a configuration section handler with a configuration element or section. This is required because ASP.NET makes no presumptions about how to handle settings within a configuration file. Instead, ASP.NET delegates the processing of configuration data to configuration section handlers. Each section element identifies a configuration section or element and the associated class that is derived from ConfigurationSection that handles the configuration section or element. The section elements can be logically grouped in sectionGroup elements for organization and to help avoid naming conflicts. The section and sectionGroup elements are contained in the configSections element.
Configuration sections for the .NET configuration elements are defined in the Machine.config file and are too numerous to list here. The following excerpt from the Machine.config file defines the configuration section handler for the authentication element of the system.web section. Then, configuration settings are defined for the authentication element.
If a configuration section handler is not associated with a configuration element, ASP.NET issues the server error,
"Unrecognized configuration section element_name".
<configuration>
<configSections>
<sectionGroup name = "system.web"
type = "System.Web.Configuration.SystemWebSectionGroup, System.Web,
Version=%ASSEMBLY_VERSION%, Culture=neutral,
PublicKeyToken=%MICROSOFT_PUBLICKEY%">
<section name = "authentication"
type = "System.Web.Configuration.AuthenticationSection, System.Web,
Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
allowDefinition = "MachineToApplication" />
</sectionGroup>
</configSections>
<system.web>
<authentication mode = "Windows">
<forms name = ".ASPXAUTH"
loginUrl = "login.aspx"
defaultUrl = "default.aspx"
protection = "All"
timeout = "30"
path = "/"
requireSSL = "False"
slidingExpiration = "True"
cookieless = "UseCookies"
domain = ""
enableCrossAppRedirects = "False">
<credentials passwordFormat = "SHA1" />
</forms>
<passport redirectUrl = "internal" />
</authentication>
<!-- Other system.web elements -->
</system.web>
<!-- Other configuration settings -->
</configuration>
The following shows an excerpt from the root web.config file of asp.net.ph. The code example shows how a custom configuration section named sourceView ( and the settings for that section ) is defined.
<configuration xmlns = "http://schemas.microsoft.com/.NetConfiguration/v2.0">
<configSections>
<sectionGroup name = "system.web">
<section name = "sourceView"
type = "System.Configuration.NameValueSectionHandler, System,
Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
</sectionGroup>
</configSections>
<!-- Other configuration settings -->
<system.web>
<sourceView>
<add key = "root" value="d:\web projects\asp.net.ph" />
</sourceView>
<!-- Other system.web settings -->
</system.web>
</configuration>
<configSections> Section <configSections> sectionGroup Element ConfigurationSection Class