Esta documentación está archivada y no tiene mantenimiento.

ConfigurationManager (Clase)

Actualización: noviembre 2007

Proporciona acceso a los archivos de configuración para las aplicaciones cliente. Esta clase no se puede heredar.

Espacio de nombres:  System.Configuration
Ensamblado:  System.Configuration (en System.Configuration.dll)

public static class ConfigurationManager
public final class ConfigurationManager
public final class ConfigurationManager

La clase ConfigurationManager permite obtener acceso a la información de configuración de usuarios, aplicaciones y equipos. Esta clase reemplaza la clase ConfigurationSettings, que queda obsoleto.

ms134260.alert_note(es-es,VS.90).gifNota:

El nombre y ubicación del archivo de configuración de la aplicación dependen del host de la aplicación. Para obtener más información, vea Archivos de configuración de la aplicación.

Para controlar la información de configuración, se pueden utilizar los tipos System.Configuration integrados o derivados de ellos. El uso de estos tipos permite trabajar directamente con la información de configuración y ampliar los archivos de configuración de modo que incluyan la información personalizada.

La clase ConfigurationManager incluye miembros que permiten llevar a cabo las tareas siguientes:

  • Leer una sección de un archivo de configuración. Para obtener acceso a la información de configuración, llame al método GetSection. Para algunas secciones como appSettings y connectionStrings, utilice las clases de AppSettings y ConnectionStrings. Estos miembros llevan a cabo operaciones de sólo lectura, utilizan una única instancia almacenada en memoria caché de la configuración y reconocen los multiprocesos.

  • Leer y escribir totalmente archivos de configuración. La aplicación puede leer y escribir las opciones de configuración en cualquier nivel, para sí o para otras aplicaciones o equipos, de forma local o remota. Para abrir un archivo de configuración como SampleApp.exe.config, utilice uno de los métodos proporcionados por la clase ConfigurationManager. Estos métodos devuelven un objeto Configuration que, a su vez, expone métodos y propiedades que se pueden utilizar para trabajar con los archivos de configuración asociados. Los métodos llevan a cabo operaciones de lectura o escritura y crean los datos de configuración cada vez que se escribe en un archivo.

  • Compatibilizar tareas de configuración. Para compatibilizar las diversas tareas de configuración, se utilizan los tipos siguientes:

    Además de trabajar con la información de configuración existente, se pueden crear elementos de configuración personalizados, y trabajar con ellos, extendiendo los tipos de configuración integrados como las clases ConfigurationElement, ConfigurationElementCollection, ConfigurationProperty y ConfigurationSection. Para obtener un ejemplo sobre la forma de extender mediante programación un tipo de configuración integrado, vea ConfigurationSection. Para obtener un ejemplo de cómo extender un tipo de configuración integrado que utilice el modelo basado en atributos, vea ConfigurationElement.

Notas para los implementadores:

La clase Configuration permite el acceso mediante programación para modificar los archivos de configuración. Se utiliza uno de los métodos Open proporcionados por ConfigurationManager. Estos métodos devuelven un objeto Configuration que, a su vez, proporciona los métodos y propiedades necesarios para controlar los archivos de configuración subyacentes. Se puede obtener acceso de lectura o escritura a estos archivos.

Para leer los archivos de configuración, utilice GetSection o GetSectionGroup para leer la información de configuración. El usuario o el proceso que realice la lectura debe tener los permisos siguientes:

  • Permiso de lectura para el archivo de configuración del nivel de jerarquía de configuración actual.

  • Permisos de lectura para todos los archivos de configuración principal.

Si la aplicación necesita acceso de sólo lectura a su propia configuración, se recomienda utilizar el método GetSection. Este método proporciona acceso a los valores de configuración almacenados en memoria caché para la aplicación actual, lo que supone un rendimiento mejor que el de la clase Configuration.

Para escribir en los archivos de configuración, utilice uno de los métodos Save. El usuario o el proceso que realice la escritura debe tener los permisos siguientes:

  • Permiso de escritura para el directorio y el archivo de configuración del nivel de jerarquía de configuración actual.

  • Permisos de lectura para todos los archivos de configuración.

