ASP.NET Configuration API Overview

The ASP.NET configuration API allows you to develop, deploy, and manage application configuration data by using a single programming interface. You can use the configuration API to develop and modify complete ASP.NET configurations programmatically without directly editing the XML in the configuration files. In addition, you can use the configuration API in console applications and scripts that you develop, in Web-based management tools, and in Microsoft Management Console (MMC) snap-ins. The following two configuration-management tools use the configuration API and are included with the .NET Framework:

• The ASP.NET MMC snap-in, which uses the configuration API to simplify administrative tasks, providing an integrated view of local configuration data from all levels of the configuration hierarchy.

• The Web Site Administration Tool, which allows you to manage configuration settings for local and remote applications, including hosted sites.

The ASP.NET configuration API is separate from the Internet Information Services (IIS) programmatic configuration API. For more information, see Using IIS Programmatic Administration.

Configuration API Capabilities

The ASP.NET configuration API comprises a set of ASP.NET management objects that you can use to configure Web sites and applications programmatically. Management objects are implemented as a .NET Framework class library. The configuration API programming model helps ensure code consistency and reliability by enforcing data types at compile time.

To make it easier to manage application configurations, the configuration API allows you to view data that is merged from all points in the configuration hierarchy as a single collection, instead of viewing the data as separate collections from different configuration files. Additionally, the configuration API enables you to manipulate entire application configurations without directly editing the XML in the configuration files. Finally, the API simplifies configuration tasks by supporting administrative tools, such as the Web Site Administration Tool.

The configuration API simplifies deployment by supporting the creation of configuration files on a computer and running configuration scripts across multiple computers.

The configuration API does not support the creation of IIS applications. For information about writing administration applications for IIS, see Using System.DirectoryServices to Configure IIS in the IIS SDK.

Working with Local and Remote Configuration Settings

A Configuration object represents the merged view of the configuration settings that apply to a specific physical entity, such as a computer, or to a logical entity, such as an application or a Web site. The specified logical entity can exist on the local computer or on a remote server.

When no configuration file exists for a specified entity, the Configuration object represents the default configuration settings as defined by the Machine.config file.

You can get a Configuration object by using one of the open configuration methods from the following classes:

• The ConfigurationManager class, if your entity is a client application.

• The WebConfigurationManager class, if your entity is a Web application.

These methods will return a Configuration object, which in turn provides the required methods and properties to handle the underlying configuration files. You can access these files for reading or writing.

To read information, you use the GetSection or GetSectionGroup methods. The user or process that reads must have Read permissions on all of the configuration files in the hierarchy.

To write information, you use one of the Save methods. The user or process that writes must have Write permissions on the configuration file and directory at the current configuration hierarchy level, as well as Read permissions on all of the configuration files in the hierarchy.

To generate a configuration file that represents the inherited configuration settings for a specified entity, use one of the following save-configuration methods:

• The Save method to create a new configuration file.

• The SaveAs method to generate a new configuration file at another location.

Code Examples

From within an ASP.NET page, you could use the following code to obtain configuration information about the application in which the ASP.NET page runs. The following example shows a page named HandleAppSettings.aspx and the related code file. The page illustrates how to read and write the appSettings configuration section.

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

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

<html xmlns="https://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>

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Partial Public Class HandleAppSettings
  Inherits System.Web.UI.Page
  Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)

  End Sub
  ' Read the appSettings section.
  Protected Sub Button2_Click(ByVal sender As Object, ByVal e As EventArgs)
    Dim buffer As New System.Text.StringBuilder()
    Dim appSettings As System.Collections.Specialized.NameValueCollection = _
      System.Web.Configuration.WebConfigurationManager.AppSettings
    For i As Integer = 0 To appSettings.Count - 1
      Dim appEntry As String = _
        String.Format("#{0} Key: {1} Value: {2} <br/>", i, 
        appSettings.GetKey(i), appSettings(i))
        buffer.Append(appEntry)
    Next i
    Label1.Text = buffer.ToString()
  End Sub

  'Write AppSettings section.
  Protected Sub Button1_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' Get the application configuration file.
    Dim config As System.Configuration.Configuration = 
  System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("~/")
    ' Add an entry to the appSettings section.
    Dim appStgCnt As Integer =    
    System.Configuration.ConfigurationManager.AppSettings.Count
    Dim newKey As String = "NewKey" & appStgCnt.ToString()
    Dim newValue As String = Date.Now.ToLongDateString() & " " & 
      Date.Now.ToLongTimeString()
    ' Update the configuration file appSettings section.
    config.AppSettings.Settings.Add(newKey, newValue)
    ' Save the configuration file.
    config.Save(System.Configuration.ConfigurationSaveMode.Modified)
  End Sub
End Class

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://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();
    }
}

Configuration Classes and Namespaces

Many configuration classes and methods are similar to each other. The following table describes the most commonly used configuration classes and namespaces. For information about usage scenarios and code examples using these classes and namespaces, see Using the Configuration Classes.

Configuration Class Inheritance Structure

The following diagram illustrates the inheritance relationships between the classes in the System.Web.Configuration namespace and the classes in the System.Configuration namespace. You can use this diagram to understand what properties and methods are available to the object you currently have instantiated, and how to obtain further information.

Configuration Class Aggregation Structure

The following diagram illustrates the aggregation relationships between the classes in the System.Web.Configuration namespace and the classes in the System.Configuration namespace. You can use this diagram to understand the classes that are instantiated as objects within other classes.

Building Specialized Tools

You might need to allow many administrators to manage assigned resources, such as specific Web sites and applications, while restricting the actions that those administrators can take on other resources. You can develop administration tools that use the ASP.NET configuration API to expose only those configuration settings that your administrators require to do their work, while denying access to other settings. This empowers your administrators and helps protect your resources by eliminating the need for direct access to configuration files.

Tools for Multiple Servers

If you manage many servers, you might need to deploy and manage the same ASP.NET applications on each server. For example, managing a Web farm might entail the following tasks:

• Writing a script that configures the same ASP.NET application on any or all of the servers in the Web farm.

• Locking down some of the files that are used for each instance of the application.

• Automating an audit that records configurations of deployed applications to ensure that the installation on each computer is configured in the same way.

• Editing a change in configuration once, and then applying the change to all the instances of the application, wherever they are installed.

Additionally, the ASP.NET configuration API supports batch execution across multiple servers.

Create and Manage Configuration with One Tool

As a site owner, you can use the ASP.NET MMC snap-in to create and manage configurations of ASP.NET applications on a computer. The ASP.NET MMC snap-in exposes the functionality of the ASP.NET configuration API through a graphical user interface. The ASP.NET MMC snap-in provides a unified view of configuration settings from multiple configuration files, such as session, security, errors, and tracing. You can change settings without directly editing the XML in the configuration files. For more information, see MMC Snap-In for ASP.NET.

See Also

Tasks

How to: Access ASP.NET Configuration Settings Programmatically

How to: Read Application Settings from the Web.config File

How to: Read Connection Strings from the Web.config File

Concepts

Using the Configuration Classes

Other Resources

ASP.NET Configuration API