Note: This class is new in the .NET Framework version 2.0.
Represents a configuration element containing a collection of child elements.
Namespace: System.Configuration
Assembly: System.Configuration (in system.configuration.dll)
Visual Basic (Declaration)
Public MustInherit Class ConfigurationElementCollection
Inherits ConfigurationElement
Implements ICollection, IEnumerable
Dim instance As ConfigurationElementCollection
public abstract class ConfigurationElementCollection : ConfigurationElement, ICollection, IEnumerable
public ref class ConfigurationElementCollection abstract : public ConfigurationElement, ICollection, IEnumerable
public abstract class ConfigurationElementCollection extends ConfigurationElement implements ICollection, IEnumerable
public abstract class ConfigurationElementCollection extends ConfigurationElement implements ICollection, IEnumerable
The ConfigurationElementCollection represents a collection of elements within a configuration file.
.gif) Note |
|---|
| 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 code example shows how to implement a custom ConfigurationElementCollection. For examples of related custom types, see ConfigurationSection and ConfigurationElement.
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
using System;
using System.Configuration;
using System.Collections;
namespace Samples.AspNet
{
// Define the UrlsCollection that contains
// UrlsConfigElement elements.
public class UrlsCollection :
ConfigurationElementCollection
{
public UrlsCollection()
{
UrlConfigElement url =
(UrlConfigElement)CreateNewElement();
// Add the element to the collection.
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.AddElementName = 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.
The following configuration excerpt is used by the previous example.
<?xml version="1.0" encoding="utf-8"?>
<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 lockAllElementsExcept="urls">
<internal
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>
System.Object
System.Configuration.ConfigurationElement
System.Configuration.ConfigurationElementCollection
Derived Classes
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 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.
.NET Framework
Supported in: 2.0