Cette documentation est archivée et n’est pas conservée.

ConfigurationElement, classe

Représente un élément de configuration dans un fichier de configuration.

Espace de noms: System.Configuration
Assembly : System.Configuration (dans system.configuration.dll)

public abstract class ConfigurationElement
public abstract class ConfigurationElement
public abstract class ConfigurationElement
Non applicable.

ConfigurationElement est une classe abstraite ; vous ne pouvez donc pas créer une instance de celle-ci. Elle représente un élément dans un fichier de configuration.

RemarqueRemarque :

Un élément dans un fichier de configuration fait référence à un élément XML de base ou à une section. Un élément de base est une simple balise XML avec des attributs associés, le cas échéant. Dans sa forme la plus simple, une section équivaut à un élément de base. Les sections complexes peuvent contenir un ou plusieurs éléments de base, une collection d'éléments et d'autres sections.

ConfigurationElement est utilisé comme classe de base pour les classes représentant des éléments de configuration XML, tels que ConfigurationSection.

Vous pouvez étendre la classe ConfigurationElement pour représenter un élément de configuration dans une section ConfigurationSection. Vous pouvez également créer une collection ConfigurationElementCollection d'éléments ConfigurationElement, comme illustré dans la section Exemple.

Gestion de la configuration

Pour gérer les informations de configuration à l'aide des types standard, utilisez l'une des approches suivantes :

  • Accès à une section. Pour accéder aux informations de configuration de votre application, vous devez utiliser l'une des méthodes GetSection fournies par ConfigurationManager et WebConfigurationManager. Pour les sections spéciales telles que appSettings et connectionStrings, vous utilisez la propriété AppSettings de la classe ConfigurationManager ou la propriété AppSettings de la classe WebConfigurationManager, et la propriété ConnectionStrings de la classe ConfigurationManager ou la propriété ConnectionStrings de la classe WebConfigurationManager. Ces méthodes exécutent des opérations en lecture seule, utilisent une instance unique mise en cache de la configuration et sont sensibles au multithread.

  • Accès aux fichiers de configuration. Votre application peut lire et écrire des paramètres de configuration à tout niveau, pour elle-même ou pour d'autres applications ou ordinateurs globalement, localement ou à distance. Vous utilisez l'une des méthodes Open fournies par la classe ConfigurationManager et la classe WebConfigurationManager. Ces méthodes retournent un objet Configuration qui fournit à son tour les méthodes et les propriétés requises pour gérer les fichiers de configuration sous-jacents. Ces méthodes exécutent des opérations de lecture ou d'écriture et recréent les données de configuration chaque fois qu'un fichier est ouvert.

  • Configuration avancée. La gestion d'une configuration plus avancée est fournie par les types SectionInformation, PropertyInformation, PropertyInformationCollection, ElementInformation, ContextInformation, ConfigurationSectionGroup, ConfigurationSectionGroupCollection et WebConfigurationSectionGroup.

Extension des types standard de configuration

Vous pouvez également étendre les types de configuration standard tels que ConfigurationElement, ConfigurationElementCollection, ConfigurationProperty et ConfigurationSection, en utilisant un modèle de programmation ou d'un modèle déclaratif (par attributs). Pour obtenir un exemple d'extension d'un type de configuration standard par programme, consultez la classe ConfigurationSection. Pour obtenir un exemple d'extension d'un type de configuration standard à l'aide du mode par attributs, consultez la classe ConfigurationElement.

Remarques à l'attention des implémenteurs : Configuration est la classe qui autorise l'accès par programme pour modifier les fichiers de configuration. Vous utilisez l'une des méthodes Open fournies par WebConfigurationManager pour les applications Web ou par ConfigurationManager pour les applications clientes. Ces méthodes retournent un objet Configuration qui fournit à son tour les méthodes et les propriétés requises pour gérer les fichiers de configuration sous-jacents. Vous pouvez accéder à ces fichiers pour lire ou écrire comme expliqué dans les sections suivantes :

  • Lecture. Vous utilisez GetSection ou GetSectionGroup pour lire les informations de configuration. Notez que l'utilisateur ou le processus qui lit doit avoir les autorisations suivantes :

    • Autorisation en lecture sur le fichier de configuration au niveau de la hiérarchie de configuration en cours.

    • Autorisations en lecture sur tous les fichiers de configuration parents.

    Si votre application requiert un accès en lecture seule à sa propre configuration et qu'il s'agit d'une application Web, il est recommandé d'utiliser l'une des méthodes surchargées GetSection. S'il s'agit d'une application cliente, utilisez la méthode GetSection.

    Ces méthodes donnent accès aux valeurs de configuration mises en cache pour l'application actuelle et offrent ainsi de meilleures performances que la classe Configuration.

    RemarqueRemarque :

    Si vous utilisez une méthode statique GetSection qui utilise un paramètre path, ce paramètre path doit faire référence à l'application dans laquelle le code s'exécute ; sinon, il est ignoré et les informations de configuration de l'application en cours d'exécution sont retournées.

  • Écriture. Vous utilisez l'une des méthodes Save pour écrire des informations de configuration. Notez que l'utilisateur ou le processus qui écrit doit avoir les autorisations suivantes :

    • Autorisation en écriture sur le fichier de configuration et le répertoire au niveau de la hiérarchie de configuration en cours.

    • Autorisations en lecture sur tous les fichiers de configuration.

