ConfigurationElement Classe
Definizione
Importante
Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.
Rappresenta un elemento di configurazione contenuto in un file di configurazione.
public ref class ConfigurationElement abstractpublic abstract class ConfigurationElementtype ConfigurationElement = classPublic MustInherit Class ConfigurationElement- Ereditarietà
-
ConfigurationElement
- Derivato
Esempio
Nell'esempio di codice seguente viene illustrato come implementare un oggetto personalizzato ConfigurationElement sia come singolo elemento in una sezione personalizzata che come raccolta di elementi in una sezione personalizzata. L'esempio è costituito dai file seguenti:
Un file app.config che contiene una sezione personalizzata denominata
MyUrls. Questa sezione contiene un elemento semplice (non contiene altri elementi) e una raccolta di elementi. L'elemento semplice è denominatosimplee la raccolta è denominataurls.Un'applicazione console. L'applicazione legge il contenuto del file app.config e scrive le informazioni nella console. Usa classi che derivano da ConfigurationElement, ConfigurationElementCollectione ConfigurationSection.
Classe denominata
UrlsSectionche deriva dalla ConfigurationSection classe . Questa classe viene usata per accedere allaMyUrlssezione nel file di configurazione.Classe denominata
UrlsCollectionche deriva dalla ConfigurationElementCollection classe . Questa classe viene usata per accedere allaurlsraccolta nel file di configurazione.Classe denominata
UrlConfigElementche deriva dalla ConfigurationElement classe . Questa classe viene usata per accedere all'elementosimplee ai membri della raccolta nel file diurlsconfigurazione.
Per eseguire l'esempio, seguire questa procedura:
Creare una soluzione con un progetto di applicazione console e un progetto di libreria di classi denominato
ConfigurationElement.Inserire i tre file di classe nel progetto libreria di classi e inserire gli altri file nel progetto della libreria console.
In entrambi i progetti impostare un riferimento a
System.Configuration.Nel progetto dell'applicazione console impostare un riferimento al progetto della libreria di classi.
// 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
Commenti
È ConfigurationElement una classe astratta usata per rappresentare un elemento XML in un file di configurazione, ad esempio Web.config. Un elemento in un file di configurazione può contenere zero, uno o più elementi figlio.
Poiché la ConfigurationElement classe è definita come astratta, non è possibile crearne un'istanza. È possibile derivare solo le classi da esso. .NET Framework include classi derivate dalla ConfigurationElement classe per rappresentare gli elementi di configurazione XML standard, ad esempio ConfigurationSection. È anche possibile estendere la ConfigurationElement classe per accedere a elementi e sezioni di configurazione personalizzati. L'esempio incluso più avanti in questo argomento illustra come accedere agli elementi e alle sezioni di configurazione personalizzati usando classi personalizzate derivate da ConfigurationElement.
È anche possibile estendere i tipi di configurazione standard, ad ConfigurationElementesempio , ConfigurationElementCollection, ConfigurationPropertye ConfigurationSection. Per altre informazioni, vedere la documentazione per tali classi.
Per altre informazioni su come accedere alle informazioni nei file di configurazione, vedere la classe e la ConfigurationManagerWebConfigurationManager classe.
Note per gli implementatori
Ogni ConfigurationElement oggetto crea una raccolta interna ConfigurationPropertyCollection di ConfigurationProperty oggetti che rappresenta gli attributi dell'elemento o una raccolta di elementi figlio.
Le informazioni e le funzionalità non personalizzabili sono contenute in un ElementInformation oggetto fornito dalla ElementInformation proprietà .
È possibile usare un modello di codifica programmatico o dichiarativo (con attributi) per creare un elemento di configurazione personalizzato:
Il modello programmatico richiede che per ogni attributo di elemento venga creata una proprietà per ottenere o impostare il relativo valore e aggiungerla al contenitore di proprietà interno della classe di base sottostante ConfigurationElement . Per un esempio di come usare questo modello, vedere la ConfigurationSection classe .
Il modello dichiarativo più semplice, detto anche modello con attributi, consente di definire un attributo di elemento usando una proprietà e quindi decorarlo con gli attributi. Questi attributi indicano al sistema di configurazione ASP.NET i tipi di proprietà e i relativi valori predefiniti. Con queste informazioni, ottenute tramite reflection, il sistema di configurazione ASP.NET crea automaticamente gli oggetti proprietà dell'elemento ed esegue l'inizializzazione necessaria. L'esempio illustrato più avanti in questo argomento illustra come usare questo modello.
Costruttori
| ConfigurationElement() |
Inizializza una nuova istanza della classe ConfigurationElement. |
Proprietà
| CurrentConfiguration |
Ottiene un riferimento all'istanza di Configuration di livello superiore che rappresenta la gerarchia di configurazione cui appartiene l'istanza corrente di ConfigurationElement. |
| ElementInformation |
Ottiene un oggetto ElementInformation contenente le funzionalità e le informazioni non personalizzabili dell'oggetto ConfigurationElement. |
| ElementProperty |
Ottiene l'oggetto ConfigurationElementProperty che rappresenta l'oggetto ConfigurationElement stesso. |
| EvaluationContext |
Ottiene l'oggetto ContextInformation per l'oggetto ConfigurationElement. |
| HasContext |
Ottiene un valore che indica se la proprietà CurrentConfiguration è |
| Item[ConfigurationProperty] |
Ottiene o imposta una proprietà o un attributo di questo elemento di configurazione. |
| Item[String] |
Ottiene o imposta una proprietà, un attributo o un elemento figlio di questo elemento di configurazione. |
| LockAllAttributesExcept |
Ottiene l'insieme di attributi bloccati. |
| LockAllElementsExcept |
Ottiene l'insieme di elementi bloccati. |
| LockAttributes |
Ottiene l'insieme di attributi bloccati. |
| LockElements |
Ottiene l'insieme di elementi bloccati. |
| LockItem |
Ottiene o imposta un valore che indica se l'elemento è bloccato. |
| Properties |
Ottiene la raccolta di proprietà. |
Metodi
| DeserializeElement(XmlReader, Boolean) |
Legge il codice XML dal file di configurazione. |
| Equals(Object) |
Confronta l'istanza corrente di ConfigurationElement con l'oggetto specificato. |
| GetHashCode() |
Ottiene un valore univoco che rappresenta l'istanza corrente di ConfigurationElement. |
| GetTransformedAssemblyString(String) |
Restituisce la versione trasformata del nome di assembly specificato. |
| GetTransformedTypeString(String) |
Restituisce la versione trasformata del nome del tipo specificato. |
| GetType() |
Ottiene l'oggetto Type dell'istanza corrente. (Ereditato da Object) |
| Init() |
Ripristina lo stato iniziale dell'oggetto ConfigurationElement. |
| InitializeDefault() |
Da utilizzare per inizializzare un insieme predefinito di valori per l'oggetto ConfigurationElement. |
| IsModified() |
Indica se questo elemento di configurazione è stato modificato dopo l'ultimo salvataggio o caricamento durante l'implementazione in una classe derivata. |
| IsReadOnly() |
Ottiene un valore che indica se l'oggetto ConfigurationElement è di sola lettura. |
| ListErrors(IList) |
Aggiunge all'elenco passato gli errori di proprietà non valida di questo oggetto ConfigurationElement e di tutti i sottoelementi. |
| MemberwiseClone() |
Crea una copia superficiale dell'oggetto Object corrente. (Ereditato da Object) |
| OnDeserializeUnrecognizedAttribute(String, String) |
Ottiene un valore che indica se viene incontrato un attributo sconosciuto durante la deserializzazione. |
| OnDeserializeUnrecognizedElement(String, XmlReader) |
Ottiene un valore che indica se viene incontrato un attributo sconosciuto durante la deserializzazione. |
| OnRequiredPropertyNotFound(String) |
Genera un'eccezione quando una proprietà obbligatoria non viene trovata. |
| PostDeserialize() |
Da chiamare dopo la deserializzazione. |
| PreSerialize(XmlWriter) |
Da chiamare prima della serializzazione. |
| Reset(ConfigurationElement) |
Reimposta lo stato interno dell'oggetto ConfigurationElement, inclusi i blocchi e le raccolte di proprietà. |
| ResetModified() |
Reimposta il valore del metodo IsModified() su |
| SerializeElement(XmlWriter, Boolean) |
Scrive il contenuto di questo elemento di configurazione nel file di configurazione in caso di implementazione in una classe derivata. |
| SerializeToXmlElement(XmlWriter, String) |
Scrive i tag esterni di questo elemento di configurazione nel file di configurazione in caso di implementazione in una classe derivata. |
| SetPropertyValue(ConfigurationProperty, Object, Boolean) |
Imposta una proprietà sul valore specificato. |
| SetReadOnly() |
Imposta la proprietà IsReadOnly() per l'oggetto ConfigurationElement e tutti i sottoelementi. |
| ToString() |
Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object) |
| Unmerge(ConfigurationElement, ConfigurationElement, ConfigurationSaveMode) |
Modifica l'oggetto ConfigurationElement in modo da rimuovere tutti i valori che non devono essere salvati. |
