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 version 2.0:
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.
Reading You use the GetSection or GetSectionGroup method to read configuration information. The user or process that reads must have Read permissions on all of the configuration files in the hierarchy.
Note
If you use a static GetSection method that takes a path parameter, the path parameter must refer to the application in which the code is running. Otherwise, the parameter is ignored and the configuration information for the currently running application is returned.
Writing You use one of the Save methods to write configuration information. 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.
Note
To enable access to configuration settings on a remote computer, use the Aspnet_regiis command-line tool. For more information about this tool, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe). For information about creating and accessing custom configuration settings other than the intrinsic sections included in the .NET Framework, see ConfigurationSection.
Code Examples
From within an ASP.NET page, you could use the code that is shown in the following example in order 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 example shows 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" "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" />
<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" "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" />
<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 or namespace |
Description |
|---|---|
System.Configuration namespace |
Contains the main configuration classes for all .NET Framework applications. This includes the section handler classes for the .NET Framework client configuration sections defined at Configuration File Schema for the .NET Framework. Section handler classes are used to obtain configuration data for a section from methods, such as GetSection and GetSectionGroup. These two methods are non-static. For more information, see the Working with Static and Non-Static Methods section earlier in this topic. The ASP.NET section handler classes are contained in the System.Web.Configuration namespace. |
Represents a set of configuration data for a computer, application, Web directory, or other resource. An instance of the Configuration class corresponds to the merged configuration settings contained in the hierarchy. This class contains useful methods, such as GetSection and GetSectionGroup, for updating configuration settings and obtaining references to sections and section groups. These two methods are non-static. For more information, see the Working with Static and Non-Static Methods section earlier in this topic. This class is used as a return type for methods that obtain design-time configuration data, such as the methods of the WebConfigurationManager and ConfigurationManager classes. |
|
System.Web.Configuration namespace |
Contains the section handler classes for the ASP.NET configuration sections defined at ASP.NET Configuration Settings. Section handler classes are used to obtain configuration data for a section from methods, such as GetSection and GetSectionGroup. These two methods are static. For more information, see the Working with Static and Non-Static Methods section earlier in this topic. |
Provides useful methods for obtaining references to run-time and design-time configuration settings. These methods use the System.Configuration.Configuration class as a return type. You can use the static GetSection method of this class or the non-static GetSection method of the System.Configuration.ConfigurationManager class interchangeably. For more information, see the Working with Static and Non-Static Methods section earlier in this topic. For Web application configurations, we recommend using the System.Web.Configuration.WebConfigurationManager class and not the System.Configuration.ConfigurationManager class. |
|
System.Configuration.Provider namespace |
Provides a way to customize and extend the configuration provider. This is the base class for all provider classes in the configuration system. |
System.Web.Management namespace |
Contains classes and interfaces for managing and monitoring the health of Web applications. Strictly speaking, this namespace is not considered part of the configuration API. For example, tracing and event firing is accomplished by the classes in this namespace. For more information, see ASP.NET Troubleshooting and Debugging. |
System.Management.Instrumentation namespace |
Provides the classes necessary for the instrumentation of applications to expose their management information and events through Windows Management Instrumentation (WMI) to potential consumers. ASP.NET health monitoring uses WMI to deliver events. Strictly speaking, this namespace is not considered part of the configuration API. |
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.
.gif "Inheritance in the configuration classes")
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.
.gif "ASP .NET Configuration Diagram")
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