Visão Geral da API de Configuração do ASP.NET

  • Artigo

A API de configuração do ASP.NET permite que você desenvolva, implante e gerencie os dados de configuração do aplicativo pelo uso de um única interface de programação.Você pode usar a API de configuração para desenvolver e modificar configurações completas do ASP.NET de forma programável sem editar diretamente o XML nos arquivos de configuração.Além disso, você pode usar a API de configuração em aplicativos de console e scripts que você desenvolver, em ferramentas de gerenciamento baseados na Web e em snap-ins do Microsoft Management Console (MMC).As duas ferramentas de configuração e gerenciamento a seguir usam a API de configuração e estão inclusas com o .NET Framework versão 2.0:

  • O snap-in do MMC do ASP.NET, que usa a API de configuração para simplificar tarefas administrativas, fornecendo uma visão integrada de dados de configuração local de todos os níveis da hierarquia de configuração.

  • A Ferramenta de Administração de Site Web, que permite a você gerenciar configurações para aplicativos locais e remotos, inclusive sites hospedados.

A API de configuração do ASP.NET é separada dos Serviços de Informação da Internet (IIS) de maneira programável na API de configuração.Para obter mais informações, consulte Usando a administração programática do IIS.

Recursos da API de Configuração

A API de configuração do ASP.NET constitui um conjunto de objetos de gerenciamento do ASP.NET que você pode usar para configurar sites e aplicativos de forma programável.Objetos de gerenciamento são implementados como um biblioteca de classes do .NET Framework.O modelo de programação da API de configuração ajuda a garantir a consistência e confiabilidade do código aplicando tipos de dados em tempo de compilação.

Para tornar mais fácil gerenciar as configurações do aplicativo, a configuração API permite que você exiba os dados que são mesclados de todos os pontos na hierarquia de configuração como um único conjunto, em vez de exibir os dados como coleções separadas de diferentes arquivos de configuração.Além disso, a API de configuração permite que você manipule todas as configurações do aplicativo sem editar diretamente o XML nos arquivos de configuração.Finalmente, a API simplifica tarefas de configuração apoiando ferramentas administrativas, como a Ferramenta de Administração de Site.

A API de configuração simplifica a implantação, apoiando a criação dos arquivos de configuração em um computador e executando scripts de configuração entre vários computadores.

A API de configuração não oferece suporte à criação de aplicativos do IIS.Para obter informações sobre como escrever aplicativos de administração do IIS, consulte Usando sistema.DirectoryServices para configurar o IIS no IIS SDK.

Trabalhando com Parâmetros de Configuração Local e Remoto

Um objeto Configuration representa a visão mesclada dos parâmetros de configuração que se aplica a uma entidade física específica, como um computador, ou a uma entidade lógica, como um aplicativo ou um site da Web.A entidade lógica especificada pode existir no computador local ou em um servidor remoto.

Quando nenhum arquivo de configuração existe para uma entidade especificada, o objeto Configuration representa os parâmetros de configuração padrão, conforme definido pelo arquivo Machine.config.

Você pode obter um objeto Configuration usando um dos métodos de configuração de abertura das classes a seguir:

Esses métodos irão retornar um objeto Configuration, que, por sua vez, fornece os métodos e propriedades necessários para manipular os arquivos de configuração subjacente.Você pode acessar esses arquivos para leitura ou gravação.

  • Leitura Você usa o método GetSection ou o GetSectionGroup para ler a informação de configuração.O usuário ou processo que lê deve ter Permissão de leitura em todos os arquivos de configuração na hierarquia.

    Observação:

    Se você usar um estático GetSection método que usa um path parâmetro, o path parâmetro deve se referir ao aplicativo no qual o código é executado. Caso contrário, o parâmetro é ignorado e a informação de configuração para o aplicativo em execução no momento é retornada.

  • Escrever Você usa um dos métodos Save para gravar a informação de configuração.O usuário ou processo que grava deve ter Permição de gravação no arquivo e diretório de configuração no nível de hierarquia de configuração atual, bem como Permissões de leitura em todos os arquivos de configuração na hierarquia.

Para gerar um arquivo de configuração que representa os parâmetros de configuração herdados para uma entidade especificada, use um dos seguintes métodos de salvar configuração:

  • O método Save para criar um novo arquivo de configuração.

  • O método SaveAs para gerar um novo arquivo de configuração em outro local.

