Información general sobre la API de configuración de ASP.NET

La API de configuración de ASP.NET comprende un conjunto de objetos de administración de ASP.NET que puede utilizar para configurar mediante programación sitios Web y aplicaciones. Los objetos de administración se implementan como una biblioteca de clases de .NET Framework. El modelo de programación de la API de configuración ayuda a garantizar la coherencia y la fiabilidad del código aplicando los tipos de datos en tiempo de compilación.

Para facilitar la administración de las configuraciones de aplicación, la API de configuración permite ver los datos que se combinan desde todos los puntos de la jerarquía de configuración como una colección única, en lugar de ver los datos como colecciones individuales de distintos archivos de configuración. Además, la API de configuración permite manipular las configuraciones de aplicación completas sin editar directamente el XML en los archivos de configuración. Por último, la API simplifica las tareas de configuración al admitir herramientas administrativas, como la herramienta Administración de sitios Web.

La API de configuración simplifica la implementación al admitir la creación de archivos de configuración en un equipo y ejecutar scripts de configuración en varios equipos.

La API de configuración no admite la creación de aplicaciones IIS. Para obtener información sobre cómo escribir aplicaciones de administración para IIS, vea Using System.DirectoryServices to Configure IIS en el SDK de IIS.

Un objeto Configuration representa la vista combinada de las opciones de configuración que se aplican a una entidad física específica, como un equipo, o a una entidad lógica, como una aplicación o sitio Web. La entidad lógica especificada puede existir en el equipo local o en un servidor remoto.

Cuando no existen archivos de configuración para una entidad especificada, el objeto Configuration representa las opciones de configuración predeterminadas tal se se definen en el archivo Machine.config.

Puede obtener un objeto Configuration utilizando uno de los métodos de configuración abiertos de las clases siguientes:

• La clase ConfigurationManager, si la entidad es una aplicación de cliente.

• La clase WebConfigurationManager, si la entidad es una aplicación Web.

Estos métodos devolverán un objeto Configuration, que a su vez proporciona los métodos y propiedades necesarios para controlar los archivos de configuración subyacentes. Puede tener acceso de lectura o escritura a estos archivos.

Para leer información, se utilizan los métodos GetSectionGroup o GetSection. El usuario o el proceso que lee debe tener permisos de lectura en todos los archivos de configuración de la jerarquía.

Nota
Si utiliza un método GetSection estático que acepta un parámetro path, el parámetro path debe hacer referencia a la aplicación en la que se ejecuta el código. De lo contrario, se omite el parámetro y se devuelve la información de configuración para la aplicación que está actualmente en ejecución.

Para escribir información, puede usar uno de los métodos Save(ConfigurationSaveMode). El usuario o el proceso que escribe debe tener permisos de escritura en el archivo y el directorio de configuración en el nivel de jerarquía de configuración actual, así como permisos de lectura en todos los archivos de configuración de la jerarquía.

Para generar un archivo de configuración que representa las opciones de configuración heredadas para una entidad especificada, utilice uno de los siguientes métodos de configuración de guardado:

• El método Save(ConfigurationSaveMode), para crear un nuevo archivo de configuración.

• El método SaveAs(String, ConfigurationSaveMode) para generar un nuevo archivo de configuración en otra ubicación.

Nota

Para permitir el acceso a los valores de configuración en un equipo remoto, utilice la herramienta de línea de comandos Aspnet_regiis. Para obtener más información sobre esta herramienta, vea Herramienta Registro de IIS en ASP.NET (Aspnet_regiis.exe). Para obtener información sobre cómo crear y tener acceso a opciones de configuración personalizadas distintas de las secciones intrínsecas incluidas en .NET Framework, vea ConfigurationSection.

Ejemplos de código

<%@ Page Language="VB" AutoEventWireup="false" CodeFile="HandleAppSettings.aspx.vb" Inherits="HandleAppSettings" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
     <title>Handle Application Settings</title>
