ConfigurationSection Classe

Definizione

public ref class ConfigurationSection abstract : System::Configuration::ConfigurationElement

public abstract class ConfigurationSection : System.Configuration.ConfigurationElement

type ConfigurationSection = class
    inherit ConfigurationElement

Public MustInherit Class ConfigurationSection
Inherits ConfigurationElement

Ereditarietà

Object

ConfigurationElement

ConfigurationSection

Derivato

System.Configuration.AppSettingsSection

System.Configuration.ClientSettingsSection

System.Configuration.ConfigurationBuildersSection

System.Configuration.ConnectionStringsSection

System.Configuration.DefaultSection

Altro…

Esempio

Nell'esempio seguente viene illustrato come implementare una sezione personalizzata a livello di codice.

Per un esempio completo che illustra come implementare e usare una sezione personalizzata implementata usando il modello con attributi, vedere ConfigurationElement.

// Define a custom section.
// The CustomSection type allows to define a custom section 
// programmatically.
public sealed class CustomSection : 
    ConfigurationSection
{
    // The collection (property bag) that contains 
    // the section properties.
    private static ConfigurationPropertyCollection _Properties;
    
    // Internal flag to disable 
    // property setting.
    private static bool _ReadOnly;

    // The FileName property.
    private static readonly ConfigurationProperty _FileName =
        new ConfigurationProperty("fileName", 
        typeof(string),"default.txt", 
        ConfigurationPropertyOptions.IsRequired);

    // The MaxUsers property.
    private static readonly ConfigurationProperty _MaxUsers =
        new ConfigurationProperty("maxUsers", 
        typeof(long), (long)1000, 
        ConfigurationPropertyOptions.None);
    
    // The MaxIdleTime property.
    private static readonly ConfigurationProperty _MaxIdleTime =
        new ConfigurationProperty("maxIdleTime", 
        typeof(TimeSpan), TimeSpan.FromMinutes(5), 
        ConfigurationPropertyOptions.IsRequired);

    // CustomSection constructor.
    public CustomSection()
    {
        // Property initialization
        _Properties = 
            new ConfigurationPropertyCollection();

        _Properties.Add(_FileName);
        _Properties.Add(_MaxUsers);
        _Properties.Add(_MaxIdleTime);
   }

    // This is a key customization. 
    // It returns the initialized property bag.
    protected override ConfigurationPropertyCollection Properties
    {
        get
        {
            return _Properties;
        }
    }

    private new bool IsReadOnly
    {
        get
        {
            return _ReadOnly;
        }
    }

    // Use this to disable property setting.
    private void ThrowIfReadOnly(string propertyName)
    {
        if (IsReadOnly)
            throw new ConfigurationErrorsException(
                "The property " + propertyName + " is read only.");
    }

    // Customizes the use of CustomSection
    // by setting _ReadOnly to false.
    // Remember you must use it along with ThrowIfReadOnly.
    protected override object GetRuntimeObject()
    {
        // To enable property setting just assign true to
        // the following flag.
        _ReadOnly = true;
        return base.GetRuntimeObject();
    }


    [StringValidator(InvalidCharacters = " ~!@#$%^&*()[]{}/;'\"|\\",
        MinLength = 1, MaxLength = 60)]
    public string FileName
    {
        get
        {
            return (string)this["fileName"];
        }
        set
        {
            // With this you disable the setting.
            // Remember that the _ReadOnly flag must
            // be set to true in the GetRuntimeObject.
            ThrowIfReadOnly("FileName");
            this["fileName"] = value;
        }
    }

    [LongValidator(MinValue = 1, MaxValue = 1000000,
        ExcludeRange = false)]
    public long MaxUsers
    {
        get
        {
            return (long)this["maxUsers"];
        }
        set
        {
            this["maxUsers"] = value;
        }
    }

    [TimeSpanValidator(MinValueString = "0:0:30",
        MaxValueString = "5:00:0",
        ExcludeRange = false)]
    public TimeSpan MaxIdleTime
    {
        get
        {
            return  (TimeSpan)this["maxIdleTime"];
        }
        set
        {
            this["maxIdleTime"] = value;
        }
    }
}

' Define a custom section.
' The CustomSection type allows to define a custom section 
' programmatically.

