ConfigurationElement Class
Assembly: System.Configuration (in system.configuration.dll)
The ConfigurationElement is an abstract class, so it cannot be instantiated. It represents an element within a configuration file.
Note |
|---|
| An element within a configuration file refers to a basic XML element or a section. The basic element is a simple XML tag with related attributes, if any. In its simplest form, a section coincides with a basic element. Complex sections can contain one or more basic elements, a collection of elements, and other sections. |
The ConfigurationElement is used 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 section. You can also create a ConfigurationElementCollection collection of ConfigurationElement elements, as shown in the next example.
-
Handling Configuration. To handle configuration information using the standard types, use one of the following approaches.
-
Extending Configuration Standard Types. You can also extend the standard configuration types such as ConfigurationElement, ConfigurationElementCollection, ConfigurationProperty, and ConfigurationSection using either a programmatic or a declarative (attributed) model. Refer to the ConfigurationSection class for an example of how to extend a standard configuration type programmatically. Refer to the ConfigurationElement class for an example of how to extend a standard configuration type using the attributed model.
-
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.
-
-
Programmatic Model. This model requires that for each element 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 the attributed model, allows you to define an element attribute by using a property and then 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 the element property objects for you and performs the required initialization.
The following code example shows how to implement a custom ConfigurationElement.
This element is used by a custom section to define a custom section or a custom element collection.
Imports System Imports System.Configuration Imports System.Collections ' Define the UrlConfigElement. Public Class UrlConfigElement Inherits ConfigurationElement ' Test flag. Private Shared _displayIt _ As Boolean = False Public Sub New(ByVal newName As String, _ ByVal newUrl As String, _ ByVal newPort As Integer) Name = newName Url = newUrl Port = newPort End Sub 'New Public Sub New() End Sub 'New Public Sub New(ByVal elementName As String) Name = elementName End Sub 'New <ConfigurationProperty("name", _ DefaultValue:="Microsoft", _ IsRequired:=True, _ IsKey:=True)> _ Public Property Name() As String Get Return CStr(Me("name")) End Get Set(ByVal value As String) Me("name") = value End Set End Property <ConfigurationProperty("url", _ DefaultValue:="http://www.microsoft.com", _ IsRequired:=True), _ RegexStringValidator("\w+:\/\/[\w.]+\S*")> _ Public Property Url() As String Get Return CStr(Me("url")) End Get Set(ByVal value As String) Me("url") = value End Set End Property <ConfigurationProperty("port", _ DefaultValue:=0, _ IsRequired:=False), _ IntegerValidator(MinValue:=0, _ MaxValue:=8080, ExcludeRange:=False)> _ Public Property Port() As Integer Get Return Fix(Me("port")) End Get Set(ByVal value As Integer) Me("port") = value End Set End Property Protected Overrides Sub DeserializeElement(ByVal reader _ As System.Xml.XmlReader, _ ByVal serializeCollectionKey As Boolean) MyBase.DeserializeElement(reader, _ serializeCollectionKey) ' Enter your custom processing code here. If _displayIt Then Console.WriteLine( _ "UrlConfigElement.DeserializeElement({0, {1) called", _ IIf(reader Is Nothing, "null", _ reader.ToString()), _ serializeCollectionKey.ToString()) End If End Sub 'DeserializeElement Protected Overrides Function SerializeElement(ByVal writer _ As System.Xml.XmlWriter, _ ByVal serializeCollectionKey As Boolean) As Boolean Dim ret As Boolean = _ MyBase.SerializeElement(writer, _ serializeCollectionKey) ' Enter your custom processing code here. If _displayIt Then Console.WriteLine( _ "UrlConfigElement.SerializeElement({0, {1) called = {2", _ IIf(writer Is Nothing, "null", _ writer.ToString()), _ serializeCollectionKey.ToString(), _ ret.ToString()) End If Return ret End Function 'SerializeElement Protected Overrides Function IsModified() As Boolean Dim ret As Boolean = MyBase.IsModified() ' Enter your custom processing code here. Console.WriteLine("UrlConfigElement.IsModified() called.") Return ret End Function 'IsModified
The following configuration excerpt is used by the above example.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<configSections>
<section name="MyUrls" type="Samples.AspNet.Configuration.UrlsSection, ConfigurationElement, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" restartOnExternalChanges="true" />
</configSections>
<MyUrls lockAllElementsExcept="urls">
<simple
name="Microsoft" url="http://www.microsoft.com" port="0" />
<urls>
<clear />
<add
name="Microsoft" url="http://www.microsoft.com" port="0"
lockAllAttributesExcept="port" />
<add
name="Contoso" url="http://www.contoso.com/" port="8080"
lockAllAttributesExcept="port" lockItem="true" />
</urls>
</MyUrls>
</configuration>
The following code example shows how to implement a custom ConfigurationElementCollection that contains the previously defined element.
Imports System Imports System.Configuration Imports System.Collections ' Define the UrlsCollection that contains ' UrlsConfigElement elements. Public Class UrlsCollection Inherits ConfigurationElementCollection Public Sub New() Dim url As UrlConfigElement = _ CType(CreateNewElement(), UrlConfigElement) ' Add the element to the collection. Add(url) End Sub 'New Public Overrides ReadOnly Property CollectionType() _ As ConfigurationElementCollectionType Get Return ConfigurationElementCollectionType.AddRemoveClearMap End Get End Property Protected Overloads Overrides Function CreateNewElement() _ As ConfigurationElement Return New UrlConfigElement() End Function 'CreateNewElement Protected Overloads Overrides Function CreateNewElement( _ ByVal elementName As String) _ As ConfigurationElement Return New UrlConfigElement(elementName) End Function 'CreateNewElement Protected Overrides Function GetElementKey( _ ByVal element As ConfigurationElement) As [Object] Return CType(element, UrlConfigElement).Name End Function 'GetElementKey Public Shadows Property AddElementName() As String Get Return MyBase.AddElementName End Get Set MyBase.AddElementName = value End Set End Property Public Shadows Property ClearElementName() As String Get Return MyBase.ClearElementName End Get Set MyBase.AddElementName = value End Set End Property Public Shadows ReadOnly Property RemoveElementName() As String Get Return MyBase.RemoveElementName End Get End Property Public Shadows ReadOnly Property Count() As Integer Get Return MyBase.Count End Get End Property Default Public Shadows Property Item( _ ByVal index As Integer) As UrlConfigElement Get Return CType(BaseGet(index), UrlConfigElement) End Get Set(ByVal value As UrlConfigElement) If Not (BaseGet(index) Is Nothing) Then BaseRemoveAt(index) End If BaseAdd(index, value) End Set End Property Default Public Shadows ReadOnly Property Item( _ ByVal Name As String) As UrlConfigElement Get Return CType(BaseGet(Name), UrlConfigElement) End Get End Property Public Function IndexOf( _ ByVal url As UrlConfigElement) As Integer Return BaseIndexOf(url) End Function 'IndexOf Public Sub Add(ByVal url As UrlConfigElement) BaseAdd(url) ' Add custom code here. End Sub 'Add Protected Overrides Sub BaseAdd( _ ByVal element As ConfigurationElement) BaseAdd(element, False) ' Add custom code here. End Sub 'BaseAdd Public Overloads Sub Remove( _ ByVal url As UrlConfigElement) If BaseIndexOf(url) >= 0 Then BaseRemove(url.Name) End If End Sub 'Remove Public Sub RemoveAt(ByVal index As Integer) BaseRemoveAt(index) End Sub 'RemoveAt Overloads Public Sub Remove(ByVal name As String) BaseRemove(name) End Sub 'Remove Public Sub Clear() BaseClear() End Sub 'Clear ' Add custom code here. End Class 'UrlsCollection
The following code example shows how to implement a custom ConfigurationSection section that uses the previously defined element.
Imports System Imports System.Configuration Imports System.Collections ' Define a custom section containing ' a simple element and a collection of ' the same element. It uses two custom ' types: UrlsCollection and ' UrlsConfigElement. Public Class UrlsSection Inherits ConfigurationSection ' Test flag. Private Shared _displayIt As Boolean = False ' Declare the custom element type. ' This element will also be part of ' the custom collection. Private url As UrlConfigElement Public Sub New() ' Create the element. url = New UrlConfigElement() End Sub 'New <ConfigurationProperty("name", _ DefaultValue:="MyFavorites", _ IsRequired:=True, _ IsKey:=False), _ StringValidator( _ InvalidCharacters:=" ~!@#$%^&*()[]{/;'""|\", _ MinLength:=1, MaxLength:=60)> _ Public Property Name() As String Get Return CStr(Me("name")) End Get Set(ByVal value As String) Me("name") = value End Set End Property ' Declare a simple element of the type ' UrlConfigElement. In the configuration ' file it corresponds to <simple .... />. <ConfigurationProperty("simple")> _ Public ReadOnly Property Simple() _ As UrlConfigElement Get Dim url As UrlConfigElement = _ CType(Me("simple"), _ UrlConfigElement) Return url End Get End Property ' Declare a collection element represented ' in the configuration file by the sub-section ' <urls> <add .../> </urls> ' Note: the "IsDefaultCollection = false" ' instructs the .NET Framework to build a nested ' section like <urls> ...</urls>. <ConfigurationProperty("urls", _ IsDefaultCollection:=False)> _ Public ReadOnly Property Urls() _ As UrlsCollection Get Dim urlsCollection _ As UrlsCollection = _ CType(Me("urls"), UrlsCollection) Return urlsCollection End Get End Property Protected Overrides Sub DeserializeSection( _ ByVal reader As System.Xml.XmlReader) MyBase.DeserializeSection(reader) ' Enter your custom processing code here. If _displayIt Then Console.WriteLine( _ "UrlsSection.DeserializeSection({0) called", _ IIf(reader Is Nothing, "null", _ reader.ToString())) End If End Sub 'DeserializeSection Protected Overrides Function SerializeSection( _ ByVal parentElement As ConfigurationElement, _ ByVal name As String, _ ByVal saveMode As ConfigurationSaveMode) As String Dim s As String = _ MyBase.SerializeSection(parentElement, _ name, saveMode) ' Enter your custom processing code here. If _displayIt Then Console.WriteLine( _ "UrlsSection.SerializeSection({0, {1, {2) called = {3", _ parentElement.ToString(), _ name, saveMode.ToString(), s) End If Return s End Function 'SerializeSection End Class 'UrlsSection
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