Questa documentazione è stata archiviata e non viene gestita.

Classe ConfigurationElement

Nota: questa classe è stata introdotta con .NET Framework versione 2.0.

Rappresenta un elemento di configurazione contenuto in un file di configurazione.

Spazio dei nomi: System.Configuration
Assembly: System.Configuration (in system.configuration.dll)

public abstract class ConfigurationElement
public abstract class ConfigurationElement
public abstract class ConfigurationElement

Poiché ConfigurationElement è una classe astratta, non è possibile crearne istanze. Rappresenta un elemento all'interno di un file di configurazione.

NotaNota

Un elemento all'interno di un file di configurazione fa riferimento a una sezione o a un elemento XML di base. L'elemento di base è un tag XML semplice con eventuali attributi correlati. Nel formato più semplice una sezione corrisponde a un elemento di base. Le sezioni complesse possono contenere uno o più elementi di base, un insieme di elementi e altre sezioni.

La classe ConfigurationElement viene utilizzata come classe base per le classi che rappresentano elementi di configurazione XML, ad esempio ConfigurationSection.

È possibile estendere la classe ConfigurationElement in modo da rappresentare un elemento di configurazione contenuto in una sezione ConfigurationSection. È inoltre possibile creare un insieme ConfigurationElementCollection di elementi ConfigurationElement, come illustrato nell'esempio riportato di seguito.

  • Gestione della configurazione. Per gestire le informazioni relative alla configurazione mediante i tipi standard, attenersi alle istruzioni riportate di seguito.

  • Estensione dei tipi standard di configurazione. È anche possibile estendere i tipi standard di configurazione quali ConfigurationElement, ConfigurationElementCollection, ConfigurationProperty e ConfigurationSection utilizzando un modello a livello di codice o un modello dichiarativo, ovvero con attributi. Per un esempio sull'estensione di un tipo standard di configurazione a livello di codice, fare riferimento alla classe ConfigurationSection. Per un esempio sull'estensione di un tipo standard di configurazione utilizzando il modello con attributi, fare riferimento alla classe ConfigurationElement.

Note per gli implementatori: Configuration è la classe che consente l'accesso a livello di codice per la modifica dei file di configurazione. Utilizzare uno dei metodi Open forniti da WebConfigurationManager per le applicazioni Web o da ConfigurationManager per le applicazioni client. Questi metodi restituiranno un oggetto Configuration, che a sua volta fornisce i metodi e le proprietà necessari per la gestione dei file di configurazione sottostanti. Viene descritto di seguito come accedere a questi file in lettura o in scrittura.

  • Lettura. Utilizzare GetSection o GetSectionGroup per leggere le informazioni di configurazione. Notare che l'utente o il processo che esegue la lettura deve disporre delle seguenti autorizzazioni:

    • Autorizzazione di lettura per il file di configurazione in corrispondenza del livello di gerarchia di configurazione corrente.

    • Autorizzazioni di lettura per tutti i file di configurazione padre.

Se l'applicazione necessita di un accesso in sola lettura alla propria configurazione, è consigliabile utilizzare i metodi di overload GetSection nel caso delle applicazioni Web o il metodo GetSection nel caso delle applicazioni client. Questi metodi consentono di accedere ai valori di configurazione dell'applicazione corrente salvati nella cache, garantendo prestazioni migliori rispetto alla classe Configuration.
NotaNota

Se si utilizza un metodo GetSection statico che utilizza un parametro path, il parametro path deve fare riferimento all'applicazione in cui è in esecuzione il codice, altrimenti il parametro verrà ignorato e verranno restituite le informazioni della configurazione dell'applicazione attualmente in esecuzione.

  • Scrittura. Utilizzare uno dei metodi Save per scrivere le informazioni di configurazione. Notare che l'utente o il processo che esegue la scrittura deve disporre delle seguenti autorizzazioni:

    • Autorizzazione di scrittura per la directory e il file di configurazione in corrispondenza del livello di gerarchia di configurazione corrente.

    • Autorizzazioni di lettura per tutti i file di configurazione.

Note sull'ereditarietà: Ogni oggetto ConfigurationElement crea un insieme ConfigurationPropertyCollection interno di oggetti ConfigurationProperty che rappresenta gli attributi dell'elemento o un insieme di elementi figlio. Le funzionalità e le informazioni non personalizzabili sono contenute in un oggetto ElementInformation fornito dalla proprietà ElementInformation. È possibile utilizzare un modello di codifica a livello di codice oppure dichiarativo, ovvero con attributi, per creare un elemento di configurazione personalizzato.

  • Modello a livello di codice. Questo modello richiede che per ogni attributo di elemento venga creata una proprietà per ottenerne e/o impostarne il valore e aggiungerlo all'elenco proprietà interno della classe base ConfigurationElement sottostante.

  • Modello dichiarativo. Questo modello più semplice, detto anche modello con attributi, consente di definire un attributo di elemento utilizzando una proprietà e di decorarlo con attributi. Questi attributi indicano al sistema di configurazione di ASP.NET i tipi di proprietà e i valori predefiniti. Con queste informazioni, ottenute tramite la reflection, il sistema di configurazione ASP.NET crea gli oggetti della proprietà dell'elemento ed esegue l'inizializzazione necessaria.

Nell'esempio di codice riportato di seguito viene illustrato come implementare una classe ConfigurationElement personalizzata.

Questo elemento viene utilizzato da una sezione personalizzata per definire una sezione personalizzata o un insieme di elementi personalizzati.


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


    }
}

Viene riportato di seguito un frammento di configurazione utilizzato dall'esempio precedente.

<?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 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>

Nell'esempio di codice riportato di seguito viene illustrato come implementare una classe ConfigurationElementCollection personalizzata contenente l'elemento precedentemente definito.


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

Nell'esempio di codice riportato di seguito viene illustrato come implementare una sezione ConfigurationSection personalizzata che utilizza l'elemento precedentemente definito.


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
     Classi derivate

I membri statici pubblici (Shared in Visual Basic) di questo tipo sono validi per le operazioni multithreading. I membri di istanza non sono garantiti come 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

.NET Framework non supporta tutte le versioni di ciascuna piattaforma. Per un elenco delle versioni supportate, vedere Requisiti di sistema.

.NET Framework

Supportato in: 2.0
Mostra: