Compartilhar via


ConfigurationSection Classe

Definição

Representa uma seção em um arquivo de configuração.

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
Herança
ConfigurationSection
Derivado

Exemplos

O exemplo a seguir mostra como implementar uma seção personalizada programaticamente.

Para obter um exemplo completo que mostra como implementar e usar uma seção personalizada implementada usando o modelo atribuído, consulte 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

O exemplo a seguir é um trecho do arquivo de configuração que se aplica ao exemplo anterior.

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

Comentários

Use a ConfigurationSection classe para implementar um tipo de seção personalizado. Estenda a ConfigurationSection classe para fornecer tratamento personalizado e acesso programático a seções de configuração personalizadas. Para obter informações sobre como usar seções de configuração personalizadas, consulte Como criar seções de configuração personalizadas usando ConfigurationSection.

Uma seção registra seu tipo de manipulação com uma entrada no configSections elemento . Para obter um exemplo, consulte o trecho do arquivo de configuração mostrado na seção Exemplo.

Observação

Nas versões anteriores do .NET Framework, os manipuladores de seção de configuração eram usados para fazer alterações nas definições de configuração programaticamente. Agora, todas as seções de configuração padrão são representadas por classes que estendem a ConfigurationSection classe .

Notas aos Implementadores

Você pode usar um modelo de codificação programático ou declarativo (atribuído) para criar seções de configuração personalizadas:

  • Modelo programático. Esse modelo requer que, para cada atributo de seção, você crie uma propriedade para obter ou definir seu valor e adicioná-la ao recipiente de propriedades internas da classe base subjacente ConfigurationElement .

  • Modelo declarativo. Esse modelo mais simples, também chamado de modelo atribuído, permite que você defina um atributo de seção usando uma propriedade e decorando-o com atributos. Esses atributos instruem o sistema de configuração ASP.NET sobre os tipos de propriedade e seus valores padrão. Com essas informações, obtidas por meio da reflexão, o sistema de configuração ASP.NET cria os objetos de propriedade da seção e executa a inicialização necessária.

A Configuration classe permite acesso programático para editar arquivos de configuração. Você pode acessar esses arquivos para leitura ou gravação da seguinte maneira:

  • Leitura. Você usa GetSection(String) ou GetSectionGroup(String) para ler informações de configuração. Observe que o usuário ou processo que lê deve ter as seguintes permissões:

    • Permissão de leitura no arquivo de configuração no nível da hierarquia de configuração atual.

    • Permissões de leitura em todos os arquivos de configuração pai.

    Se o aplicativo precisar de acesso somente leitura à sua própria configuração, é recomendável usar os GetSection métodos sobrecarregados no caso de aplicativos Web ou o GetSection(String) método no caso de aplicativos cliente.

    Esses métodos fornecem acesso aos valores de configuração armazenados em cache para o aplicativo atual, que tem melhor desempenho do que a Configuration classe .

Observação: se você usar um método estático GetSection que usa um path parâmetro , o path parâmetro deverá se referir ao aplicativo no qual o código está sendo executado; caso contrário, o parâmetro será ignorado e as informações de configuração do aplicativo em execução no momento serão retornadas.

  • Escrever. Você usa um dos Save métodos para gravar informações de configuração. Observe que o usuário ou processo que grava deve ter as seguintes permissões:

    • Permissão de gravação no arquivo de configuração e no diretório no nível da hierarquia de configuração atual.

    • Permissões de leitura em todos os arquivos de configuração.

Construtores

ConfigurationSection()

Inicializa uma nova instância da classe ConfigurationSection.

Propriedades

CurrentConfiguration

Obtém uma referência para a instância Configuration de nível superior que representa a hierarquia de configuração à qual a instância atual ConfigurationElement pertence.

(Herdado de ConfigurationElement)
ElementInformation

Obtém um objeto ElementInformation que contém as informações não personalizáveis e a funcionalidade do objeto ConfigurationElement.

(Herdado de ConfigurationElement)
ElementProperty

Obtém o objeto ConfigurationElementProperty que representa o próprio objeto ConfigurationElement.

(Herdado de ConfigurationElement)
EvaluationContext

Obtém o objeto ContextInformation para o objeto ConfigurationElement.

(Herdado de ConfigurationElement)
HasContext

Obtém um valor que indica se a propriedade CurrentConfiguration é null.

(Herdado de ConfigurationElement)
Item[ConfigurationProperty]

Obtém ou define uma propriedade ou um atributo desse elemento de configuração.

(Herdado de ConfigurationElement)
Item[String]

Obtém ou define uma propriedade, atributo ou elemento filho desse elemento de configuração.

(Herdado de ConfigurationElement)
LockAllAttributesExcept

Obtém a coleção de atributos bloqueados.

(Herdado de ConfigurationElement)
LockAllElementsExcept

Obtém a coleção de elementos bloqueados.

(Herdado de ConfigurationElement)
LockAttributes

Obtém a coleção de atributos bloqueados.

(Herdado de ConfigurationElement)
LockElements

Obtém a coleção de elementos bloqueados.