En el ejemplo siguiente se muestra cómo utilizar la clase ConfigurationManager en una aplicación de consola. El código muestra lo siguiente:

  • Cómo tener acceso a la sección de configuración appSettings. Si la sección no existe, se crea y agrega al archivo de configuración. El ejemplo crea el archivo de configuración de la aplicación si no existe.

  • Cómo tener acceso al archivo Machine.config para obtener información como la cadena de conexión predeterminada, si se ha definido, y las secciones que están configuradas actualmente.

    ms134260.alert_note(es-es,VS.90).gifNota:

    Al crear un proyecto, asegúrese de agregar una referencia al ensamblado System.Configuration. Este ensamblado contiene la clase ConfigurationManager.

Imports System
Imports System.Collections.Specialized
Imports System.Collections.ObjectModel
Imports System.Collections
Imports System.Text
Imports System.Configuration

Class UsingConfigurationManager


    ' Show how to use AppSettings.
    Shared Sub DisplayAppSettings()

        ' Get the AppSettings collection.
        Dim appSettings As NameValueCollection = _
        ConfigurationManager.AppSettings

        Dim keys As String() = appSettings.AllKeys

        Console.WriteLine()
        Console.WriteLine("Application appSettings:")

        ' Loop to get key/value pairs.
        Dim i As Integer
        For i = 0 To appSettings.Count - 1
            Console.WriteLine("#{0} Name: {1} Value: {2}", i, _
            keys(i), appSettings(i))
        Next i

    End Sub 'DisplayAppSettings

    ' Show how to use ConnectionStrings.
    ' This sub assumes that at least one connection string
    ' has been defined.
    Shared Sub DisplayConnectionStrings()

        ' Get the ConnectionStrings collection.
        Dim connections As ConnectionStringSettingsCollection = _
        ConfigurationManager.ConnectionStrings

        If connections.Count <> 0 Then
            Console.WriteLine("Connection strings:")
            ' Loop to get the collection elements.
            For Each connection As ConnectionStringSettings In connections
                Dim name As String = connection.Name
                Dim provider As String = connection.ProviderName
                Dim connectionString As String = connection.ConnectionString

                Console.WriteLine("Name:               {0}", name)
                Console.WriteLine("Connection string:  {0}", connectionString)
                Console.WriteLine("Provider:           {0}", provider)
            Next
        Else
            Console.WriteLine("No connection string is defined.")
        End If

    End Sub 'DisplayConnectionStrings

    ' Show how to use OpenMachineConfiguration.
    Shared Sub DisplayMachineConfigSections()
        ' Get the machine.config file.
        Dim machineConfig As Configuration = _
        ConfigurationManager.OpenMachineConfiguration()

        Dim sections As ConfigurationSectionCollection = _
        machineConfig.Sections

        Console.WriteLine()
        Console.WriteLine("Sections in machine.config:")

        ' Loop to get the sections machine.config.
        Dim section As ConfigurationSection
        For Each section In sections
            Dim name As String = section.SectionInformation.Name
            Console.WriteLine("Name: {0}", name)
        Next section

    End Sub 'DisplayMachineConfigSections


    ' Show how to use OpenExeConfiguration(ConfigurationUserLevel) 
    ' and RefreshSection. 
    ' This function creates a configuration file for the application, if one
    ' does not exist.
    Shared Sub UpdateAppSettings()
        ' Get the configuration file.
        Dim config As System.Configuration.Configuration = _
        ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None)

        ' Add an entry to appSettings.
        Dim appStgCnt As Integer = _
        ConfigurationManager.AppSettings.Count
        Dim newKey As String = "NewKey" + appStgCnt.ToString()

        Dim newValue As String = DateTime.Now.ToLongDateString() + " " + _
        DateTime.Now.ToLongTimeString()

        config.AppSettings.Settings.Add(newKey, newValue)

        ' Save the configuration file.
        config.Save(ConfigurationSaveMode.Modified)

        ' Force a reload of the changed section.
        ConfigurationManager.RefreshSection("appSettings")

    End Sub 'UpdateAppSettings

    ' Show how to use OpenExeConfiguration(string).
    Shared Sub DisplayAppSettingsRawXml()


        ' Get the application path.
        Dim exePath As String = System.IO.Path.Combine( _
        Environment.CurrentDirectory, "ConfigurationManager.exe")

        ' Get the configuration file.
        Dim config As System.Configuration.Configuration = _
        ConfigurationManager.OpenExeConfiguration(exePath)

        ' Get the AppSetins section.
        Dim appSettingSection As AppSettingsSection = _
        config.AppSettings

        ' Display raw xml.
        Console.WriteLine( _
        appSettingSection.SectionInformation.GetRawXml())

    End Sub 'DisplayAppSettingsRawXml


    ' Show how to use GetSection.
    Shared Sub DisplayAppSettingsSectionRawXml()

        ' Get the configuration file.
        Dim config As System.Configuration.Configuration = _
        ConfigurationManager.OpenExeConfiguration( _
        ConfigurationUserLevel.None)

        ' Get the AppSetins section.
        Dim appSettingSection As AppSettingsSection = _
        CType(config.GetSection("appSettings"), AppSettingsSection)

        ' Display raw xml.
        Console.WriteLine("appSettings XML:")
        Console.WriteLine(appSettingSection.SectionInformation.GetRawXml())

    End Sub 'DisplayAppSettingsSectionRawXml


    ' Show how to use OpenMappedMachineConfiguration.
    Shared Sub DisplayMappedMachineConfigurationFileSections()
        ' Get the machine.config file.
        Dim machineConfig As Configuration = _
        ConfigurationManager.OpenMachineConfiguration()

        ' Map to the machine configuration file.
        Dim configFile As New ConfigurationFileMap(machineConfig.FilePath)
        Dim config As Configuration = _
        ConfigurationManager.OpenMappedMachineConfiguration(configFile)

        ' Display the configuration file sections.
        Dim sections As ConfigurationSectionCollection = config.Sections

        Console.WriteLine()
        Console.WriteLine("Sections in machine.config:")

        ' Loop to get the sections machine.config.
        Dim section As ConfigurationSection
        For Each section In sections
            Dim name As String = section.SectionInformation.Name
            Console.WriteLine("Name: {0}", name)
        Next section

    End Sub 'DisplayMappedMachineConfigurationFileSections


    ' Show how to use OpenMappedExeConfiguration.
    Shared Sub DisplayMappedExeConfigurationFileSections()
        ' Get the application configuration file path.
        Dim exeFilePath As String = System.IO.Path.Combine( _
        Environment.CurrentDirectory, "ConfigurationManager.exe.config")

        ' Map to the application configuration file.
        Dim configFile As New ExeConfigurationFileMap()
        configFile.ExeConfigFilename = exeFilePath
        Dim config As Configuration = _
        ConfigurationManager.OpenMappedExeConfiguration(configFile, _
        ConfigurationUserLevel.None)

        ' Display the configuration file sections.
        Dim sections As ConfigurationSectionCollection = config.Sections

        Console.WriteLine()
        Console.WriteLine("Sections in machine.config:")

        ' Loop to get the sections machine.config.
        Dim section As ConfigurationSection
        For Each section In sections
            Dim name As String = section.SectionInformation.Name
            Console.WriteLine("Name: {0}", name)
        Next section

    End Sub 'DisplayMappedExeConfigurationFileSections

    Shared Sub Main(ByVal args() As String)

        ' Show how to use OpenExeConfiguration() and RefreshSection.
        UpdateAppSettings()

        ' Show how to use AppSettings.
        DisplayAppSettings()

        ' Show how to use OpenExeConfiguration(string).
        DisplayAppSettingsRawXml()

        ' Show how to use GetSection.
        DisplayAppSettingsSectionRawXml()

        ' Show how to use ConnectionStrings.
        DisplayConnectionStrings()

        ' Show how to use OpenMappedMachineConfiguration.
        DisplayMappedMachineConfigurationFileSections()

        ' Show how to use OpenMappedExeConfiguration.
        DisplayMappedExeConfigurationFileSections()

        ' Show how to use OpenMachineConfiguration.
        DisplayMachineConfigSections()

    End Sub 'Main 
End Class 'UsingConfigurationManager



El ejemplo funciona con los elementos que son similares a los mostrados en el archivo de configuración siguiente. Estos elementos se generan la primera vez que se ejecuta el ejemplo.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="NewKey0" value="Monday, January 23, 2006 2:56:14 PM" />
  </appSettings>
</configuration>

System.Object
  System.Configuration.ConfigurationManager

Todos los miembros static (Shared en Visual Basic) públicos de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

.NET Framework y .NET Compact Framework no admiten todas las versiones de cada plataforma. Para obtener una lista de las versiones compatibles, vea Requisitos de sistema de .NET Framework.

.NET Framework

Compatible con: 3.5, 3.0, 2.0
Mostrar: