Export (0) Print
Expand All
6 out of 46 rated this helpful - Rate this topic

ConfigurationElement Class

Updated: May 2011

Represents a configuration element within a configuration file.

Namespace:  System.Configuration
Assembly:  System.Configuration (in System.Configuration.dll)
public abstract class ConfigurationElement

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:

  1. Create a solution that has a console application project and a class library project that is named ConfigurationElement.

  2. Put the three class files in the class library project and put the other files in the console library project.

  3. In both projects, set a reference to System.Configuration.

  4. 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 
using System;
using System.Configuration;
using System.Collections;

namespace Samples.AspNet
{
    // Entry point for console application that reads the  
    // app.config file and writes to the console the  
    // URLs in the custom section. 
    class TestConfigurationElement
    {
        static void Main(string[] args)
        {
            // Get current configuration file.
            System.Configuration.Configuration config =
                ConfigurationManager.OpenExeConfiguration(
                ConfigurationUserLevel.None);

            // Get the MyUrls section.
            UrlsSection myUrlsSection =
                config.GetSection("MyUrls") as UrlsSection;

            if (myUrlsSection == null)
                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:");
                for (int i = 0; i < myUrlsSection.Urls.Count; i++)
                {
                    Console.WriteLine("  Name={0} URL={1} Port={2}",
                        myUrlsSection.Urls[i].Name,
                        myUrlsSection.Urls[i].Url,
                        myUrlsSection.Urls[i].Port);
                }
            }
            Console.ReadLine();
        }
    }
}
using System;
using System.Configuration;
using System.Collections;


namespace Samples.AspNet
{
    // Define a custom section containing an individual 
    // element and a collection of elements. 
    public class UrlsSection : ConfigurationSection
    {
        [ConfigurationProperty("name", 
            DefaultValue = "MyFavorites",
            IsRequired = true, 
            IsKey = false)]
        [StringValidator(InvalidCharacters = 
            " ~!@#$%^&*()[]{}/;'\"|\\",
            MinLength = 1, MaxLength = 60)]
        public string Name
        {

            get
            {
                return (string)this["name"];
            }
            set
            {
                this["name"] = value;
            }

        }

        // Declare an element (not in a collection) of the type 
        // UrlConfigElement. In the configuration 
        // file it corresponds to <simple .... />.
        [ConfigurationProperty("simple")]
        public UrlConfigElement Simple
        {
            get
            {
                UrlConfigElement url =
                (UrlConfigElement)base["simple"];
                return url;
            }
        }

        // 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 UrlsCollection Urls
        {
            get
            {
                UrlsCollection urlsCollection =
                (UrlsCollection)base["urls"];
                return urlsCollection;
            }
        }


        protected override void DeserializeSection(
            System.Xml.XmlReader reader)
        {
            base.DeserializeSection(reader);
            // You can add custom processing code here.
        }

        protected override string SerializeSection(
            ConfigurationElement parentElement,
            string name, ConfigurationSaveMode saveMode)
        {
            string s =
                base.SerializeSection(parentElement,
                name, saveMode);
            // You can add custom processing code here. 
            return s;
        }

    }
}
using System;
using System.Configuration;
using System.Collections;

namespace Samples.AspNet
{
    public class UrlsCollection : ConfigurationElementCollection
    {
        public UrlsCollection()
        {
            // Add one url to the collection.  This is 
            // not necessary; could leave the collection  
            // empty until items are added to it outside 
            // the constructor.
            UrlConfigElement url = 
                (UrlConfigElement)CreateNewElement();
            Add(url);
        }

        public override 
            ConfigurationElementCollectionType CollectionType
        {
            get
            {
                return 

                    ConfigurationElementCollectionType.AddRemoveClearMap;
            }
        }

        protected override 
            ConfigurationElement CreateNewElement()
        {
            return new UrlConfigElement();
        }


        protected override 
            ConfigurationElement CreateNewElement(
            string elementName)
        {
            return new UrlConfigElement(elementName);
        }


        protected override Object 
            GetElementKey(ConfigurationElement element)
        {
            return ((UrlConfigElement)element).Name;
        }