Observação:

Para habilitar o acesso aos parâmetros de configuração em um computador remoto, use o ferramenta de linha de comando Aspnet_regiis.Para obter mais informações sobre essa ferramenta, consulte Ferramenta de registro ASP.NET IIS (Aspnet_regiis.exe).Para obter informações sobre como criar e acessar parâmetros de configuração personalizados, exceto as seções intrínsecas incluídas no .NET Framework, consulte ConfigurationSection.

Exemplos de código

De dentro uma página ASP.NET, você pode usar o código a seguir para obter informação de configuração sobre o aplicativo no qual a página do ASP.NET é executada.Este exemplo de código usa o método estático WebConfigurationManager.GetSection.

System.Web.Configuration.UrlMappingsSection urlMaps =
    (System.Web.Configuration.UrlMappingsSection)
    System.Web.Configuration.WebConfigurationManager.GetSection(
    "system.web/urlMappings");
Bool urlMappingsEnabled = urlMaps.IsEnabled;

De um aplicativo ASP.NET ou um aplicativo cliente, você pode usar o código a seguir para obter informação de configuração sobre um aplicativo separado.Este exemplo de código usa o método não estático GetSection do objeto System.Configuration.Configuration.

System.Configuration.Configuration config =
    System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration(
    "/SampleWebApp");
System.Web.Configuration.UrlMappingsSection urlMaps =
    (System.Web.Configuration.UrlMappingsSection)
    System.Web.Configuration.WebConfigurationManager.GetSection(
    "system.web/urlMappings");
bool urlMappingsEnabled = urlMaps.IsEnabled;

Classes de Configuração e Namespaces

Muitas classes de configuração e métodos são semelhantes uns aos outros.A tabela a seguir descreve as classes de configuração e os namespaces mais comumente usados.Para obter informações sobre cenários de uso e exemplos de código usando essas classes e namespaces, consulte Usando as Classes de Configuração.

Classe de configuração ou namespaces

Descrição

Namespace System.Configuration

Contém as principais classes de configuração para todos os aplicativos do .NET Framework.Isso inclui as classes manipuladoras de seção para as seções de configuração do cliente do .NET Framework definidas em Esquema do arquivo de configuração para o .NET Framework .Classes manipuladoras de seção são usadas para obter dados de configuração para uma seção de métodos, como GetSection e GetSectionGroup.Esses dois métodos são não estáticos.Para obter mais informações, consulte a seção anterior contida neste tópico Trabalhando com Métodos Estáticos e Não Estáticos.

As classes manipuladoras de seção do ASP.NET estão contidas no namespace System.Web.Configuration.

Classe System.Configuration.Configuration

Representa um conjunto de dados de configuração para um computador, aplicativo, diretório da Web ou outro recurso.Uma instância da classe Configuration corresponde aos parâmetros de configuração mesclados contidos na hierarquia.

Esta classe contém métodos úteis, como GetSection e GetSectionGroup, para atualizar os parâmetros de configuração e obter referências para seções e grupos de seções.Esses dois métodos são não estáticos.Para obter mais informações, consulte a seção anterior contida neste tópico Trabalhando com Métodos Estáticos e Não Estáticos.

Essa classe é usada como um tipo de retorno para métodos que obtêm dados de configuração de tempo de design, como os métodos das classes WebConfigurationManager e ConfigurationManager.

Namespace System.Web.Configuration

Contém as classes manipuladoras de seção para as seções de configuração do ASP.NET definidas em Definições de configuração ASP.NET.Classes manipuladoras de seção são usadas para obter dados de configuração para uma seção de métodos, como GetSection e GetSectionGroup.Esses dois métodos são não estáticos.Para obter mais informações, consulte a seção anterior contida neste tópico Trabalhando com Métodos Estáticos e Não Estáticos.

Classe System.Web.Configuration.WebConfigurationManager

Fornece métodos úteis para obter referências para parâmetros de configuração de tempo de execução e de tempo de design.Esses métodos usam a classe System.Configuration.Configuration como um tipo de retorno.Você pode usar o método estático GetSection dessa classe ou o método não estático GetSection da classe System.Configuration.ConfigurationManager alternadamente.Para obter mais informações, consulte a seção anterior contida neste tópico Trabalhando com Métodos Estáticos e Não Estáticos.

