ConfigurationSection Classe

Definição

Representa uma seção em um arquivo de configuração.Represents a section within a configuration file.

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.The following example shows how to implement a custom section programmatically.

Para obter um exemplo completo que mostra como implementar e usar uma seção personalizada implementada usando o modelo atribuído, consulte ConfigurationElement.For a complete example that shows how to implement and use a custom section implemented using the attributed model, see 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 como ele se aplica ao exemplo anterior.The following example is an excerpt of the configuration file as it applies to the previous example.

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

Você usa a classe ConfigurationSection para implementar um tipo de seção personalizada.You use the ConfigurationSection class to implement a custom section type. Estenda a classe ConfigurationSection para fornecer tratamento personalizado e acesso programático a seções de configuração personalizadas.Extend the ConfigurationSection class to provide custom handling and programmatic access to custom configuration sections. Para obter informações sobre como usar seções de configuração personalizadas, consulte como criar seções de configuração personalizadas usando ConfigurationSection.For information about how use custom configuration sections, see How to: Create Custom Configuration Sections Using ConfigurationSection.

Uma seção registra seu tipo de manuseio com uma entrada no elemento configSections.A section registers its handling type with an entry in the configSections element. Para obter um exemplo, consulte o trecho do arquivo de configuração mostrado na seção de exemplo.For an example, see the configuration file excerpt shown in the Example section.

Observação

Nas versões anteriores do .NET Framework, os manipuladores da seção de configuração foram usados para fazer alterações nas definições de configuração programaticamente.In previous versions of the .NET Framework, configuration section handlers were used to make changes to configuration settings programmatically. Agora, todas as seções de configuração padrão são representadas por classes que estendem a classe ConfigurationSection.Now, all the default configuration sections are represented by classes that extend the ConfigurationSection class.

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:You can use a programmatic or a declarative (attributed) coding model to create custom configuration sections: -Modelo programático.- Programmatic model. Esse modelo requer que, para cada atributo de seção, você crie uma propriedade para obter ou defina seu valor e adicione-o ao recipiente de propriedades interna da classe base de ConfigurationElement subjacente.This model requires that for each section attribute you create a property to get or set its value and add it to the internal property bag of the underlying ConfigurationElement base class.

-Modelo declarativo.- Declarative model. Esse modelo mais simples, também chamado de modelo atribuído, permite que você defina um atributo de seção usando uma propriedade e decoração-o com atributos.This simpler model, also called the attributed model, allows you to define a section attribute by using a property and decorating it with attributes. Esses atributos instruem o sistema de configuração ASP.NET sobre os tipos de propriedade e seus valores padrão.These attributes instruct the ASP.NET configuration system about the property types and their default values. Com essas informações, obtidas por meio de reflexão, o sistema de configuração ASP.NET cria os objetos de propriedade da seção e executa a inicialização necessária.With this information, obtained through reflection, the ASP.NET configuration system creates the section property objects and performs the required initialization.

A classe Configuration permite acesso programático à edição de arquivos de configuração.The Configuration class allows programmatic access for editing configuration files. Você pode acessar esses arquivos para leitura ou gravação da seguinte maneira:You can access these files for reading or writing as follows: Leitura.- Reading. Você usa GetSection(String) ou GetSectionGroup(String) para ler as informações de configuração.You use GetSection(String) or GetSectionGroup(String) to read configuration information. Observe que o usuário ou processo que lê deve ter as seguintes permissões:Note that the user or process that reads must have the following permissions: -Permissão de leitura no arquivo de configuração no nível da hierarquia de configuração atual.- Read permission on the configuration file at the current configuration hierarchy level.

-Permissões de leitura em todos os arquivos de configuração pai.- Read permissions on all the parent configuration files.

Se seu aplicativo precisar de acesso somente leitura para sua própria configuração, é recomendável usar os GetSection métodos sobrecarregados no caso de aplicativos Web ou o método GetSection(String) no caso de aplicativos cliente.If your application needs read-only access to its own configuration, it is recommended you use the GetSection overloaded methods in the case of Web applications, or the GetSection(String) method in the case of client applications.

Esses métodos fornecem acesso aos valores de configuração em cache para o aplicativo atual, que tem um desempenho melhor do que a classe Configuration.These methods provide access to the cached configuration values for the current application, which has better performance than the Configuration class.


