ConfigurationElement Classe
Définition
Important
Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.
Représente un élément de configuration dans un fichier de configuration.
public ref class ConfigurationElement abstract
public abstract class ConfigurationElement
type ConfigurationElement = class
Public MustInherit Class ConfigurationElement
- Héritage
-
ConfigurationElement
- Dérivé
Exemples
L’exemple de code suivant montre comment implémenter un personnalisé ConfigurationElement en tant qu’élément individuel dans une section personnalisée et en tant que collection d’éléments dans une section personnalisée. L’exemple se compose des fichiers suivants :
Un fichier app.config qui contient une section personnalisée nommée
MyUrls
. Cette section contient un élément simple (elle ne contient aucun autre élément) et une collection d’éléments. L’élément simple est nommésimple
et la collection est nomméeurls
.Une application console. L’application lit le contenu du fichier app.config et écrit les informations dans la console. Il utilise des classes qui dérivent de ConfigurationElement, ConfigurationElementCollectionet ConfigurationSection.
Classe nommée
UrlsSection
qui dérive de la ConfigurationSection classe . Cette classe est utilisée pour accéder à laMyUrls
section dans le fichier de configuration.Classe nommée
UrlsCollection
qui dérive de la ConfigurationElementCollection classe . Cette classe est utilisée pour accéder à laurls
collection dans le fichier de configuration.Classe nommée
UrlConfigElement
qui dérive de la ConfigurationElement classe . Cette classe est utilisée pour accéder à l’élémentsimple
et aux membres de laurls
collection dans le fichier de configuration.
Pour exécuter l’exemple, procédez comme suit :
Créez une solution qui a un projet d’application console et un projet de bibliothèque de classes nommé
ConfigurationElement
.Placez les trois fichiers de classe dans le projet de bibliothèque de classes et placez les autres fichiers dans le projet de bibliothèque de console.
Dans les deux projets, définissez une référence à
System.Configuration
.Dans le projet d’application console, définissez une référence de projet au projet de bibliothèque de classes.
// 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
Remarques
est ConfigurationElement une classe abstraite utilisée pour représenter un élément XML dans un fichier de configuration (par exemple, Web.config). Un élément dans un fichier de configuration peut contenir zéro, un ou plusieurs éléments enfants.
Étant donné que la ConfigurationElement classe est définie comme abstraite, vous ne pouvez pas en créer une instance. Vous ne pouvez en dériver que des classes. Le .NET Framework inclut des classes qui dérivent de la ConfigurationElement classe afin de représenter des éléments de configuration XML standard, tels que ConfigurationSection. Vous pouvez également étendre la ConfigurationElement classe pour accéder aux sections et éléments de configuration personnalisés. L’exemple inclus plus loin dans cette rubrique montre comment accéder aux éléments et sections de configuration personnalisés à l’aide de classes personnalisées qui dérivent de ConfigurationElement.
Vous pouvez également étendre les types de configuration standard tels que ConfigurationElement, ConfigurationElementCollection, ConfigurationPropertyet ConfigurationSection. Pour plus d’informations, consultez la documentation relative à ces classes.
Pour plus d’informations sur l’accès aux informations dans les fichiers de configuration, consultez la ConfigurationManager classe et la WebConfigurationManager classe .
Notes pour les responsables de l’implémentation
Chaque ConfigurationElement objet crée une collection interne ConfigurationPropertyCollection d’objets ConfigurationProperty qui représente les attributs d’élément ou une collection d’éléments enfants.
Les informations et fonctionnalités non personnalisables sont contenues dans un ElementInformation objet fourni par la ElementInformation propriété .
Vous pouvez utiliser un modèle de codage programmatique ou déclaratif (attribut) pour créer un élément de configuration personnalisé :
Le modèle programmatique nécessite que pour chaque attribut d’élément, vous créez une propriété pour obtenir ou définir sa valeur et l’ajouter au sac de propriétés interne de la classe de base sous-jacente ConfigurationElement . Pour obtenir un exemple d’utilisation de ce modèle, consultez la ConfigurationSection classe .
Le modèle déclaratif plus simple, également appelé modèle attribué, vous permet de définir un attribut d’élément à l’aide d’une propriété, puis de le décorer avec des attributs. Ces attributs indiquent au système de configuration ASP.NET les types de propriétés et leurs valeurs par défaut. Avec ces informations, obtenues par réflexion, le système de configuration ASP.NET crée les objets de propriété d’élément pour vous et effectue l’initialisation requise. L’exemple présenté plus loin dans cette rubrique montre comment utiliser ce modèle.
Constructeurs
ConfigurationElement() |
Initialise une nouvelle instance de la classe ConfigurationElement. |
Propriétés
CurrentConfiguration |
Obtient une référence à l'instance Configuration de niveau supérieur qui représente la hiérarchie de configuration à laquelle l'instance ConfigurationElement actuelle appartient. |
ElementInformation |
Obtient un objet ElementInformation qui contient les fonctionnalités et informations non personnalisables de l'objet ConfigurationElement. |
ElementProperty |
Obtient l'objet ConfigurationElementProperty qui représente l'objet ConfigurationElement lui-même. |
EvaluationContext |
Obtient l'objet ContextInformation pour l'objet ConfigurationElement. |
HasContext |
Obtient une valeur qui indique si la propriété CurrentConfiguration a la valeur |
Item[ConfigurationProperty] |
Obtient ou définit une propriété ou un attribut de cet élément de configuration. |
Item[String] |
Obtient ou définit une propriété, un attribut ou un élément enfant de cet élément de configuration. |
LockAllAttributesExcept |
Obtient la collection d'attributs verrouillés. |
LockAllElementsExcept |
Obtient la collection d'éléments verrouillés. |
LockAttributes |
Obtient la collection d'attributs verrouillés. |
LockElements |
Obtient la collection d'éléments verrouillés. |
LockItem |
Obtient ou définit une valeur indiquant si l'élément est verrouillé. |
Properties |
Obtient la collection de propriétés. |
Méthodes
DeserializeElement(XmlReader, Boolean) |
Lit du XML à partir du fichier de configuration. |
Equals(Object) |
Compare l’instance de ConfigurationElement actuelle à l’objet spécifié. |
GetHashCode() |
Obtient une valeur unique représentant l'instance actuelle de ConfigurationElement. |
GetTransformedAssemblyString(String) |
Retourne la version transformée du nom de l'assembly spécifié. |
GetTransformedTypeString(String) |
Retourne la version transformée du nom de type spécifié. |
GetType() |
Obtient le Type de l'instance actuelle. (Hérité de Object) |
Init() |
Rétablit l’état initial de l’objet ConfigurationElement. |
InitializeDefault() |
Utilisé pour initialiser un jeu de valeurs par défaut pour l'objet ConfigurationElement. |
IsModified() |
Indique si cet élément de configuration a été modifié depuis son dernier enregistrement ou chargement lorsqu'il est implémenté dans une classe dérivée. |
IsReadOnly() |
Obtient une valeur indiquant si l’objet ConfigurationElement est en lecture seule. |
ListErrors(IList) |
Ajoute les erreurs de propriété non valide dans cet objet ConfigurationElement et dans tous les sous-éléments à la liste passée. |
MemberwiseClone() |
Crée une copie superficielle du Object actuel. (Hérité de Object) |
OnDeserializeUnrecognizedAttribute(String, String) |
Obtient une valeur indiquant si un attribut inconnu est rencontré pendant la désérialisation. |
OnDeserializeUnrecognizedElement(String, XmlReader) |
Obtient une valeur indiquant si un élément inconnu est rencontré pendant la désérialisation. |
OnRequiredPropertyNotFound(String) |
Lève une exception lorsqu'une propriété requise est introuvable. |
PostDeserialize() |
Appelé après la désérialisation. |
PreSerialize(XmlWriter) |
Appelé avant la sérialisation. |
Reset(ConfigurationElement) |
Rétablit l'état interne de l'objet ConfigurationElement, y compris les verrouillages et les collections de propriétés. |
ResetModified() |
Réinitialise la valeur de la méthode IsModified() à |
SerializeElement(XmlWriter, Boolean) |
Écrit le contenu de cet élément de configuration dans le fichier de configuration lorsqu'il est implémenté dans une classe dérivée. |
SerializeToXmlElement(XmlWriter, String) |
Écrit les balises extérieures de cet élément de configuration dans le fichier de configuration lorsqu'il est implémenté dans une classe dérivée. |
SetPropertyValue(ConfigurationProperty, Object, Boolean) |
Affecte la valeur spécifiée à une propriété. |
SetReadOnly() |
Définit la propriété IsReadOnly() pour l'objet ConfigurationElement et tous les sous-éléments. |
ToString() |
Retourne une chaîne qui représente l'objet actuel. (Hérité de Object) |
Unmerge(ConfigurationElement, ConfigurationElement, ConfigurationSaveMode) |
Modifie l'objet ConfigurationElement pour supprimer toutes les valeurs qui ne doivent pas être enregistrées. |