</head>
<body>
  <form id="form1" runat="server">
    <h2>Handle Application Settings</h2>
    <asp:Label ID="Label1" Text="[Application Settings go here.]" 
      runat="server"></asp:Label>
    <hr />
   <asp:Button ID="Button1" runat="server" onclick="Button1_Click" 
     Text="Write AppSettings" /> &nbsp; &nbsp;
   <asp:Button ID="Button2" runat="server" onclick="Button2_Click" Text="Read 
      AppSettings" />
  </form>
</body>
</html>

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="HandleAppSettings.aspx.cs" Inherits="HandleAppSettings" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Application Settings</title>
</head>
<body>
    <form id="form1" runat="server">
        <h2>Application Settings</h2>
        <asp:Label ID="Label1" Text="[Application Settings go here.]" 
          runat="server"></asp:Label>
        <hr />
       <asp:Button ID="Button1" runat="server" onclick="Button1_Click" 
          Text="Write AppSettings" /> &nbsp; &nbsp;
       <asp:Button ID="Button2" runat="server" onclick="Button2_Click"     
          Text="Read AppSettings" />
    </form>
</body>
</html>

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

public partial class HandleAppSettings : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
    }
    
    protected void Button1_Click(object sender, EventArgs e)
    {
        // Get the application configuration file.
        System.Configuration.Configuration config =
          System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("~/");
          
        // Add an entry to the appSettings section.
        int appStgCnt =
            System.Configuration.ConfigurationManager.AppSettings.Count;
        string newKey = "NewKey" + appStgCnt.ToString();

        string newValue = DateTime.Now.ToLongDateString() +
          " " + DateTime.Now.ToLongTimeString();

        // Update the configuration file appSettings section.
        config.AppSettings.Settings.Add(newKey, newValue);

        // Save the configuration file.
        config.Save(System.Configuration.ConfigurationSaveMode.Modified);

    }

    protected void Button2_Click(object sender, EventArgs e)
    {
        // Read the appSettings section.
        System.Text.StringBuilder buffer = new System.Text.StringBuilder();
        System.Collections.Specialized.NameValueCollection appSettings =
           System.Web.Configuration.WebConfigurationManager.AppSettings;
        for (int i = 0; i < appSettings.Count; i++)
        {
            string appEntry = String.Format("#{0} Key: {1} Value: {2} <br/>",
            i, appSettings.GetKey(i), appSettings[i]);
            buffer.Append(appEntry);
        }
        Label1.Text = buffer.ToString();
    }
}

Numerosas clases y métodos de configuración son similares entre sí. La tabla siguiente describe las clases de configuración y los espacios de nombres que más se utilizan. Para obtener información sobre escenarios de uso y ejemplos de código que utilizan estas clases y espacios de nombres, vea Utilizar las clases Configuration.

Estructura de herencia de clases de configuración

El diagrama siguiente muestra las relaciones de herencia entre las clases en el espacio de nombres System.Web.Configuration y las clases en el espacio de nombres System.Configuration. Puede utilizar este diagrama para entender las propiedades y métodos que están disponibles para el objeto del que ha creado actualmente una instancia y para obtener más información.

Estructura de agregación de clases de configuración

El diagrama siguiente muestra las relaciones de herencia entre las clases en el espacio de nombres System.Web.Configuration y las clases en el espacio de nombres System.Configuration. Puede utilizar este diagrama para entender las clases de las que se crean instancias como objetos dentro de otras clases.

Es posible que deba permitir a muchos administradores administrar recursos asignados, como sitios Web y aplicaciones específicos, a la vez que limitar las acciones que estos administradores puedan realizar en otros recursos. Puede desarrollar herramientas de administración que utilizan la API de configuración de ASP.NET para exponer sólo aquellas opciones de configuración que los administradores necesitan para realizar su trabajo, a la vez que se niega el acceso a otras opciones. Esto da autoridad a los administradores y ayuda a proteger los recursos eliminando la necesidad de un acceso directo a los archivos de configuración.

Herramientas para varios servidores

Crear y administrar la configuración con una herramienta

Tareas

Conceptos

Otros recursos