Utilizar las clases Configuration
Actualización: noviembre 2007
La mayor parte del trabajo de configuración se realiza con la clase Configuration. Esta clase representa la configuración de equipos, aplicaciones de clientes .NET, aplicaciones ASP.NET, directorios Web y recursos que se almacenan en directorios Web.
En la versión 2.0 de ASP.NET, puede tener acceso a una instancia de la clase Configuration utilizando los métodos del objeto WebConfigurationManager para obtener una sección de configuración. (En las aplicaciones cliente .NET Framework, puede utilizar un objeto similar ConfigurationManager). Cada sección de configuración tiene su propio tipo de objeto, que aparece en la lista como el controlador de sección en la tabla "Información de elementos" en los temas de referencia en Opciones de configuración de ASP.NET. Para obtener un ejemplo, vea Cómo: Tener acceso a las opciones de configuración de ASP.NET mediante programación.
Las siguientes secciones describen cómo utilizar las clases de configuración en diferentes escenarios. Para obtener un resumen de las clases de configuración, vea Información general sobre la API de configuración de ASP.NET.
Todos los ejemplos siguientes utilizan los métodos Configuration.GetSection y Configuration.GetSectionGroup no estáticos creando primero una instancia de la claseSystem.Configuration.Configuration. Esto permite obtener información sobre la configuración desde cualquier aplicación. Si va a obtener información de configuración de la aplicación en la que reside el código, utilice los métodos estáticos GetSection que procesan con más rapidez. Para obtener más información, vea la sección "Trabajar con valores de configuración local y remota" en Información general sobre la API de configuración de ASP.NET.
Abrir un objeto de configuración asignado a los valores de configuración global
Para abrir un archivo de configuración para configuración global, su aplicación llama al método OpenMachineConfiguration estático de la clase WebConfigurationManager. En el siguiente ejemplo de código, el método OpenMachineConfiguration abre y devuelve el objeto de configuración que corresponde al archivo Machine.config de la versión 2.0 de .NET Framework. Otras versiones de este método sobrecargado permiten especificar una ubicación, un servidor remoto o información de usuario.
' 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");
La configuración API es específica de la versión. Por lo tanto, no es posible abrir el archivo Machine.config para una versión de .NET Framework utilizando los métodos incluidos en otra versión de .NET Framework.
Privilegios necesarios
Para abrir el archivo de configuración del equipo, la aplicación necesita permiso de Lectura para el archivo físico Machine.config. Para modificar la configuración del equipo, la aplicación necesita permiso de Escritura para el archivo y privilegios de Creación para el directorio de configuración de .NET Framework.
Abrir un objeto de configuración asignado a los valores de configuración de una aplicación Web
Para abrir el archivo de configuración para una aplicación Web, la aplicación llama al método estático OpenWebConfiguration de la clase WebConfigurationManager, pasando la ruta de acceso relativa del directorio virtual de los Servicios de Internet Information Server (IIS) que debe abrirse.
Los valores del parámetro de ruta de acceso pueden obtenerse de la ruta de metabase de IIS del directorio que contiene la configuración necesaria. Por ejemplo, si la ruta de acceso de metabase de IIS es W3SVC/1/Root/Temp, entonces la ruta es /Temp porque el sitio predeterminado es 1.
En el siguiente ejemplo de código, el método OpenWebConfiguration abre y devuelve el objeto de configuración que corresponde a la aplicación Web Temp en el sitio Web predeterminado. El objeto de configuración incluye los valores de configuración que se especifican localmente en un archivo Web.config y todos los valores heredados de archivos de configuración principales que se remontan al archivo Machine.config. Otras versiones de este método sobrecargado permiten especificar el sitio Web, una ubicación, un servidor remoto e información de usuario.
' 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");
Es posible abrir un objeto System.Configuration.Configuration aunque no exista un archivo físico Web.config. En este caso, la configuración devuelta está formada totalmente por valores que se han heredado de la jerarquía del archivo de configuración. Para obtener más información, vea Escenarios de configuración de ASP.NET.
Privilegios necesarios
Para abrir un archivo de configuración Web, la aplicación necesita permiso de Lectura para el archivo físico Web.config y para todos sus archivos principales en la jerarquía.
Abrir un objeto de configuración asignado a una sección de un archivo de configuración
Para obtener información sobre la configuración de una sección, su aplicación llama al método GetSectionGroup no estático de la clase Configuration, pasando el nombre de la sección. Para las secciones que pertenecen a grupos de secciones, se puede utilizar un XPath a la sección (system.web/anonymousIdentification), u obtener un objeto de configuración que esté asignado primero al grupo de sección. Para obtener una lista de nombres de sección, vea Opciones de configuración de ASP.NET.
En el siguiente ejemplo de código, el método OpenWebConfiguration abre y devuelve el objeto de configuración que corresponde a la aplicación Web Temp en el sitio Web predeterminado y, después, utiliza dicho objeto para obtener una referencia al grupo de sección system.web, que se utiliza para obtener una referencia a la secciónanonymousIdentification.
' 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());
}
Es posible abrir un objeto System.Configuration.Configuration aunque no exista un archivo físico Web.config. En este caso, la configuración devuelta está formada totalmente por valores que se han heredado de la jerarquía del archivo de configuración. Para obtener más información, vea Escenarios de configuración de ASP.NET.
Privilegios necesarios
Para abrir una sección en un archivo de configuración Web, la aplicación necesita permiso de Lectura para el archivo físico Web.config y para todos sus archivos principales en la jerarquía. Las aplicaciones de código administrado necesitan tener permiso para leer las secciones del sistema. Las aplicaciones de plena confianza y de gran confianza tienen estos permisos de forma predeterminada. En otras palabras, de forma predeterminada, las aplicaciones de media y baja confianza no podrán leer secciones de configuración.
Abrir un objeto de configuración asignado a los valores de configuración remota
Puede utilizar la configuración de API para abrir la configuración de un equipo remoto. La API puede abrir el archivo de configuración del equipo de otro equipo o el archivo de configuración de la aplicación para cualquier aplicación de IIS o sus directorios secundarios.
Para abrir un archivo de configuración del equipo en otro equipo, la aplicación llama al método estático OpenMachineConfiguration, pasando el nombre del servidor.
Para abrir un archivo Web.config en otro equipo, la aplicación llama al método estático OpenWebConfiguration, pasando la ruta de acceso relativa al sitio del objeto de configuración, el identificador del sitio y el nombre del servidor. El objeto de configuración devuelto incluye los valores de configuración que se especifican localmente en un archivo Web.config y todos los valores heredados de archivos de configuración principales que se remontan al archivo Machine.config.
Los nombres de los servidores son nombres válidos de equipos de red de Windows. ASP.NET no controla de forma especial estos nombres pero pasan directamente al sistema operativo.
En el siguiente ejemplo de código se muestra cómo abrir una configuración de equipo, la configuración raíz en un sitio predeterminado y una configuración Web en un directorio de aplicación.
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");
Privilegios necesarios
Para abrir un archivo de configuración en un equipo remoto, la aplicación debe tener permisos administrativos en el equipo remoto. Este requisito es más restrictivo que el requisito para uso local. Para los archivos de configuración local, la aplicación sólo necesita permiso de Lectura para los archivos de configuración en la jerarquía y para la metabase de IIS (para resolver rutas de acceso de IIS).
Ejecute la herramienta Aspnet_regiis.exe con el parámetro "-config+" en el equipo remoto antes de intentar configurarlo. Para obtener más información, vea Herramienta Registro de IIS en ASP.NET (Aspnet_regiis.exe).
Actualizar valores de configuración
Para actualizar un objeto de configuración abierto, la aplicación llama al método Save o SaveAs del objeto de configuración. Estos métodos escriben los cambios de los valores de configuración para dicho objeto. Si un archivo de configuración no existe en la ubicación, se crea un nuevo archivo de configuración.
El siguiente ejemplo de código establece el atributo debug de la sección compilación como 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.");
}
Actualmente, no existe ninguna funcionalidad disponible para bloquear los datos de configuración durante su actualización. Por tanto, la API de configuración API utiliza un modelo de concurrencia optimista para modificar la configuración. Bajo el modelo de concurrencia optimista, si dos aplicaciones abren de forma simultánea la misma configuración, obtendrán copias únicas del objeto de configuración. Si una aplicación intenta modificar la configuración llamando a los métodos Save o SaveAs y se ha modificado el archivo de configuración subyacente desde que la aplicación obtuvo el objeto de configuración, el método provocará una excepción. Es posible que el archivo subyacente haya sido modificado por otra aplicación que esté actualizando la configuración o por algún otro cambio en el archivo independiente de la API de configuración.
Privilegios necesarios
Para modificar la configuración Web, la aplicación necesita permiso de Escritura para el archivo y privilegios de Creación para el directorio que contiene el archivo.
Vea también
Conceptos
Información general sobre la API de configuración de ASP.NET