(Herdado de ConfigurationElement)
LockItem

Obtém ou define um valor que indica se o elemento está bloqueado.

(Herdado de ConfigurationElement)
Properties

Obtém a coleção de propriedades.

(Herdado de ConfigurationElement)
SectionInformation

Obtém um objeto SectionInformation que contém as informações não personalizáveis e a funcionalidade do objeto ConfigurationSection.

Métodos

DeserializeElement(XmlReader, Boolean)

Lê o XML do arquivo de configuração.

(Herdado de ConfigurationElement)
DeserializeSection(XmlReader)

Lê o XML do arquivo de configuração.

Equals(Object)

Compara a instância ConfigurationElement atual com o objeto especificado.

(Herdado de ConfigurationElement)
GetHashCode()

Obtém um valor exclusivo que representa a instância ConfigurationElement atual.

(Herdado de ConfigurationElement)
GetRuntimeObject()

Retorna um objeto personalizado quando substituído em uma classe derivada.

GetTransformedAssemblyString(String)

Retorna a versão transformada do nome do assembly especificado.

(Herdado de ConfigurationElement)
GetTransformedTypeString(String)

Retorna a versão transformada do nome do tipo especificado.

(Herdado de ConfigurationElement)
GetType()

Obtém o Type da instância atual.

(Herdado de Object)
Init()

Define o objeto ConfigurationElement para seu estado inicial.

(Herdado de ConfigurationElement)
InitializeDefault()

Usado para inicializar um conjunto padrão de valores para o objeto ConfigurationElement.

(Herdado de ConfigurationElement)
IsModified()

Indica se este elemento de configuração foi modificado desde a última vez em que foi salvo ou carregado quando implementado em uma classe derivada.

IsReadOnly()

Obtém um valor que indica se o objeto ConfigurationElement é somente leitura.

(Herdado de ConfigurationElement)
ListErrors(IList)

Adiciona os erros de propriedade inválida deste objeto ConfigurationElement e de todos os subelementos à lista passada.

(Herdado de ConfigurationElement)
MemberwiseClone()

Cria uma cópia superficial do Object atual.

(Herdado de Object)
OnDeserializeUnrecognizedAttribute(String, String)

Obtém um valor que indica se um atributo desconhecido é encontrado durante a desserialização.

(Herdado de ConfigurationElement)
OnDeserializeUnrecognizedElement(String, XmlReader)

Obtém um valor que indica se um elemento desconhecido é encontrado durante a desserialização.

(Herdado de ConfigurationElement)
OnRequiredPropertyNotFound(String)

Gera uma exceção quando uma propriedade necessária não é encontrada.

(Herdado de ConfigurationElement)
PostDeserialize()

Chamado depois da desserialização.

(Herdado de ConfigurationElement)
PreSerialize(XmlWriter)

Chamado antes da serialização.

(Herdado de ConfigurationElement)
Reset(ConfigurationElement)

Redefine o estado interno do objeto ConfigurationElement, incluindo os bloqueios e as coleções de propriedades.

(Herdado de ConfigurationElement)
ResetModified()

Redefine o valor do método IsModified() para false quando implementado em uma classe derivada.

SerializeElement(XmlWriter, Boolean)

Grava o conteúdo desse elemento de configuração no arquivo de configuração quando implementado em uma classe derivada.

(Herdado de ConfigurationElement)
SerializeSection(ConfigurationElement, String, ConfigurationSaveMode)

Cria uma cadeia de caracteres XML que contém uma exibição não mesclada do objeto ConfigurationSection como uma única seção a ser gravada em um arquivo.

SerializeToXmlElement(XmlWriter, String)

Grava as marcas externas desse elemento de configuração no arquivo de configuração quando implementado em uma classe derivada.

(Herdado de ConfigurationElement)
SetPropertyValue(ConfigurationProperty, Object, Boolean)

Define uma propriedade para o valor especificado.

(Herdado de ConfigurationElement)
SetReadOnly()

Define a propriedade IsReadOnly() para o objeto ConfigurationElement e para todos os subelementos.

(Herdado de ConfigurationElement)
ShouldSerializeElementInTargetVersion(ConfigurationElement, String, FrameworkName)

Indica se o elemento especificado deve ser serializado quando a hierarquia de objetos de configuração é serializada para a versão de destino especificada do .NET Framework.

ShouldSerializePropertyInTargetVersion(ConfigurationProperty, String, FrameworkName, ConfigurationElement)

Indica se a propriedade especificada deve ser serializada quando a hierarquia de objetos de configuração é serializada para a versão de destino especificada do .NET Framework.

ShouldSerializeSectionInTargetVersion(FrameworkName)

Indica se a instância atual ConfigurationSection deve ser serializada quando a hierarquia de objetos de configuração é serializada para a versão de destino especificada do .NET Framework.

ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.

(Herdado de Object)
Unmerge(ConfigurationElement, ConfigurationElement, ConfigurationSaveMode)

Modifica o objeto ConfigurationElement para remover todos os valores que não devem ser salvos.

(Herdado de ConfigurationElement)

Aplica-se a

Confira também