ConfigurationSection Class
Assembly: System.Configuration (in system.configuration.dll)
You use the ConfigurationSection to implement a custom section 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.
Refer to the configuration file excerpt shown in the example next.
Note |
|---|
| In previous versions of the .NET Framework, configuration section handlers were used to make changes to configuration settings programmatically. Now, all of the default configuration sections are represented by classes that extend the ConfigurationSection class. |
-
Programmatic 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 bag of the underlying ConfigurationElement base class.
-
Declarative Model. This simpler model, also called attributed model, allows you to define a section attribute by using a property and decorate it with attributes. These attributes instruct the ASP.NET configuration system about the property types and their default values. With this information, obtained through reflection, the ASP.NET configuration system creates for you the section property objects and performs the required initialization.
-
Reading. You use GetSection or GetSectionGroup to read configuration information. Note the user or process that reads must have the following permissions:
-
Read permission on the configuration file at the current configuration hierarchy level.
-
Read permissions on all the parent configuration files.
-
Note |
|---|
| If you use a static GetSection method that takes a path parameter, the path parameter must refer to the application in which the code is running, otherwise the parameter is ignored and configuration information for the currently-running application is returned. |
-
Writing. You use one of the Save methods to write configuration information. Note the user or process that writes must have the following permissions:
-
Write permission on the configuration file and directory at the current configuration hierarchy level.
-
Read permissions on all the configuration files.
-
| Topic | Location |
|---|---|
| How to: Create Custom Configuration Sections Using IConfigurationSectionHandler | Configuring ASP .NET Web Applications |
| How to: Create Custom Configuration Sections Using ConfigurationSection | Configuring ASP .NET Web Applications |
| How to: Create Custom Configuration Sections Using IConfigurationSectionHandler | Configuring ASP .NET Web Applications |
| How to: Create Custom Configuration Sections Using ConfigurationSection | Configuring ASP .NET Web Applications |
| How to: Create Custom Configuration Sections Using IConfigurationSectionHandler | |
| How to: Create Custom Configuration Sections Using ConfigurationSection |
The following example shows how to implement a custom section programmatically.
Refer to ConfigurationElement for a complete example showing how to implement and use a custom section implemented using the attributed model.
' Define a custom section. ' The CustomSection type alows to define a custom section ' programmatically. NotInheritable Public Class CustomSection Inherits ConfigurationSection ' The collection (property bag) that conatains ' the section properties. Private Shared _Properties As ConfigurationPropertyCollection ' Internal flag to disable ' property setting. Private Shared _ReadOnly As Boolean ' The FileName property. Private Shared _FileName As New ConfigurationProperty( _ "fileName", GetType(String), _ "default.txt", _ ConfigurationPropertyOptions.IsRequired) ' The MasUsers property. Private Shared _MaxUsers As New ConfigurationProperty( _ "maxUsers", GetType(Long), _ CType(1000, Long), _ ConfigurationPropertyOptions.None) ' The MaxIdleTime property. Private Shared _MaxIdleTime As New ConfigurationProperty( _ "maxIdleTime", GetType(TimeSpan), _ TimeSpan.FromMinutes(5), _ ConfigurationPropertyOptions.IsRequired) ' CustomSection constructor. Public Sub New() ' Property initialization _Properties = _ New ConfigurationPropertyCollection() _Properties.Add(_FileName) _Properties.Add(_MaxUsers) _Properties.Add(_MaxIdleTime) End Sub 'New ' This is a key customization. ' It returns the initialized property bag. Protected Overrides ReadOnly Property Properties() _ As ConfigurationPropertyCollection Get Return _Properties End Get End Property Private Shadows ReadOnly Property IsReadOnly() As Boolean Get Return _ReadOnly End Get End Property ' Use this to disable property setting. Private Sub ThrowIfReadOnly(propertyName As String) If IsReadOnly Then Throw New ConfigurationErrorsException( _ "The property " + propertyName + " is read only.") End If End Sub 'ThrowIfReadOnly ' Customizes the use of CustomSection ' by setting _ReadOnly to false. ' Remember you must use it along with ThrowIfReadOnly. Protected Overrides Function GetRuntimeObject() As Object ' To enable property setting just assign true to ' the following flag. _ReadOnly = True Return MyBase.GetRuntimeObject() End Function 'GetRuntimeObject <StringValidator( _ InvalidCharacters:=" ~!@#$%^&*()[]{/;'""|\", _ MinLength:=1, MaxLength:=60)> _ Public Property FileName() As String Get Return CStr(Me("fileName")) End Get Set(ByVal value As String) ' With this you disable the setting. ' Renemmber that the _ReadOnly flag must ' be set to true in the GetRuntimeObject. ThrowIfReadOnly("FileName") Me("fileName") = value End Set End Property <LongValidator( _ MinValue:=1, MaxValue:=1000000, _ ExcludeRange:=False)> _ Public Property MaxUsers() As Long Get Return Fix(Me("maxUsers")) End Get Set(ByVal value As Long) Me("maxUsers") = Value End Set End Property <TimeSpanValidator( _ MinValueString:="0:0:30", _ MaxValueString:="5:00:0", ExcludeRange:=False)> _ Public Property MaxIdleTime() As TimeSpan Get Return CType(Me("maxIdleTime"), TimeSpan) End Get Set(ByVal value As TimeSpan) Me("maxIdleTime") = Value End Set End Property End Class 'CustomSection
This is an excerpt of the configuration file as it applies to the previous example.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSections>
<section name="CustomSection" type="Samples.AspNet, CustomConfigurationSection, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" restartOnExternalChanges="true" />
</configSections>
<CustomSection fileName="default.txt" maxUsers="1000" maxIdleTime="00:15:00" />
</configuration>
System.Configuration.ConfigurationElement
System.Configuration.ConfigurationSection
Derived Classes
Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.
Note