<%@ Page Language="C#" MasterPageFile="~/aspnet/section.master" %> <%@ Register TagPrefix=Acme Namespace=Acme %> <%@ Register TagPrefix="Acme" TagName="SourceRef" Src="~/util/SrcRef.ascx"%>

Using the Management API

ASP.NET 2.0 now includes a full configuration management API that enables you to navigate, read, and write application configuration. The management API has the following benefits:

Configuration settings are exposed as a set of strongly typed objects that you can easily program against.
The management API includes built-in support for configuration inheritance. At each level of the application hierarchy, the management API provides a readable view that represents the merged configuration settings that apply to that level. When you modify these settings, the API automatically "unmerges" these settings, calculating and writing out the correct set of overrides at that node.
You can easily navigate the configuration hierarchy of the entire application.
You can use the management API to read and write configuration settings of local and remote web applications.
New configuration sections written using the configuration API are automatically manageable through the configuration API.

To open a configuration file, you use one of several static members on the System.Configuration.ConfigurationManager or the System.Web.Configuration.WebConfigurationManager classes. Each of these members returns a System.Configuration.Configuration object representing the merged configuration settings for the corresponding level. The following are some examples:

1. Open machine.config on the local machine.
WebConfigurationManager.OpenMachineConfiguration()

2. Open root web.config on the local machine.
WebConfigurationManager.OpenWebConfiguration(null)

3. Open web.config for the application at the root of the default web site.
WebConfigurationManager.OpenWebConfiguration("/")

4. Open web.config for a subdirectory of the application found at /MyApp.
WebConfigurationManager.OpenWebConfiguration("/MyApp/subdir")

5. Open web.config for an application at the root of another site.
WebConfigurationManager.OpenWebConfiguration("/", "Another Site")

6. Open the <location> tag for a subdirectory at the application level.
WebConfigurationManager.OpenWebConfiguration("/", null, "/subdir")

7. Open machine.config on another computer, using credentials provided.
WebConfigurationManager.OpenMachineConfiguration(null, "remotemachine", "user", "password")

To open and read a configuration, you must have read privileges for the directory that contains the configuration, as well as all directories that are in the parent hierarchy (including machine.config). To write a configuration, you must also have write and create privileges for the directory that contains the configuration.

Examining Configuration Settings

The Configuration object contains a hierarchy of configuration sections and configuration section groups, corresponding to the hierarchy of sections and groups in the configuration file. To obtain the root of this hierarchy, you can call the Configuration.RootSectionGroup property. From this object, you can navigate the Sections collection, which contains all sections that are direct children of the section group, or the SectionGroups collection, which contain all section groups that are direct children. The collections returned contain all configuration sections and groups that are hierarchically inherited by the current level of configuration, and not just sections that are physically declared at the current level.

You can also access a section directly by calling the Configuration.GetSection method, passing in the path to the section required.

The following example opens the configuration file for its own root, and recursively enumerates all the section groups and sections.

Configuration sections are represented by the ConfigurationSection type. Each section returned is typically a strongly typed object that inherits from this type. The returned object includes all property values that are hiearchically inherited by the current level of configuration, and not just values that are declared at the current level.

All sections also allow you to read and write their raw XML. This is useful particularly for legacy third-party ASP.NET 1.x sections that do not support a strongly typed management API. The raw XML returned is for the current level only, and does not automatically reflect inherited settings.

The following example opens the configuration file for its own root, and displays strongly typed settings for the <pages> section, and the raw XML for the <appSettings> section. Note that all inherited values for the <pages> section are shown, even though the web.config for this application does not contain such a section.

Updating Configuration Settings

To update a configuration setting, you can simply set the corresponding property on a ConfigurationSection object, and then call the Save method on the Configuration object.

Although the ConfigurationSection object provides a merged view of settings hierarchically inherited by the current level of configuration, the management API keeps track of settings specifically applied at the current level. When you call Save, only these settings are physically written to the configuration file at the current level.

The following example modifies an application setting for the current application using the management API.

Encypting a Section

Some configuration sections may contain sensitive data such as usernames and passwords. Although ASP.NET configures IIS to prevent browser access to web.config files, it is nonetheless a good practice to never store such data as plain text in a configuration file. ASP.NET 2.0 now allows you to encrypt individual sections of a configuration file, so that they are virtually impossible to read using a text editor.

ASP.NET includes two built-in protected configuration providers: RSA and DPAPI The DPAPI provider uses a machine-specific key, so you must physically encrypt the configuration settings on each machine. The RSA provider, which is used by default, allows you the option to create an RSA key and install it on other machines, so that you can copy the same configuration file between these machines. In addition, you can install other protected configuration providers for use with the system.

Calls to the configuration management API can transparently work with encrypted sections, because the API automatically handles encryption and decryption. To programmatically set a configuration section to be encrypted, you can get the ConfigurationSection.SectionInformation property, and call the ProtectSection method, passing in the protection provider of your choice. To use the default provider, you can pass null or the empty string. The UnprotectSection method turns off encryption of a section.

The following example shows how sections can be programmatically encrypted, and how the configuration API automatically handles encrypted sections.

You can also use the aspnet_regiis command line tool to encrypt configuration sections. To see available encryption options, run this tool with the /? option. For details on how to run aspnet_regiis, see The ASPNET_REGIIS Tool.