Para configurações do aplicativo Web, nós recomendamos usar a classe System.Web.Configuration.WebConfigurationManager e não a classe System.Configuration.ConfigurationManager.

Namespace System.Configuration.Provider

Fornece uma maneira de personalizar e estender o provedor de configuração.Esta é a classe base para todas as classes do fornecedor no sistema de configuração.

Namespace System.Web.Management

Contém classes e interfaces para gerenciar e monitorar a integridade dos aplicativos da Web.Estritamente falando, esse namespace não é considerado parte da API de configuração.Por exemplo, o rastreamento e o acionamento de evento é realizado pelas classes neste namespace.Para obter mais informações, consulte Depuração de Solução de Problemas no ASP.NET.

Namespace System.Management.Instrumentation

Fornece as classes necessárias para a instrumentação de aplicativos para expor sua informação e seus eventos de gerenciamento através da Instrumentação de Gerenciamento do Windows (WMI) para os consumidores em potencial.Monitoramento da integridade do ASP.NET usa WMI para entregar eventos.Estritamente falando, esse namespace não é considerado parte da API de configuração.

Configuração da Estrutura de Herança de Classe

O diagrama a seguir ilustra as relações de herança entre as classes no namespace System.Web.Configuration e as classes no namespace System.Configuration.Você pode usar esse diagrama para entender quais propriedades e métodos estão disponíveis para o objeto que atualmente foi instanciado e como obter mais informações.

Configuração da Estrutura Agregação de Classe

O diagrama a seguir ilustra as relações de agregação entre as classes no namespace System.Web.Configuration e as classes no namespace System.Configuration.Você pode usar esse diagrama para entender as classes que são instanciadas como objetos de outras classes.

Criando Ferramentas Especializadas

Você talvez precise permitir que vários administradores gerenciem recursos designados, como sites Web e aplicativos específicos, enquanto restringe as ações que esses administradores podem levar de outros recursos.Você pode desenvolver ferramentas de administração que usam a API de configuração do ASP.NET para expor somente os parâmetros de configuração que seus administradores precisam para realizar seu trabalho, enquanto nega acesso a outras configurações.Isso capacita seus administradores e ajuda a proteger seus recursos, eliminando a necessidade de acesso direto a arquivos de configuração.

Ferramentas para Vários Servidores

Se você gerenciar vários servidores, você talvez precise implantar e gerenciar os mesmos aplicativos ASP.NET em cada servidor.Por exemplo, gerenciar um Web farm pode englobar as seguintes tarefas:

  • Gravar um script que configura o mesmo aplicativo ASP.NET em um ou todos os servidores do Web farm.

  • Bloquear alguns dos arquivos que são usados para cada instância do aplicativo.

  • Automatizar uma auditoria que registra configurações de aplicativos implantados para garantir que a instalação em cada computador está configurada da mesma forma.

  • Editar uma alteração na configuração uma vez e, em seguida, aplicar a alteração a todas as instâncias do aplicativo, não importa onde eles estejam instalados.

Além disso, a API de configuração do ASP.NET oferece suporte a execução em lotes em vários servidores.

Criar e Gerenciar Configuração com Uma Ferramenta

Como um proprietário do site, você pode usar o snap-in MMC do ASP.NET para criar e gerenciar as configurações de aplicativos ASP.NET em um computador.O snap-in MMC do ASP.NET expõe a funcionalidade da API de configuração do ASP.NET através de uma interface gráfica do usuário.O snap-in MMC do ASP.NET fornece uma visão unificada de parâmetros de configuração de vários arquivos de configuração, como sessão, segurança, erros e rastreamento.Você pode alterar as configurações sem editar diretamente o XML nos arquivos de configuração.Para obter mais informações, consulte Snap-in do MMC do ASP.NET.

Consulte também

Tarefas

Como: Acessar definições de configuração do ASP.NET por programação

Como: Ler configurações do aplicativo do arquivo Web.config

Como: Ler as seqüências de conexão do arquivo Web.config

Conceitos

Usando as Classes de Configuração

Outros recursos

API de Configuração do ASP.NET