Using the Configuration API
| The Configuration API enables you to retrieve and modify configuration settings. You can use the Configuration API to modify web configuration files on the local machine or a remote machine. If you are responsible for maintaining a large number of websites, the Configuration API can make your life much easier. You can build administrative tools that enable you to make configuration changes quickly to multiple applications. You can use the Configuration API in an ASP.NET page, or you can build command-line tools or Windows Forms applications that use the Configuration API. The Configuration API is exposed by the WebConfigurationManager class (located in the System.Web.Configuration namespace). This class supports the following properties:
The WebConfigurationManager also supports the following methods:
Almost every configuration section in the web configuration file has a corresponding class in the .NET Framework that represents the configuration section. These classes provide you with a strongly typed representation of each configuration section. For example, corresponding to the <authentication> section in the web configuration file, there is a System.Web.Configuration.AuthenticationSection class. Corresponding to the <pages> section in the web configuration file, there is a System.Web.Configuration.PagesSection class. Each of these classes expose properties that correspond to all the attributes you can set in the web configuration file. Reading Configuration Sections from the Current ApplicationWhen an ASP.NET application starts, the application merges all the configuration settings in the configuration hierarchy to create one representation of the configuration settings. A particular configuration setting might have different values at different levels in the hierarchy. You can use the methods of the WebConfigurationManager class to get the value of a configuration setting at any level in the hierarchy. The WebConfigurationManager.GetWebApplicationSection() method always retrieves a configuration setting from the application root Web.config file. For example, the page in Listing 26.8 displays whether debugging is enabled. Listing 26.8. ShowConfigApp.aspx
The GetWebApplication() method returns an object. You must cast the value returned by this method to a particular configuration section type. In Listing 26.8, the value returned by this method is cast to an instance of the CompilationSection type. Realize that you will get the same result when the page in Listing 26.8 is located in different subfolders. For example, debugging might not be enabled in a root configuration file, but it might be enabled in a configuration file in a particular subfolder. However, if you call the GetWebApplicationSection() method, the method always returns the configuration setting for the application root Web.config file. If you want to get the value of a configuration setting relative to the folder in which the page executes, then you can use the GetSection() method instead of the GetWebApplicationSection() method. The page in Listing 26.9 is located in a subfolder. The page displays the value of the debug setting retrieved from both the GetWebApplicationSection() method and the GetSection() method (see Figure 26.5). Figure 26.5. Retrieving a configuration setting with the GetSection() and GetWebApplicationSection() methods. Listing 26.9. SubFolder\ShowConfigRelative.aspx
When you request the page in Listing 26.9, different values are displayed by the GetSection() method and GetWebApplicationSection() method. The method displays the configuration setting relative to the current directory. The second method displays the configuration setting from the application root Web.config file. If you want to retrieve the value of a configuration setting for a particular path, then you can use the overload of the GetSection() method that accepts a path parameter. The page in Listing 26.10 iterates through all the immediate subfolders contained in the current application and displays whether debugging is enabled (see Figure 26.6). Figure 26.6. Displaying configuration settings for each subfolder in an application. Listing 26.10. ShowConfigPath.aspx
Opening a Configuration FileIf you want to open a particular configuration file, then you can use one of the Open methods exposed by the WebConfigurationManager class. For example, the page in Listing 26.11 uses the OpenMachineConfiguration() method to open the Machine.config file and display the default value for the authentication mode setting. Listing 26.11. ShowConfigMachine.aspx
You can use the WebConfigurationManager class to display configuration information for other websites located on the same server. For example, the page in Listing 26.12 displays a list of all the virtual directories contained in the default website. You can select a virtual directory and view the authentication mode associated with the virtual directory (see Figure 26.7). Figure 26.7. Displaying configuration information for any application hosted on a server. Listing 26.12. ShowConfigSites.aspx
The list of virtual directories is retrieved with the classes from the System.DirectoryServices namespace. When you select a virtual directory, the OpenWebConfiguration() method is called with the path to the virtual directory to get the configuration information. Warning Before you can use the classes from the System.DirectoryServices namespace, you must add a reference to the System.DirectoryServices.dll assembly. In Visual Web Developer, select the menu option Website, Add Reference. Opening a Configuration File on a Remote ServerYou can use the WebConfigurationManager class to open Machine.config or Web.config files located on remote web servers. However, before you can do this, you must perform one configuration step. You must enable the remote server to accept remote configuration connections by executing the following command from a command prompt: aspnet_regiis -config+ To disable remove configuration connections, execute the following command: aspnet_regiis -config- The aspnet_regiis tool is located in the following path: \WINDOWS\Microsoft.NET\Framework\[version]\aspnet_regiis.exe Note If you open the SDK Command Prompt, then you don't need to navigate to the Microsoft.NET folder to execute the aspnet_regiis tool. After you make this modification to a remote server, you can retrieve (and modify) configuration settings on the remote server by using one of the Open methods exposed by the WebConfigurationManager class. For example, the page in Listing 26.13 contains a form that enables you to enter a server, username, and password. When you submit the form, the page connects to the remote server and retrieves its Machine.config file. The page displays the current value of the remote server's authentication mode (see Figure 26.8). Figure 26.8. Changing configuration settings for a remote server. Listing 26.13. ShowConfigRemote.aspx
You can use the page in Listing 26.13 even when the web server is located in some distant part of the Internet. You can enter a domain name or IP address in the server field. Using the Configuration ClassWhen you use one of the WebConfigurationManager Open methodssuch as the OpenMachineConfiguration() or OpenWebConfiguration() methodsthe method returns an instance of the Configuration class. This class supports the following properties:
The Configuration class also supports the following methods:
A configuration file contains two basic types of entities: section groups and sections. For example, the <system.web> element in a configuration file represents a section group. The <system.web> section group contains child sections such as the <authentication> and <httpRuntime> sections. You can use the Configuration.RootSectionGroup property to get the primary section group in a configuration file. You can use the SectionGroups property to return all of a section group's child section groups and the Sections property to return all of a section group's child sections. For example, the page in Listing 26.14 recursively displays the contents of the Machine.config file in a treeView control (see Figure 26.9). Figure 26.9. Displaying all configuration sections from the system.web configuration section group. Listing 26.14. ShowConfigContents.aspx
Modifying Configuration SectionsYou can use the WebConfigurationManager class not only when opening a configuration file to read the values of various configuration settings. You also can use the WebConfigurationManager class to modify existing configuration settings or add new ones. The Configuration class supports two methods for saving configuration information: the Save() and SaveAs() methods. For example, the page in Listing 26.15 enables you to turn on and off debugging for an application (see Figure 26.10). Figure 26.10. Modifying the value of the Debug configuration setting. Listing 26.15. ShowConfigModify.aspx
The page in Listing 26.15 loads the application root Web.config file with the help of the OpenWebConfiguration() method (the Nothing parameter causes the root Web.config file to be loaded). Next, the value of the Compilation.Debug property is modified. Finally, the Save() method is called to save this change. When you call the Save() method, you can pass a ConfigurationSaveMode parameter to the method. This parameter can have the following values:
To use the Save() or SaveAs() methods, the account associated with the page must have Write permissions for the folder where the configuration file is saved. By default, when pages are served from Internet Information Server, ASP.NET pages execute in the security context of the NETWORK SERVICE account (in the case of Windows Server 2003) or the ASPNET account (in the case of other operating systems). By default, neither of these accounts have permissions to save configuration changes. Note To make things more confusing, when pages are served from the web server included with Visual Web Developer, the pages are always served in the security context of the current user. There are multiple ways that you can get around this permission problem. First, remember that you can use many of the methods of the WebConfigurationManager class from a console application or a Windows Forms application. If you build this type of application, then you can sidestep these security issues. Another option is to enable per-request impersonation for your ASP.NET application. When impersonation is enabled, an ASP.NET page executes within the security context of the user making the page request. If the user account has permissions to write to the file system, then the page has permissions to write to the file system. The web configuration file in Listing 26.16 enables impersonation. Listing 26.16. Web.config
If you add the configuration file in Listing 26.16 to the same folder that contains the file in Listing 26.15, then you will be able to make modifications to configuration files. Warning Most changes to a configuration file result in an application restart. When an ASP.NET application restarts, all data stored in memory is blown away. For example, all data cached in the Cache object or Session state is lost. Provisioning a New WebsiteWhen you are provisioning new websites, you often need to create a new virtual directory. The Configuration API doesn't provide you with any help here. However, you can create new virtual directories (and applications) by taking advantage of the classes in the System.DirectoryServices namespace. These classes enable you to use Active Directory Services Interface (ADSI) to modify properties of Internet Information Server. Note You also can manipulate Internet Information Server properties by using Windows Management Instrumentation (WMI). For more information, see the topic "Using WMI to Configure IIS" at the Microsoft MSDN website (msdn.microsoft.com). Before you can use the classes from the System.DirectoryServices namespace, you need to add a reference to the System.DirectoryServices.dll assembly. In Visual Web Developer, select the menu option Website, Add Reference, and select System.DirectoryServices.dll. For example, the page in Listing 26.17 enables you to provision a new ASP.NET application (see Figure 26.11). The page creates a new virtual directory and a new application. The page also creates a new web configuration file in the virtual directory that contains the default language and debug settings you specify. Figure 26.11. Creating a new ASP.NET application. Listing 26.17. ProvisionSite.aspx
To use the page in Listing 26.17, you'll need adequate permissions. You can enable per-request impersonation by adding the file in Listing 26.16 to the same folder as the page in Listing 26.17. Note Internet Information Server includes several sample ADSI scripts. Look in your Inetpub\AdminScripts folder. |
.GetWebApplicationSection("system.web/compilation"), CompilationSection) lblDebug.Text = section.Debug.ToString() End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server"> <title>Show Config App</title> </head> <body> <form runat="server"> <div> Debug Mode: <asp:Label Runat="server" /> </div> </form> </body> </html> 