Usando as Classes de Configuração
A maior parte do trabalho de configuração é feito com a classe Configuration.Essa classe representa configurações de computadores, aplicativos de cliente .NET, aplicativos ASP.NET, diretórios Web, e recursos que são armazenados em diretórios Web.
Em ASP.NET versão 2.0, você pode ganhar acesso à uma instância da classe Configuration utilizando os métodos do objeto WebConfigurationManager para obter uma seção de configuração.(Em aplicativos de clientes .NET Framework, você pode utilizar o objeto similar ConfigurationManager).Cada seção de configuração possui seu próprio tipo de objeto, que é lista como um manipulador de seções na tabela "Element Information" no tópico referente em Definições de configuração ASP.NET.Para um exemplo, consulte Como: Acessar definições de configuração do ASP.NET por programação.
As seções seguintes descrevem como utilizar as classes de configuração em cenários diferentes.Para um sumário das classes de configuração, consulte Visão Geral da API de Configuração do ASP.NET.
Todos os exemplos abaixo utilizam os métodos não estáticos Configuration.GetSection e Configuration.GetSectionGroup, através da criação de uma instância da classe System.Configuration.Configuration primeiro.Isso permite que você obtenha a informação de configuração de qualquer aplicativo.Se você irá obter informações de configuração do aplicativo no qual seu código reside, utilize métodos estáticos GetSection, que processam muito mais rápido.Para mais informações, consulte a seção "Trabalhando com Definições de Configurações Local e Remota" em Visão Geral da API de Configuração do ASP.NET.
Abrindo um Objeto de Configuração Mapeado para Definições de Configurações Globais
Para abrir um arquivo de configuração para uma configuração global, seu aplicativo chama o método estático OpenMachineConfiguration da classe WebConfigurationManager.No exemplo de código seguinte, o método OpenMachineConfiguration abre e retorna o objeto de configuração que corresponde ao arquivo Machine.config do .NET Framework 2.0.Outras versões desse método sobrescrito permitem que você especifique um local, um servidor remoto, ou informações do usuário.
' Obtains the machine configuration settings on the local machine.
Dim machineConfig As System.Configuration.Configuration
machineConfig = _
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration()
machineConfig.SaveAs("c:\machineConfig.xml")
// Obtains the machine configuration settings on the local machine.
System.Configuration.Configuration machineConfig =
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration();
machineConfig.SaveAs("c:\\machineConfig.xml");
A configuração API é específica para a versão.Portanto, não é possível abrir o arquivo Machine.config para uma versão do .NET Framework utilizando os métodos incluídos em outra versão do .NET Framework.
Privilégios Requeridos
Para abrir o arquivo de configuração de máquina, o aplicativo necessita de permissão de Leitura para o arquivo físico Machine.config.Para modificar a configuração de máquina, o aplicativo necessita de permissão de Escrita para o arquivo, e privilégios de Criação para o diretório de configuração do .NET Framework.
Abrindo um Objeto de Configuração Mapeado para Definições de Configuração Aplicativos Web
Para abrir o arquivo de configuração para um aplicativo Web, sua aplicação chama o método estático OpenWebConfiguration da classe WebConfigurationManager, passando o caminho relativo do diretório virtual Serviço de Informações da Internet (IIS) a ser aberto.
Os valores dos parâmetros de caminho podem ser obtidos do caminho de metadados do IIS do diretório que contém a configuração requerida.Por exemplo, se o caminho de metadados do IIS for W3SVC/1/Root/Temp, então o caminho será /Temp porque o site padrão é 1.
No exemplo de código seguinte, o método OpenWebConfiguration abre e retorna o objeto de configuração correspondente ao aplicativo Temp Web no site Web padrão.O objeto de configuração inclui as definições de configuração especificadas localmente no arquivo Web.config e herdadas das definições dos arquivos de configuração de seus pais, todo o caminho até o arquivo Machine.config.Outras versões deste método sobrescrito permitem que você especifique o Web site, a localização, um servidor remoto, e informações do usuário.
' Obtains the configuration settings for a Web application.
Dim webConfig As System.Configuration.Configuration
webConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
webConfig.SaveAs("c:\\webConfig.xml")
// Obtains the configuration settings for a Web application.
System.Configuration.Configuration webConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
webConfig.SaveAs("c:\\webConfig.xml");
É possível abrir um objeto System.Configuration.Configuration mesmo quando o arquivo físico Web.config não exista.Neste caso, a configuração retornada consiste inteiramente de definições que são herdas de arquivos de configuração na hierarquia.Para obter mais informações, consulte Cenários de configuração ASP.NET.
Privilégios Requeridos
Para abrir um arquivo de configuração Web, o aplicativo necessita de permissões de Leitura para o arquivo Web.config, e todos os seus arquivos pais na hierarquia.
Abrind um Objeto de Configuração Mapeado para uma Seção em um Arquivo de Configuração
Para obter configurações de informação de uma seção, seu aplicativo chama o método não estático GetSectionGroup da classe Configuration, passando o nome da seção.Para seções que estejam contidas em grupos de seção, você pode tanto usar um XPath para a seção (system.web/anonymousIdentification), ou obter um objeto de configuração que esteja mapeado para a seção do primeiro grupo.Para uma lista de nomes de seção, consulte Definições de configuração ASP.NET.
No exemplo de código seguinte, o método OpenWebConfiguration abre e retorna o objeto de configuração correspondente ao aplicativo Temp Web no site Web padrão, e então utiliza o objeto para obter uma referência ao grupo de seção system.web, que então é utilizado para obter uma referência para a seção anonymousIdentification.
' Obtains the configuration settings for the <anonymousIdentification> section.
Dim config As System.Configuration.Configuration
config = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
Dim systemWeb As System.Web.Configuration.SystemWebSectionGroup
systemWeb = config.GetSectionGroup("system.web")
Dim sectionConfig As System.Web.Configuration.AnonymousIdentificationSection
sectionConfig = systemWeb.AnonymousIdentification
Dim sb As New StringBuilder
sb.AppendLine("<anonymousIdentification> attributes:")
Dim props As System.Configuration.PropertyInformationCollection
props = sectionConfig.ElementInformation.Properties
For Each prop As System.Configuration.PropertyInformation In props
sb.Append(prop.Name.ToString())
sb.Append(" = ")
sb.AppendLine(prop.Value.ToString())
Next
Console.WriteLine(sb.ToString())
// Obtains the configuration settings for the <anonymousIdentification> section.
System.Configuration.Configuration config =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
System.Web.Configuration.SystemWebSectionGroup systemWeb =
config.GetSectionGroup("system.web")
as System.Web.Configuration.SystemWebSectionGroup;
System.Web.Configuration.AnonymousIdentificationSection sectionConfig =
systemWeb.AnonymousIdentification;
if (null != sectionConfig)
{
StringBuilder sb = new StringBuilder();
sb.Append("<anonymousIdentification> attributes:\r\n");
System.Configuration.PropertyInformationCollection props =
sectionConfig.ElementInformation.Properties;
foreach (System.Configuration.PropertyInformation prop in props)
{
sb.AppendFormat("{0} = {1}\r\n", prop.Name.ToString(), prop.Value.ToString());
}
Console.WriteLine(sb.ToString());
}
É possível abrir um objeto System.Configuration.Configuration mesmo quando o arquivo físico Web.config não exista.Neste caso, a configuração retornada consiste inteiramente de definições que são herdas de arquivos de configuração na hierarquia.Para obter mais informações, consulte Cenários de configuração ASP.NET.
Privilégios Requeridos
Para abrir uma seção no arquivo de configuração Web, a aplicação necessita permissão de Leitura para o arquivo físico Web.config, e para todos os arquivos pai no diretório.Aplicações gerenciadas de código necessitam de ter permissão para leitura de seções do sistema.Aplicativos de Confiança Total e Alta Confiança têm permissão por padrão.Em outras palavras, por padrão, aplicativos de média e baixa confiança não estão habilitados a seções de configuração de leitura.
Abrindo um Objeto de Configuração Mapeadas para Definições Remotas de Configuração
Você pode utilizar a configuração API para abrir a configuração de um computador remoto.O API pode abrir um arquivo de configuração de máquina de outro computador, ou o arquivo de configuração de aplicativo para quaisquer aplicativos IIS ou seus diretórios filho.
Para abrir um arquivo de configuração de máquina em outro computador, o aplicativo chama o método estático OpenMachineConfiguration, passando o nome de um servidor.
Para abrir o arquivo Web.config em outro computador, o aplicativo chama o método estático OpenWebConfiguration, passando o caminho relativo ao site para o objeto de configuração o identificador do site, e o nome do servidor.O objeto de configuração retornado inclui as definições de configuração que são especificadas localmente no arquivo Web.config e todas as definições herdadas dos arquivos de configuração pai todo o caminho de volta ao arquivo Machine.config.
Nomes de servidor são nomes de computador de rede Windows válidos.Esses nomes não são manipulados especialmente através do ASP.NET mas são passados diretamente ao sistema operacional.
O exemplo de código seguinte mostra como abrir uma configuração de máquina, a configuração raiz em um site padrão, e a configuração Web em um diretório de aplicativo.
Dim userToken As IntPtr
userToken = System.Security.Principal.WindowsIdentity.GetCurrent().Token
' Obtains the machine configuration settings on a remote machine.
Dim remoteMachineConfig As System.Configuration.Configuration
remoteMachineConfig = _
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration( _
Nothing, "JanetFi2", userToken)
remoteMachineConfig.SaveAs("c:\remoteMachineConfig.xml")
' Obtains the root Web configuration settings on a remote machine.
Dim remoteRootConfig As System.Configuration.Configuration
remoteRootConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration( _
Nothing, Nothing, Nothing, "JanetFi2", userToken)
remoteRootConfig.SaveAs("c:\remoteRootConfig.xml")
' Obtains the configuration settings for the
' W3SVC/1/Root/Temp application on a remote machine.
Dim remoteWebConfig As System.Configuration.Configuration
remoteWebConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration( _
"/Temp", "1", Nothing, "JanetFi2", userToken)
remoteWebConfig.SaveAs("c:\\remoteWebConfig.xml")
IntPtr userToken = System.Security.Principal.WindowsIdentity.GetCurrent().Token;
// Obtains the machine configuration settings on a remote machine.
System.Configuration.Configuration remoteMachineConfig =
System.Web.Configuration.WebConfigurationManager.OpenMachineConfiguration
(null, "ServerName", userToken);
remoteMachineConfig.SaveAs("c:\\remoteMachineConfig.xml");
// Obtains the root Web configuration settings on a remote machine.
System.Configuration.Configuration remoteRootConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration
(null, null, null, "ServerName", userToken);
remoteRootConfig.SaveAs("c:\\remoteRootConfig.xml");
// Obtains the configuration settings for the
// W3SVC/1/Root/Temp application on a remote machine.
System.Configuration.Configuration remoteWebConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration
("/Temp", "1", null, "ServerName", userToken);
remoteWebConfig.SaveAs("c:\\remoteWebConfig.xml");
Privilégios Requeridos
Para abrir um arquivo de configuração em um computador remoto, o aplicativo deve ter permissões administrativas em um computador remoto.Esse requerimento é mais restrito que os requerimentos para uso local.Para arquivos de configuração local, o aplicativo necessita apenas de permissão de Leitura para os arquivos de configuração na hierarquia e para o metabase IIS (para gerar caminhos IIS).
Execute a ferramente Aspnet_regiis.exe com o parâmetro "-config+" no computador remoto antes de tentar configurá-lo.Para obter mais informações, consulte Ferramenta de registro ASP.NET IIS (Aspnet_regiis.exe).
Atualizando as Definições de Configurações
Para atualizar um objeto de configuração aberto, o aplicativo chama os métodos Save ou SaveAs do objeto de configuração.Esses métodos escrevem quaisquer mudanças de definição de configuração para aquele objeto.Se um arquivo de configuração não existir naquela localização, um novo arquivo de configuração é criado.
O exemplo de código seguinte define o atributo debug da seção compilação para true.
' Updates the configuration settings for a Web application.
Dim updateWebConfig As System.Configuration.Configuration
updateWebConfig = _
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp")
Dim compilation As System.Web.Configuration.CompilationSection
compilation = _
updateWebConfig.GetSection("system.web/compilation")
Console.WriteLine("Current <compilation> debug = {0}", compilation.Debug)
compilation.Debug = True
If Not compilation.SectionInformation.IsLocked Then
updateWebConfig.Save()
Console.WriteLine("New <compilation> debug = {0}", compilation.Debug)
Else
Console.WriteLine("Could not save configuration.")
End If
// Updates the configuration settings for a Web application.
System.Configuration.Configuration updateWebConfig =
System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("/Temp");
System.Web.Configuration.CompilationSection compilation =
updateWebConfig.GetSection("system.web/compilation")
as System.Web.Configuration.CompilationSection;
Console.WriteLine("Current <compilation> debug = {0}", compilation.Debug);
compilation.Debug = true;
if (!compilation.SectionInformation.IsLocked)
{
updateWebConfig.Save();
Console.WriteLine("New <compilation> debug = {0}", compilation.Debug);
}
else
{
Console.WriteLine("Could not save configuration.");
}
Atualmente, não há funcionalidade disponível para bloquear dados de configuração enquanto da atualização.Então, a configuração API, utiliza um modelo otimista de concorrência para modificar a configuração.Sob o modelo otimista de concorrência, se dois aplicativos abrir simultaneamente a mesma configuração, eles irão receber cópias únicas do objeto de configuração.Se algum aplicativo tentar modificar a configuração chamando os métodos Save ou SaveAs e o arquivo de configuração subsequente tiver sido modificado desde da obtenção do objeto de configuração, o método irá disparar uma exceção.O arquivo subsequente pode ter sido modificado por outro aplicativo durante a atualização, ou por outra modificação do arquivo independente da configuração API.
Privilégios Requeridos
Para modificar uma configuração Web, o aplicativo necessita de permissão de Escrita para o arquivo e privilégios de Criação para o diretório que contém o arquivo.
Consulte também
Conceitos
Visão Geral da API de Configuração do ASP.NET