Se você usar um método de GetSection estático que usa um parâmetro path, o parâmetro path 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 para o aplicativo em execução no momento serão retornadas.If you use a static GetSection method that takes a path parameter, the path parameter must refer to the application in which the code is running; otherwise, the parameter is ignored and configuration information for the currently-running application is returned.

Criando.- Writing. Você usa um dos métodos de Save para gravar informações de configuração.You use one of the Save methods to write configuration information. Observe que o usuário ou processo que grava deve ter as seguintes permissões:Note that the user or process that writes must have the following permissions: -Permissão de gravação no arquivo de configuração e no diretório no nível da hierarquia de configuração atual.- Write permission on the configuration file and directory at the current configuration hierarchy level. -Permissões de leitura em todos os arquivos de configuração.- Read permissions on all the configuration files.

Construtores

ConfigurationSection()

Inicializa uma nova instância da classe ConfigurationSection.Initializes a new instance of the ConfigurationSection class.

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.Gets a reference to the top-level Configuration instance that represents the configuration hierarchy that the current ConfigurationElement instance belongs to.

(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.Gets an ElementInformation object that contains the non-customizable information and functionality of the ConfigurationElement object.

(Herdado de ConfigurationElement)
ElementProperty

Obtém o objeto ConfigurationElementProperty que representa o próprio objeto ConfigurationElement.Gets the ConfigurationElementProperty object that represents the ConfigurationElement object itself.

(Herdado de ConfigurationElement)
EvaluationContext

Obtém o objeto ContextInformation para o objeto ConfigurationElement.Gets the ContextInformation object for the ConfigurationElement object.

(Herdado de ConfigurationElement)
HasContext

Obtém um valor que indica se a propriedade CurrentConfiguration é null.Gets a value that indicates whether the CurrentConfiguration property is null.

(Herdado de ConfigurationElement)
Item[ConfigurationProperty]

Obtém ou define uma propriedade ou um atributo desse elemento de configuração.Gets or sets a property or attribute of this configuration element.

(Herdado de ConfigurationElement)
Item[String]

Obtém ou define uma propriedade, atributo ou elemento filho desse elemento de configuração.Gets or sets a property, attribute, or child element of this configuration element.

(Herdado de ConfigurationElement)
LockAllAttributesExcept

Obtém a coleção de atributos bloqueados.Gets the collection of locked attributes.

(Herdado de ConfigurationElement)
LockAllElementsExcept

Obtém a coleção de elementos bloqueados.Gets the collection of locked elements.

(Herdado de ConfigurationElement)
LockAttributes

Obtém a coleção de atributos bloqueados.Gets the collection of locked attributes.

(Herdado de ConfigurationElement)
LockElements

Obtém a coleção de elementos bloqueados.Gets the collection of locked elements.

(Herdado de ConfigurationElement)
LockItem

Obtém ou define um valor que indica se o elemento está bloqueado.Gets or sets a value indicating whether the element is locked.

(Herdado de ConfigurationElement)
Properties

Obtém a coleção de propriedades.Gets the collection of properties.

(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.Gets a SectionInformation object that contains the non-customizable information and functionality of the ConfigurationSection object.

Métodos

DeserializeElement(XmlReader, Boolean)

Lê o XML do arquivo de configuração.Reads XML from the configuration file.

(Herdado de ConfigurationElement)
DeserializeSection(XmlReader)

Lê o XML do arquivo de configuração.Reads XML from the configuration file.

Equals(Object)

Compara a instância ConfigurationElement atual com o objeto especificado.Compares the current ConfigurationElement instance to the specified object.

(Herdado de ConfigurationElement)
GetHashCode()

Obtém um valor exclusivo que representa a instância ConfigurationElement atual.Gets a unique value representing the current ConfigurationElement instance.

(Herdado de ConfigurationElement)
GetRuntimeObject()

Retorna um objeto personalizado quando substituído em uma classe derivada.Returns a custom object when overridden in a derived class.

GetTransformedAssemblyString(String)

Retorna a versão transformada do nome do assembly especificado.Returns the transformed version of the specified assembly name.

(Herdado de ConfigurationElement)
GetTransformedTypeString(String)

Retorna a versão transformada do nome do tipo especificado.Returns the transformed version of the specified type name.

(Herdado de ConfigurationElement)
GetType()

Obtém o Type da instância atual.Gets the Type of the current instance.

(Herdado de Object)
Init()

Define o objeto ConfigurationElement para seu estado inicial.Sets the ConfigurationElement object to its initial state.

(Herdado de ConfigurationElement)
InitializeDefault()

Usado para inicializar um conjunto padrão de valores para o objeto ConfigurationElement.Used to initialize a default set of values for the ConfigurationElement object.

(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.Indicates whether this configuration element has been modified since it was last saved or loaded when implemented in a derived class.

IsReadOnly()

Obtém um valor que indica se o objeto ConfigurationElement é somente leitura.Gets a value indicating whether the ConfigurationElement object is read-only.

(Herdado de ConfigurationElement)
ListErrors(IList)

Adiciona os erros de propriedade inválida deste objeto ConfigurationElement e de todos os subelementos à lista passada.Adds the invalid-property errors in this ConfigurationElement object, and in all subelements, to the passed list.

(Herdado de ConfigurationElement)
MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Herdado de Object)
OnDeserializeUnrecognizedAttribute(String, String)

Obtém um valor que indica se um atributo desconhecido é encontrado durante a desserialização.Gets a value indicating whether an unknown attribute is encountered during deserialization.

(Herdado de ConfigurationElement)
OnDeserializeUnrecognizedElement(String, XmlReader)

Obtém um valor que indica se um elemento desconhecido é encontrado durante a desserialização.Gets a value indicating whether an unknown element is encountered during deserialization.

(Herdado de ConfigurationElement)
OnRequiredPropertyNotFound(String)

Gera uma exceção quando uma propriedade necessária não é encontrada.Throws an exception when a required property is not found.

(Herdado de ConfigurationElement)
PostDeserialize()

Chamado depois da desserialização.Called after deserialization.

(Herdado de ConfigurationElement)
PreSerialize(XmlWriter)

Chamado antes da serialização.Called before serialization.

(Herdado de ConfigurationElement)
Reset(ConfigurationElement)

Redefine o estado interno do objeto ConfigurationElement, incluindo os bloqueios e as coleções de propriedades.Resets the internal state of the ConfigurationElement object, including the locks and the properties collections.

(Herdado de ConfigurationElement)
ResetModified()

Redefine o valor do método IsModified() para false quando implementado em uma classe derivada.Resets the value of the IsModified() method to false when implemented in a derived class.

SerializeElement(XmlWriter, Boolean)

Grava o conteúdo desse elemento de configuração no arquivo de configuração quando implementado em uma classe derivada.Writes the contents of this configuration element to the configuration file when implemented in a derived class.

(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.Creates an XML string containing an unmerged view of the ConfigurationSection object as a single section to write to a file.

SerializeToXmlElement(XmlWriter, String)

Grava as marcas externas desse elemento de configuração no arquivo de configuração quando implementado em uma classe derivada.Writes the outer tags of this configuration element to the configuration file when implemented in a derived class.

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

Define uma propriedade para o valor especificado.Sets a property to the specified value.

(Herdado de ConfigurationElement)
SetReadOnly()

Define a propriedade IsReadOnly() para o objeto ConfigurationElement e para todos os subelementos.Sets the IsReadOnly() property for the ConfigurationElement object and all subelements.

(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.NET Framework.Indicates whether the specified element should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework.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.NET Framework.Indicates whether the specified property should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework.NET Framework.

ShouldSerializeSectionInTargetVersion(FrameworkName)

Indica se a instância ConfigurationSection atual deve ser serializada quando a hierarquia de objetos de configuração é serializada para a versão de destino especificada do .NET Framework.NET Framework.Indicates whether the current ConfigurationSection instance should be serialized when the configuration object hierarchy is serialized for the specified target version of the .NET Framework.NET Framework.

ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.Returns a string that represents the current object.

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

Modifica o objeto ConfigurationElement para remover todos os valores que não devem ser salvos.Modifies the ConfigurationElement object to remove all values that should not be saved.

(Herdado de ConfigurationElement)

Aplica-se a

Veja também