NotInheritable Public Class CustomSection
   Inherits ConfigurationSection
   ' The collection (property bag) that contains 
   ' the section properties.
   Private Shared _Properties As ConfigurationPropertyCollection
   
   ' Internal flag to disable 
   ' property setting.
   Private Shared _ReadOnly As Boolean
   
   ' The FileName property.
    Private Shared _FileName As New ConfigurationProperty( _
    "fileName", GetType(String), _
    "default.txt", _
    ConfigurationPropertyOptions.IsRequired)
   
   ' The MaxUsers property.
    Private Shared _MaxUsers As New ConfigurationProperty( _
    "maxUsers", GetType(Long), _
    CType(1000, Long), _
    ConfigurationPropertyOptions.None)
   
   ' The MaxIdleTime property.
    Private Shared _MaxIdleTime As New ConfigurationProperty( _
    "maxIdleTime", GetType(TimeSpan), _
    TimeSpan.FromMinutes(5), _
    ConfigurationPropertyOptions.IsRequired)
   
   
   ' CustomSection constructor.
   Public Sub New()
      ' Property initialization
        _Properties = _
        New ConfigurationPropertyCollection()
      
      _Properties.Add(_FileName)
      _Properties.Add(_MaxUsers)
      _Properties.Add(_MaxIdleTime)
   End Sub
   
   
   ' This is a key customization. 
   ' It returns the initialized property bag.
    Protected Overrides ReadOnly Property Properties() _
    As ConfigurationPropertyCollection
        Get
            Return _Properties
        End Get
    End Property
   
   
   
   Private Shadows ReadOnly Property IsReadOnly() As Boolean
      Get
         Return _ReadOnly
      End Get
   End Property
   
   
   ' Use this to disable property setting.
   Private Sub ThrowIfReadOnly(propertyName As String)
      If IsReadOnly Then
            Throw New ConfigurationErrorsException( _
            "The property " + propertyName + " is read only.")
      End If
   End Sub
   
   
   
   ' Customizes the use of CustomSection
    ' by setting _ReadOnly to false.
   ' Remember you must use it along with ThrowIfReadOnly.
   Protected Overrides Function GetRuntimeObject() As Object
      ' To enable property setting just assign true to
      ' the following flag.
      _ReadOnly = True
      Return MyBase.GetRuntimeObject()
   End Function 'GetRuntimeObject
   
   
    <StringValidator( _
    InvalidCharacters:=" ~!@#$%^&*()[]{}/;'""|\", _
    MinLength:=1, MaxLength:=60)> _
    Public Property FileName() As String
        Get
            Return CStr(Me("fileName"))
        End Get
        Set(ByVal value As String)
            ' With this you disable the setting.
            ' Remember that the _ReadOnly flag must
            ' be set to true in the GetRuntimeObject.
            ThrowIfReadOnly("FileName")
            Me("fileName") = value
        End Set
    End Property
   
   
    <LongValidator( _
    MinValue:=1, MaxValue:=1000000, _
    ExcludeRange:=False)> _
    Public Property MaxUsers() As Long
        Get
            Return Fix(Me("maxUsers"))
        End Get
        Set(ByVal value As Long)
            Me("maxUsers") = Value
        End Set
    End Property
   
   
    <TimeSpanValidator( _
    MinValueString:="0:0:30", _
    MaxValueString:="5:00:0", ExcludeRange:=False)> _
    Public Property MaxIdleTime() As TimeSpan
        Get
            Return CType(Me("maxIdleTime"), TimeSpan)
        End Get
        Set(ByVal value As TimeSpan)
            Me("maxIdleTime") = Value
        End Set
    End Property
End Class

L'esempio seguente è un estratto del file di configurazione applicato all'esempio precedente.

<?xml version="1.0" encoding="utf-8"?>
 <configuration>
   <configSections>
     <section name="CustomSection" type="Samples.AspNet. CustomSection, CustomConfigurationSection, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" restartOnExternalChanges="true" />
   </configSections>

   <CustomSection fileName="default.txt" maxUsers="1000" maxIdleTime="00:15:00" />

 </configuration>

Commenti

Usare la ConfigurationSection classe per implementare un tipo di sezione personalizzato. Estendere la ConfigurationSection classe per fornire la gestione personalizzata e l'accesso a livello di codice alle sezioni di configurazione personalizzate. Per informazioni sull'uso delle sezioni di configurazione personalizzate, vedere Procedura: Creare sezioni di configurazione personalizzate tramite ConfigurationSection.

Una sezione registra il tipo di gestione con una voce nell'elemento configSections . Per un esempio, vedere l'estratto del file di configurazione illustrato nella sezione Esempio.

Note per gli implementatori

È possibile usare un modello di codifica dichiarativo (con attributi) a livello di codice per creare sezioni di configurazione personalizzate:

• Modello programmatico. Questo modello richiede che per ogni attributo di sezione si crei una proprietà per ottenere o impostare il relativo valore e aggiungerlo al contenitore di proprietà interno della classe di base sottostante ConfigurationElement .

• Modello dichiarativo. Questo modello più semplice, detto anche modello con attributi, consente di definire un attributo di sezione usando una proprietà e decorata con 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 gli oggetti proprietà della sezione ed esegue l'inizializzazione necessaria.

La Configuration classe consente l'accesso a livello di codice per la modifica dei file di configurazione. È possibile accedere a questi file per la lettura o la scrittura come indicato di seguito:

• Lettura. GetSection(String) Usare o GetSectionGroup(String) per leggere le informazioni di configurazione. Si noti che l'utente o il processo che legge deve avere le autorizzazioni seguenti:

  • Autorizzazione di lettura per il file di configurazione a livello di gerarchia di configurazione corrente.

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

  Se l'applicazione richiede l'accesso in sola lettura alla propria configurazione, è consigliabile usare i GetSection metodi di overload nel caso di applicazioni Web o il GetSection(String) metodo nel caso delle applicazioni client.

  Questi metodi forniscono l'accesso ai valori di configurazione memorizzati nella cache per l'applicazione corrente, con prestazioni migliori rispetto alla Configuration classe .

Nota: se si utilizza un metodo statico GetSection che accetta un path parametro, il path parametro deve fare riferimento all'applicazione in cui è in esecuzione il codice. In caso contrario, il parametro viene ignorato e vengono restituite le informazioni di configurazione per l'applicazione attualmente in esecuzione.

• Scrittura. Usare uno dei Save metodi per scrivere informazioni di configurazione. Si noti che l'utente o il processo che scrive deve avere le autorizzazioni seguenti:

  • Autorizzazione di scrittura per il file di configurazione e la directory a livello di gerarchia di configurazione corrente.

  • Autorizzazioni di lettura per tutti i file di configurazione.

Costruttori

Proprietà

Metodi

Si applica a

Vedi anche

• Configuration
• SectionInformation
• ConfigurationElement
• Panoramica dell'API di configurazione di ASP.NET