ConfigurationElement Class
Updated: May 2011
Represents a configuration element within a configuration file.
Assembly: System.Configuration (in System.Configuration.dll)
The ConfigurationElement is an abstract class that is used to represent an XML element in a configuration file (such as Web.config). An element in a configuration file can contain zero, one, or more child elements.
Because the ConfigurationElement class is defined as abstract, you cannot create an instance of it. You can only derive classes from it. The .NET Framework includes classes that derive from the ConfigurationElement class in order to represent standard XML configuration elements, such as ConfigurationSection. You can also extend the ConfigurationElement class to access custom configuration elements and sections. The example included later in this topic shows how to access custom configuration elements and sections by using custom classes that derive from ConfigurationElement.
You can also extend the standard configuration types such as ConfigurationElement, ConfigurationElementCollection, ConfigurationProperty, and ConfigurationSection. For more information, see the documentation for those classes.
For more information about how to access information in configuration files, see the ConfigurationManager class and the WebConfigurationManager class.
Notes to Inheritors:Every ConfigurationElement object creates an internal ConfigurationPropertyCollection collection of ConfigurationProperty objects that represents either the element attributes or a collection of child elements.
Non-customizable information and functionality is contained by an ElementInformation object provided by the ElementInformation property.
You can use either a programmatic or a declarative (attributed) coding model to create a custom configuration element:
The programmatic model requires that for each element attribute, you create a property to get or set its value and add it to the internal property bag of the underlying ConfigurationElement base class. For an example of how to use this model, see the ConfigurationSection class.
The simpler declarative 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 example shown later in this topic shows how to use this model.
The following code example shows how to implement a custom ConfigurationElement both as an individual element in a custom section and as a collection of elements in a custom section. The example consists of the following files:
An app.config file that contains a custom section that is named MyUrls. This section contains a simple element (it does not contain any other elements) and a collection of elements. The simple element is named simple and the collection is named urls.
A console application. The application reads the contents of the app.config file and writes the information to the console. It uses classes that derive from ConfigurationElement, ConfigurationElementCollection, and ConfigurationSection.
A class named UrlsSection that derives from the ConfigurationSection class. This class is used to access the MyUrls section in the configuration file.
A class named UrlsCollection that derives from the ConfigurationElementCollection class. This class is used to access the urls collection in the configuration file.
A class named UrlConfigElement that derives from the ConfigurationElement class. This class is used to access the simple element and the members of the urls collection in the configuration file.
To run the example, perform the following steps:
Create a solution that has a console application project and a class library project that is named ConfigurationElement.
Put the three class files in the class library project and put the other files in the console library project.
In both projects, set a reference to System.Configuration.
In the console application project, set a project reference to the class library project.
<configuration>
<configSections>
<section name="MyUrls" type="Samples.AspNet.UrlsSection, ConfigurationElement, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" restartOnExternalChanges="true" />
</configSections>
<MyUrls name="MyFavorites">
<simple name="Microsoft1" url="http://www.microsoft1.com" port="1" />
<urls>
<clear />
<add name="Microsoft2" url="http://www.microsoft2.com" port="2" />
<add name="Contoso" url="http://www.contoso.com" port="8080" />
</urls>
</MyUrls>
</configuration>
' Set Assembly name to ConfigurationElement ' and set Root namespace to Samples.AspNet Imports System Imports System.Configuration Imports System.Collections Class TestConfigurationElement ' Entry point for console application that reads the ' app.config file and writes to the console the ' URLs in the custom section. Shared Sub Main(ByVal args() As String) ' Get the current configuration file. Dim config As System.Configuration.Configuration = _ ConfigurationManager.OpenExeConfiguration( _ ConfigurationUserLevel.None) ' Get the MyUrls section. Dim myUrlsSection As UrlsSection = _ config.GetSection("MyUrls") If myUrlsSection Is Nothing Then Console.WriteLine("Failed to load UrlsSection.") Else Console.WriteLine("The 'simple' element of app.config:") Console.WriteLine(" Name={0} URL={1} Port={2}", _ myUrlsSection.Simple.Name, _ myUrlsSection.Simple.Url, _ myUrlsSection.Simple.Port) Console.WriteLine("The urls collection of app.config:") Dim i As Integer For i = 0 To myUrlsSection.Urls.Count - 1 Console.WriteLine(" Name={0} URL={1} Port={2}", _ i, myUrlsSection.Urls(i).Name, _ myUrlsSection.Urls(i).Url, _ myUrlsSection.Urls(i).Port) Next i End If Console.ReadLine() End Sub End Class
Imports System Imports System.Configuration Imports System.Collections ' Define a custom section containing an individual ' element and a collection of elements. Public Class UrlsSection Inherits ConfigurationSection <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 an element (not in a collection) 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. 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. Return s End Function 'SerializeSection End Class 'UrlsSection
Imports System Imports System.Configuration Imports System.Collections Public Class UrlsCollection Inherits ConfigurationElementCollection Public Sub New() ' Add one url to the collection. This is ' not necessary; could leave the collection ' empty until items are added to it outside ' the constructor. 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(ByVal value As String) MyBase.AddElementName = value End Set End Property Public Shadows Property ClearElementName() As String Get Return MyBase.ClearElementName End Get Set(ByVal value As String) MyBase.ClearElementName = 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 Public Overloads Sub Remove(ByVal name As String) BaseRemove(name) End Sub 'Remove Public Sub Clear() BaseClear() End Sub 'Clear ' End Class 'UrlsCollection
Imports System Imports System.Configuration Imports System.Collections Public Class UrlConfigElement Inherits ConfigurationElement ' Constructor allowing name, url, and port to be specified. Public Sub New(ByVal newName As String, _ ByVal newUrl As String, _ ByVal newPort As Integer) Name = newName Url = newUrl Port = newPort End Sub 'New ' Default constructor, will use default values as defined Public Sub New() End Sub 'New ' Constructor allowing name to be specified, will take the ' default values for url and port. 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. 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. Return ret End Function 'SerializeElement Protected Overrides Function IsModified() As Boolean Dim ret As Boolean = MyBase.IsModified() ' Enter your custom processing code here. Return ret End Function 'IsModified End Class 'UrlConfigElement
System.Configuration.ConfigurationElement
System.Configuration.ConfigurationElementCollection
System.Configuration.ConfigurationSection
System.Configuration.ConnectionStringSettings
System.Configuration.KeyValueConfigurationElement
System.Configuration.NameValueConfigurationElement
System.Configuration.ProtectedProviderSettings
System.Configuration.ProviderSettings
System.Configuration.SettingElement
System.Configuration.SettingValueElement
System.Net.Configuration.AuthenticationModuleElement
System.Net.Configuration.BypassElement
System.Net.Configuration.ConnectionManagementElement
System.Net.Configuration.FtpCachePolicyElement
System.Net.Configuration.HttpCachePolicyElement
System.Net.Configuration.HttpWebRequestElement
System.Net.Configuration.Ipv6Element
System.Net.Configuration.ModuleElement
System.Net.Configuration.PerformanceCountersElement
System.Net.Configuration.ProxyElement
System.Net.Configuration.ServicePointManagerElement
System.Net.Configuration.SmtpNetworkElement
System.Net.Configuration.SmtpSpecifiedPickupDirectoryElement
System.Net.Configuration.SocketElement
System.Net.Configuration.WebProxyScriptElement
System.Net.Configuration.WebRequestModuleElement
System.Runtime.Serialization.Configuration.DeclaredTypeElement
System.Runtime.Serialization.Configuration.ParameterElement
System.Runtime.Serialization.Configuration.TypeElement
System.ServiceModel.Activation.Configuration.SecurityIdentifierElement
System.ServiceModel.Configuration.AddressHeaderCollectionElement
System.ServiceModel.Configuration.AuthorizationPolicyTypeElement
System.ServiceModel.Configuration.BaseAddressElement
System.ServiceModel.Configuration.BasicHttpMessageSecurityElement
System.ServiceModel.Configuration.BasicHttpSecurityElement
System.ServiceModel.Configuration.BindingCollectionElement
System.ServiceModel.Configuration.CertificateElement
System.ServiceModel.Configuration.CertificateReferenceElement
System.ServiceModel.Configuration.ChannelEndpointElement
System.ServiceModel.Configuration.ChannelPoolSettingsElement
System.ServiceModel.Configuration.ClaimTypeElement
System.ServiceModel.Configuration.ComContractElement
System.ServiceModel.Configuration.ComMethodElement
System.ServiceModel.Configuration.ComPersistableTypeElement
System.ServiceModel.Configuration.ComUdtElement
System.ServiceModel.Configuration.DnsElement
System.ServiceModel.Configuration.EndpointAddressElementBase
System.ServiceModel.Configuration.ExtensionElement
System.ServiceModel.Configuration.FederatedMessageSecurityOverHttpElement
System.ServiceModel.Configuration.HostElement
System.ServiceModel.Configuration.HostTimeoutsElement
System.ServiceModel.Configuration.HttpDigestClientElement
System.ServiceModel.Configuration.HttpTransportSecurityElement
System.ServiceModel.Configuration.IdentityElement
System.ServiceModel.Configuration.IssuedTokenClientBehaviorsElement
System.ServiceModel.Configuration.IssuedTokenClientElement
System.ServiceModel.Configuration.IssuedTokenParametersElement
System.ServiceModel.Configuration.IssuedTokenServiceElement
System.ServiceModel.Configuration.LocalClientSecuritySettingsElement
System.ServiceModel.Configuration.LocalServiceSecuritySettingsElement
System.ServiceModel.Configuration.MessageLoggingElement
System.ServiceModel.Configuration.MessageSecurityOverHttpElement
System.ServiceModel.Configuration.MessageSecurityOverMsmqElement
System.ServiceModel.Configuration.MessageSecurityOverTcpElement
System.ServiceModel.Configuration.MetadataElement
System.ServiceModel.Configuration.MsmqIntegrationSecurityElement
System.ServiceModel.Configuration.MsmqTransportSecurityElement
System.ServiceModel.Configuration.NamedPipeConnectionPoolSettingsElement
System.ServiceModel.Configuration.NamedPipeTransportSecurityElement
System.ServiceModel.Configuration.NetMsmqSecurityElement
System.ServiceModel.Configuration.NetNamedPipeSecurityElement
System.ServiceModel.Configuration.NetTcpSecurityElement
System.ServiceModel.Configuration.PeerCredentialElement
System.ServiceModel.Configuration.PeerCustomResolverElement
System.ServiceModel.Configuration.PeerResolverElement
System.ServiceModel.Configuration.PeerSecurityElement
System.ServiceModel.Configuration.PeerTransportSecurityElement
System.ServiceModel.Configuration.PolicyImporterElement
System.ServiceModel.Configuration.RsaElement
System.ServiceModel.Configuration.SecureConversationServiceElement
System.ServiceModel.Configuration.ServiceElement
System.ServiceModel.Configuration.ServiceEndpointElement
System.ServiceModel.Configuration.ServiceModelExtensionCollectionElement(Of TServiceModelExtensionElement)
System.ServiceModel.Configuration.ServiceModelExtensionElement
System.ServiceModel.Configuration.ServicePrincipalNameElement
System.ServiceModel.Configuration.StandardBindingElement
System.ServiceModel.Configuration.StandardBindingReliableSessionElement
System.ServiceModel.Configuration.TcpConnectionPoolSettingsElement
System.ServiceModel.Configuration.TcpTransportSecurityElement
System.ServiceModel.Configuration.TransportConfigurationTypeElement
System.ServiceModel.Configuration.UserNameServiceElement
System.ServiceModel.Configuration.UserPrincipalNameElement
System.ServiceModel.Configuration.WebHttpSecurityElement
System.ServiceModel.Configuration.WindowsClientElement
System.ServiceModel.Configuration.WindowsServiceElement
System.ServiceModel.Configuration.WsdlImporterElement
System.ServiceModel.Configuration.WSDualHttpSecurityElement
System.ServiceModel.Configuration.WSFederationHttpSecurityElement
System.ServiceModel.Configuration.WSHttpSecurityElement
System.ServiceModel.Configuration.WSHttpTransportSecurityElement
System.ServiceModel.Configuration.X509CertificateTrustedIssuerElement
System.ServiceModel.Configuration.X509ClientCertificateAuthenticationElement
System.ServiceModel.Configuration.X509ClientCertificateCredentialsElement
System.ServiceModel.Configuration.X509DefaultServiceCertificateElement
System.ServiceModel.Configuration.X509InitiatorCertificateClientElement
System.ServiceModel.Configuration.X509InitiatorCertificateServiceElement
System.ServiceModel.Configuration.X509PeerCertificateAuthenticationElement
System.ServiceModel.Configuration.X509PeerCertificateElement
System.ServiceModel.Configuration.X509RecipientCertificateClientElement
System.ServiceModel.Configuration.X509RecipientCertificateServiceElement
System.ServiceModel.Configuration.X509ScopedServiceCertificateElement
System.ServiceModel.Configuration.X509ServiceCertificateAuthenticationElement
System.ServiceModel.Configuration.XmlDictionaryReaderQuotasElement
System.ServiceModel.Configuration.XmlElementElement
System.ServiceModel.Configuration.XPathMessageFilterElement
System.Web.Configuration.AssemblyInfo
System.Web.Configuration.AuthorizationRule
System.Web.Configuration.BufferModeSettings
System.Web.Configuration.BuildProvider
System.Web.Configuration.ClientTarget
System.Web.Configuration.CodeSubDirectory
System.Web.Configuration.Compiler
System.Web.Configuration.Converter
System.Web.Configuration.CustomError
System.Web.Configuration.EventMappingSettings
System.Web.Configuration.ExpressionBuilder
System.Web.Configuration.FormsAuthenticationConfiguration
System.Web.Configuration.FormsAuthenticationCredentials
System.Web.Configuration.FormsAuthenticationUser
System.Web.Configuration.HttpHandlerAction
System.Web.Configuration.HttpModuleAction
System.Web.Configuration.NamespaceInfo
System.Web.Configuration.OutputCacheProfile
System.Web.Configuration.PassportAuthentication
System.Web.Configuration.ProfileGroupSettings
System.Web.Configuration.ProfilePropertySettings
System.Web.Configuration.ProfileSettings
System.Web.Configuration.RuleSettings
System.Web.Configuration.SqlCacheDependencyDatabase
System.Web.Configuration.TagMapInfo
System.Web.Configuration.TagPrefixInfo
System.Web.Configuration.TransformerInfo
System.Web.Configuration.TrustLevel
System.Web.Configuration.UrlMapping
System.Web.Configuration.WebPartsPersonalization
System.Web.Configuration.WebPartsPersonalizationAuthorization
System.Web.Mobile.DeviceFilterElement
System.Web.Services.Configuration.DiagnosticsElement
System.Web.Services.Configuration.ProtocolElement
System.Web.Services.Configuration.SoapEnvelopeProcessingElement
System.Web.Services.Configuration.SoapExtensionTypeElement
System.Web.Services.Configuration.TypeElement
System.Web.Services.Configuration.WsdlHelpGeneratorElement
System.Web.Services.Configuration.WsiProfilesElement
System.Web.UI.MobileControls.ControlElement
System.Web.UI.MobileControls.DeviceElement
System.Workflow.Runtime.Configuration.WorkflowRuntimeServiceElement
System.Xml.Serialization.Configuration.SchemaImporterExtensionElement
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.