        public new string AddElementName
        {
            get
            { return base.AddElementName; }

            set
            { base.AddElementName = value; }

        }

        public new string ClearElementName
        {
            get
            { return base.ClearElementName; }

            set
            { base.ClearElementName = value; }

        }

        public new string RemoveElementName
        {
            get
            { return base.RemoveElementName; }
        }

        public new int Count
        {
            get { return base.Count; }
        }


        public UrlConfigElement this[int index]
        {
            get
            {
                return (UrlConfigElement)BaseGet(index);
            }
            set
            {
                if (BaseGet(index) != null)
                {
                    BaseRemoveAt(index);
                }
                BaseAdd(index, value);
            }
        }

        new public UrlConfigElement this[string Name]
        {
            get
            {
                return (UrlConfigElement)BaseGet(Name);
            }
        }

        public int IndexOf(UrlConfigElement url)
        {
            return BaseIndexOf(url);
        }

        public void Add(UrlConfigElement url)
        {
            BaseAdd(url);
            // Add custom code here.
        }

        protected override void 
            BaseAdd(ConfigurationElement element)
        {
            BaseAdd(element, false);
            // Add custom code here.
        }

        public void Remove(UrlConfigElement url)
        {
            if (BaseIndexOf(url) >= 0)
                BaseRemove(url.Name);
        }

        public void RemoveAt(int index)
        {
            BaseRemoveAt(index);
        }

        public void Remove(string name)
        {
            BaseRemove(name);
        }

        public void Clear()
        {
            BaseClear();
            // Add custom code here.
        }
    }
}
using System;
using System.Configuration;
using System.Collections;

namespace Samples.AspNet
{
    public class UrlConfigElement : ConfigurationElement
    {
        // Constructor allowing name, url, and port to be specified. 
        public UrlConfigElement(String newName,
            String newUrl, int newPort)
        {
            Name = newName;
            Url = newUrl;
            Port = newPort;
        }

        // Default constructor, will use default values as defined 
        // below. 
        public UrlConfigElement()
        {
        }

        // Constructor allowing name to be specified, will take the 
        // default values for url and port. 
        public UrlConfigElement(string elementName)
        {
            Name = elementName;
        }

        [ConfigurationProperty("name", 
            DefaultValue = "Microsoft",
            IsRequired = true, 
            IsKey = true)]
        public string Name
        {
            get
            {
                return (string)this["name"];
            }
            set
            {
                this["name"] = value;
            }
        }

        [ConfigurationProperty("url",
            DefaultValue = "http://www.microsoft.com",
            IsRequired = true)]
        [RegexStringValidator(@"\w+:\/\/[\w.]+\S*")]
        public string Url
        {
            get
            {
                return (string)this["url"];
            }
            set
            {
                this["url"] = value;
            }
        }

        [ConfigurationProperty("port",
            DefaultValue = (int)0,
            IsRequired = false)]
        [IntegerValidator(MinValue = 0,
            MaxValue = 8080, ExcludeRange = false)]
        public int Port
        {
            get
            {
                return (int)this["port"];
            }
            set
            {
                this["port"] = value;
            }
        }

        protected override void DeserializeElement(
           System.Xml.XmlReader reader, 
            bool serializeCollectionKey)
        {
            base.DeserializeElement(reader, 
                serializeCollectionKey);
            // You can your custom processing code here.
        }


        protected override bool SerializeElement(
            System.Xml.XmlWriter writer, 
            bool serializeCollectionKey)
        {
            bool ret = base.SerializeElement(writer, 
                serializeCollectionKey);
            // You can enter your custom processing code here. 
            return ret;

        }


        protected override bool IsModified()
        {
            bool ret = base.IsModified();
            // You can enter your custom processing code here. 
            return ret;
        }
    }
}
System.Object
  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<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
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

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.

.NET Framework

Supported in: 3.5, 3.0, 2.0

Date

History

Reason

May 2011

Added instructions for how to run the example.

Customer feedback.

July 2009

Rewrote remarks and example to make them clearer.

Customer feedback.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.