Export (0) Print
Expand All

ConfigurationElementCollection Class

Updated: September 2008

Represents a configuration element containing a collection of child elements.

Namespace:  System.Configuration
Assembly:  System.Configuration (in System.Configuration.dll)

public abstract class ConfigurationElementCollection : ConfigurationElement, 
	ICollection, IEnumerable

The ConfigurationElementCollection represents a collection of elements within a configuration file.

NoteNote:

An element within a configuration file refers to a basic XML element or a section. A simple element is an XML tag with related attributes, if any. A simple element constitutes a section. Complex sections can contain one or more simple elements, a collection of elements, and other sections.

You use the ConfigurationElementCollection to work with a collection of ConfigurationElement objects. Implement this class to add collections of custom ConfigurationElement elements to a ConfigurationSection.

Notes to Implementers:

You can use 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 and set its value, and that you add it to the internal property bag of the underlying ConfigurationElement base class.

The declarative model, also referred to as the attributed model, allows you to define an element attribute by using a property and configuring it with attributes. These attributes instruct the ASP.NET configuration system about the property types and their default values. ASP.NET can use reflection to obtain this information and then create the element property objects and perform the required initialization.

The following example shows how to implement a custom ConfigurationElementCollection class. The example consists of the following files:

  • The custom ConfigurationElementCollection class.

  • A custom ConfigurationSection class for a section that contains the custom collection.

  • A custom ConfigurationElement class that defines the elements that are contained in the collection.

  • A Main method for running the example as a console application.

  • An app.config file.

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
{
    // 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 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;
        }
    }
}
// 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();
        }
    }
}
<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>

System.Object
  System.Configuration.ConfigurationElement
    System.Configuration.ConfigurationElementCollection
      System.Configuration.ConnectionStringSettingsCollection
      System.Configuration.KeyValueConfigurationCollection
      System.Configuration.NameValueConfigurationCollection
      System.Configuration.ProviderSettingsCollection
      System.Configuration.SettingElementCollection
      System.Net.Configuration.AuthenticationModuleElementCollection
      System.Net.Configuration.BypassElementCollection
      System.Net.Configuration.ConnectionManagementElementCollection
      System.Net.Configuration.WebRequestModuleElementCollection
      System.Runtime.Serialization.Configuration.DeclaredTypeElementCollection
      System.Runtime.Serialization.Configuration.ParameterElementCollection
      System.Runtime.Serialization.Configuration.TypeElementCollection
      System.ServiceModel.Configuration.ServiceModelConfigurationElementCollection<ConfigurationElementType>
      System.Web.Configuration.AssemblyCollection
      System.Web.Configuration.AuthorizationRuleCollection
      System.Web.Configuration.BufferModesCollection
      System.Web.Configuration.BuildProviderCollection
      System.Web.Configuration.ClientTargetCollection
      System.Web.Configuration.CodeSubDirectoriesCollection
      System.Web.Configuration.CompilerCollection
      System.Web.Configuration.ConvertersCollection
      System.Web.Configuration.CustomErrorCollection
      System.Web.Configuration.EventMappingSettingsCollection
      System.Web.Configuration.ExpressionBuilderCollection
      System.Web.Configuration.FormsAuthenticationUserCollection
      System.Web.Configuration.HttpHandlerActionCollection
      System.Web.Configuration.HttpModuleActionCollection
      System.Web.Configuration.NamespaceCollection
      System.Web.Configuration.OutputCacheProfileCollection
      System.Web.Configuration.ProfileGroupSettingsCollection
      System.Web.Configuration.ProfilePropertySettingsCollection
      System.Web.Configuration.ProfileSettingsCollection
      System.Web.Configuration.RuleSettingsCollection
      System.Web.Configuration.SqlCacheDependencyDatabaseCollection
      System.Web.Configuration.TagMapCollection
      System.Web.Configuration.TagPrefixCollection
      System.Web.Configuration.TransformerInfoCollection
      System.Web.Configuration.TrustLevelCollection
      System.Web.Configuration.UrlMappingCollection
      System.Web.Mobile.DeviceFilterElementCollection
      System.Web.Services.Configuration.ProtocolElementCollection
      System.Web.Services.Configuration.SoapExtensionTypeElementCollection
      System.Web.Services.Configuration.TypeElementCollection
      System.Web.Services.Configuration.WsiProfilesElementCollection
      System.Web.UI.MobileControls.ControlElementCollection
      System.Web.UI.MobileControls.DeviceElementCollection
      System.Workflow.Runtime.Configuration.WorkflowRuntimeServiceElementCollection
      System.Xml.Serialization.Configuration.SchemaImporterExtensionElementCollection

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

September 2008

Expanded scope of code example.

Customer feedback.

Community Additions

ADD
Show:
© 2014 Microsoft