ConfigurationElement Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents a configuration element within a configuration file.
public ref class ConfigurationElement abstractpublic abstract class ConfigurationElementtype ConfigurationElement = classPublic MustInherit Class ConfigurationElement- Inheritance
-
ConfigurationElement
- Derived
Examples
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 namedsimpleand the collection is namedurls.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
UrlsSectionthat derives from the ConfigurationSection class. This class is used to access theMyUrlssection in the configuration file.A class named
UrlsCollectionthat derives from the ConfigurationElementCollection class. This class is used to access theurlscollection in the configuration file.A class named
UrlConfigElementthat derives from the ConfigurationElement class. This class is used to access thesimpleelement and the members of theurlscollection 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.
// 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();
}
}
}
' Set Assembly name to ConfigurationElement
' and set Root namespace to Samples.AspNet
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
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;
}
}
}
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
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
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.
}
}
}
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
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
Protected Overrides Sub BaseAdd( _
ByVal element As ConfigurationElement)
BaseAdd(element, False)
' Add custom code here.
End Sub
Public Overloads Sub Remove( _
ByVal url As UrlConfigElement)
If BaseIndexOf(url) >= 0 Then
BaseRemove(url.Name)
End If
End Sub
Public Sub RemoveAt(ByVal index As Integer)
BaseRemoveAt(index)
End Sub
Public Overloads Sub Remove(ByVal name As String)
BaseRemove(name)
End Sub
Public Sub Clear()
BaseClear()
End Sub
End Class
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;
}
}
}
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
' Default constructor, will use default values as defined
Public Sub New()
End Sub
' 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
<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
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
Remarks
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 Implementers
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.
Constructors
| ConfigurationElement() |
Initializes a new instance of the ConfigurationElement class. |
Properties
| CurrentConfiguration |
Gets a reference to the top-level Configuration instance that represents the configuration hierarchy that the current ConfigurationElement instance belongs to. |
| ElementInformation |
Gets an ElementInformation object that contains the non-customizable information and functionality of the ConfigurationElement object. |
| ElementProperty |
Gets the ConfigurationElementProperty object that represents the ConfigurationElement object itself. |
| EvaluationContext |
Gets the ContextInformation object for the ConfigurationElement object. |
| HasContext |
Gets a value that indicates whether the CurrentConfiguration property is |
| Item[ConfigurationProperty] |
Gets or sets a property or attribute of this configuration element. |
| Item[String] |
Gets or sets a property, attribute, or child element of this configuration element. |
| LockAllAttributesExcept |
Gets the collection of locked attributes. |
| LockAllElementsExcept |
Gets the collection of locked elements. |
| LockAttributes |
Gets the collection of locked attributes. |
| LockElements |
Gets the collection of locked elements. |
| LockItem |
Gets or sets a value indicating whether the element is locked. |
| Properties |
Gets the collection of properties. |
Methods
| DeserializeElement(XmlReader, Boolean) |
Reads XML from the configuration file. |
| Equals(Object) |
Compares the current ConfigurationElement instance to the specified object. |
| GetHashCode() |
Gets a unique value representing the current ConfigurationElement instance. |
| GetTransformedAssemblyString(String) |
Returns the transformed version of the specified assembly name. |
| GetTransformedTypeString(String) |
Returns the transformed version of the specified type name. |
| GetType() |
Gets the Type of the current instance. (Inherited from Object) |
| Init() |
Sets the ConfigurationElement object to its initial state. |
| InitializeDefault() |
Used to initialize a default set of values for the ConfigurationElement object. |
| IsModified() |
Indicates whether this configuration element has been modified since it was last saved or loaded, when implemented in a derived class. |
| IsReadOnly() |
Gets a value indicating whether the ConfigurationElement object is read-only. |
| ListErrors(IList) |
Adds the invalid-property errors in this ConfigurationElement object, and in all subelements, to the passed list. |
| MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
| OnDeserializeUnrecognizedAttribute(String, String) |
Gets a value indicating whether an unknown attribute is encountered during deserialization. |
| OnDeserializeUnrecognizedElement(String, XmlReader) |
Gets a value indicating whether an unknown element is encountered during deserialization. |
| OnRequiredPropertyNotFound(String) |
Throws an exception when a required property is not found. |
| PostDeserialize() |
Called after deserialization. |
| PreSerialize(XmlWriter) |
Called before serialization. |
| Reset(ConfigurationElement) |
Resets the internal state of the ConfigurationElement object, including the locks and the properties collections. |
| ResetModified() |
Resets the value of the IsModified() method to |
| SerializeElement(XmlWriter, Boolean) |
Writes the contents of this configuration element to the configuration file when implemented in a derived class. |
| SerializeToXmlElement(XmlWriter, String) |
Writes the outer tags of this configuration element to the configuration file when implemented in a derived class. |
| SetPropertyValue(ConfigurationProperty, Object, Boolean) |
Sets a property to the specified value. |
| SetReadOnly() |
Sets the IsReadOnly() property for the ConfigurationElement object and all subelements. |
| ToString() |
Returns a string that represents the current object. (Inherited from Object) |
| Unmerge(ConfigurationElement, ConfigurationElement, ConfigurationSaveMode) |
Modifies the ConfigurationElement object to remove all values that should not be saved. |