Remarques à l'attention des héritiers : Chaque objet ConfigurationElement crée une collection ConfigurationPropertyCollection interne d'objets ConfigurationProperty qui représente les attributs d'éléments ou une collection d'éléments enfants. Les informations et les fonctionnalités non personnalisables sont stockées dans un objet ElementInformation fourni par la propriété ElementInformation. Vous pouvez utiliser un modèle de codage déclaratif (par attributs) ou de programmation pour créer un élément de configuration personnalisé :

  • Le modèle de programmation nécessite, pour chaque attribut d'élément, la création d'une propriété afin d'obtenir ou de définir sa valeur et de l'ajouter au sac de propriétés interne de la classe de base ConfigurationElement sous-jacente.

  • Le modèle déclaratif le plus simple, également appelé « modèle par attributs », vous permet de définir un attribut d'élément au moyen d'une propriété et de le décorer avec des attributs. Ces attributs indiquent au système de configuration ASP.NET quels sont les types des 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 pour vous les objets de propriétés d'éléments et exécute l'initialisation requise.

L'exemple de code suivant montre comment implémenter une ConfigurationElement personnalisée.

Cet élément est utilisé par une section personnalisée pour définir une section personnalisée ou une collection d'éléments personnalisés.


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


namespace Samples.AspNet
{

    // Define the UrlConfigElement.
    public class UrlConfigElement :
        ConfigurationElement
    {

        // Test flag.
        private static bool _displayIt = false;

        public UrlConfigElement(String newName,
            String newUrl, int newPort)
        {
            Name = newName;
            Url = newUrl;
            Port = newPort;

        }

        public UrlConfigElement()
        {

        }

        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);

            // Enter your custom processing code here.
            if (_displayIt)
            {
                Console.WriteLine(
                   "UrlConfigElement.DeserializeElement({0}, {1}) called",
                   (reader == null) ? "null" : reader.ToString(),
                   serializeCollectionKey.ToString());
            }
        }


        protected override bool SerializeElement(
            System.Xml.XmlWriter writer, 
            bool serializeCollectionKey)
        {
            bool ret = base.SerializeElement(writer, 
                serializeCollectionKey);

            // Enter your custom processing code here.

            if (_displayIt)
            {
                Console.WriteLine(
                    "UrlConfigElement.SerializeElement({0}, {1}) called = {2}",
                    (writer == null) ? "null" : writer.ToString(),
                    serializeCollectionKey.ToString(), ret.ToString());
            }
            return ret;

        }


        protected override bool IsModified()
        {
            bool ret = base.IsModified();

            // Enter your custom processing code here.

            Console.WriteLine("UrlConfigElement.IsModified() called.");

            return ret;
        }


    }
}

L'extrait de configuration suivant est utilisé dans l'exemple précédent.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="MyUrls" type="Samples.AspNet.Configuration.UrlsSection, ConfigurationElement, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" restartOnExternalChanges="true" />
  </configSections>
  <MyUrls name="MyFavorites" lockAllElementsExcept="urls">
    <simple 
      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>

L'exemple de code suivant montre comment implémenter une collection ConfigurationElementCollection personnalisée qui contient l'élément précédemment défini.


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.
        }
    }
}

L'exemple de code suivant montre comment implémenter une section ConfigurationSection personnalisée qui utilise l'élément précédemment défini.


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


namespace Samples.AspNet
{

    // Define a custom section containing 
    // a simple element and a collection of 
    // the same element. It uses two custom 
    // types: UrlsCollection and 
    // UrlsConfigElement.
    public class UrlsSection :
        ConfigurationSection
    {

        // Test flag.
        private static bool _displayIt = false;

        // Declare the custom element type.
        // This element will also be part of
        // the custom collection.
        UrlConfigElement url;

        public UrlsSection()
        {
            // Create the element.
            url = new UrlConfigElement();
        }

        [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 a simple element 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);

            // Enter your custom processing code here.
            if (_displayIt)
            {
                Console.WriteLine(
                    "UrlsSection.DeserializeSection({0}) called",
                    (reader == null) ? "null" : reader.ToString());
            }
        }

        protected override string SerializeSection(
            ConfigurationElement parentElement,
            string name, ConfigurationSaveMode saveMode)
        {
            string s =
                base.SerializeSection(parentElement,
                name, saveMode);

            // Enter your custom processing code here.

            if (_displayIt)
            {
                Console.WriteLine(
                   "UrlsSection.SerializeSection({0}, {1}, {2}) called = {3}",
                   parentElement.ToString(), name,
                   saveMode.ToString(), s);
            }
            return s;
        }

    }
}

System.Object
  System.Configuration.ConfigurationElement
     Classes dérivées

Les membres statiques publics (Shared en Visual Basic) de ce type sont thread-safe. Il n'est pas garanti que les membres d'instance soient thread-safe.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile pour Pocket PC, Windows Mobile pour Smartphone, Windows Server 2003, Windows XP Édition Media Center, Windows XP Professionnel Édition x64, Windows XP SP2, Windows XP Starter Edition

Microsoft .NET Framework 3.0 est pris en charge sur Windows Vista, Microsoft Windows XP SP2 et Windows Server 2003 SP1.

.NET Framework

Prise en charge dans : 3.0, 2.0
Afficher: