Ref:
Introduction
Most ASP.NET applications include a number of configuration settings, such as connection strings, mail server settings, system-wide default settings, and so forth. While these settings could be hard-coded in the source code, it's usually a wiser idea to place them in a configuration file, such asWeb.config. The reasoning being that if these values need to be modified, editing a configuration file is a lot easier than updating the code, rebuilding, and re-deploying. In fact, Web.config provides an <appSettings> section intended to hold application-wide configuration settings (see for more details). While <appSettings> work well for in-house applications, if you are building an application that will be deployed by end users a more professional approach is to use a custom configuration section. <appSettings>, for example, requires that all values be simple scalars provided through <add> elements, like:
<appSettings> <add key="message" value="Hello, World!" /> <add key="maxEntriesPerPage" value="10" /> <add key="showMessageInBold" value="true" /></appSettings>
With a custom configuration section, you can provide a more readable syntax. Moreover, custom configuration sections can support collection properties, as the following example illustrates:
<ScottsSettings message="Hello, World!" showMessageInBold="true"> <favoriteColors> <color>Red</color> <color>Yellow</color> <color>Brown</color> </favoriteColors></ScottsSettings>
In this article we'll examine how to use a custom configuration section technique that works in both ASP.NET 1.x and 2.0 applications. See for more on .NET 2.0's new configuration classes and capabilities. Read on to learn more!
Custom Configuration Section Basics
Custom configuration sections can be created inWeb.config through the <configSections> element, specifying the name of the configuration section and the class type that is responsible for deserializing the configuration XML into a class instance. We'll explore the <configSections> element in Web.config once we have created a class to handle the deserialization. In applications, typically two classes are used:
- A handler class, which implements . This class is responsible for loading the configuration markup from
Web.config. - A configuration class whose set of properties represent the information captured in the custom configuration section. Along with providing the properties, this class also is responsible for deserializing the configuration XML passed to it from its corresponding handler class.
In this article we will focus solely on the 1.x technique; for more on .NET 2.0's new configuration classes and capabilities. We'll first look at creating and using a very simple custom configuration section. Following that, we'll add a collection property to the section.
Why ASP.NET 1.x Syntax and Style is Used
Since this article examines features that date back to the 1.x timeframe (even though they'll work perfectly fine in 2.0 and even though the download at the end of this article is an ASP.NET 2.0 website application), I've used the syntax that works in 1.x rather than take advantage of new 2.0 features. For example, later on in this article we'll use the ConfigurationSettings class's GetConfig method, which has been deprecated in 2.0 in favor of the ConfigurationManager class's GetSection method. Regardless, I stick with the using the ConfigurationSettings class's GetConfig method. Similarly, when we look at specifying collections in the custom configuration section, I use a StringCollection object to hold this collection of strings. If I were creating this for .NET 2.0, I'd use a Generic List instance of type string instead.
Creating the Configuration Class
As aforementioned, the code for custom configuration sections in ASP.NET 1.x applications is typically broken down into two class files, a handler class and a configuration class. Let's create the configuration class first. Imagine that we want our custom configuration section to record three settings:message, favoriteNumber, and showMessageInBold. We would start by creating three public properties in this class like so: public class ASPNET1Configuration{ private string _message = "Hello, World!"; private int _favoriteNumber = 2; private bool _showMessageInBold = true; public string Message { get { return _message; } } public int FavoriteNumber { get { return _favoriteNumber; } } public bool ShowMessageInBold { get { return _showMessageInBold; } } ...} The three private member variables specify the default values (i.e., the values used if the property is not provided in the custom configuration section). The three properties are read-only and simply return the corresponding member variable.
The configuration class also needs to provide a method for deserializing the configuration XML. To accomplish this, we need to add a method that accepts an XmlNode instance as input and steps through the XML data to populate the property values.
public class ASPNET1Configuration{ ... Property and member variable statements omitted for bevity ... internal void LoadValuesFromXml(XmlNode section) { XmlAttributeCollection attrs = section.Attributes; if (attrs["message"] != null) { _message = attrs["message"].Value; attrs.RemoveNamedItem("message"); } if (attrs["favoriteNumber"] != null) { _favoriteNumber = Convert.ToInt32(attrs["favoriteNumber"].Value); attrs.RemoveNamedItem("favoriteNumber"); } if (attrs["showMessageInBold"] != null) { _showMessageInBold = XmlConvert.ToBoolean(attrs["showMessageInBold"].Value); attrs.RemoveNamedItem("showMessageInBold"); } // If there are any further attributes, there's an error! if (attrs.Count > 0) throw new ConfigurationException("There are illegal attributes provided in the section"); }}
The LoadValuesFromXml method inspects the Attributes collection of the passed-in XmlNode instance. If it exists, it reads in the value into the corresponding member variable and removes the attribute from the XmlNode. If, after the three properties have been deserialized, there are any additional attributes in the XmlNode, a ConfigurationException is raised since an invalid attribute is included in the custom configuration section.
Creating the Handler Class
The handler class is reponsible for taking the XML from the configuration file and passing it to the configuration class for deserialization. The handler class must implementIConfigurationSectionHandler, which defines a single method, Create. Create accepts as one of its input parameters the XmlNode from the configuration section and is tasked with returning an instance of the configuration data. This can all be accomplished with just a few lines of code, as shown below: public class ASPNET1ConfigurationHandler : IConfigurationSectionHandler{ public object Create(object parent, object configContext, XmlNode section) { ASPNET1Configuration config = new ASPNET1Configuration(); config.LoadValuesFromXml(section); return config; }} An instance of the ASPNET1Configuration class is created and its LoadValuesFromXml method is passed the XmlNode instance received by the Create method. The Create method completes by returning the deserialized ASPNET1Configuration instance.
Defining the Custom Configuration Section in Web.config
Web.config, we need to first define it in the <configSections> element like so: ...
Note that the type value is the fully-typed name of the handler class. Since the handler class appears in my App_Code folder, the value for the type attribute is simply the class's name. If this class resided in a separate assembly, the type value would be: "Namespace.ClassName, AssemblyName".
With the custom configuration section specified in <configSections>, we can add the custom section to Web.config. Note that the custom section, like <configSections>, appears outside of the <system.web> section:
...
Programmatically Accessing the Configuration Information from the ASP.NET Application
To work with the configuration information from an ASP.NET page or one of the classes that make up the application's architecture, we need to use theConfigurationSettings class's GetConfig method, passing in the path to the markup we are interested in ("aspnet1Configuration", for this example). This can be accomplished using the following code snippet: ASPNET1Configuration configInfo = (ASPNET1Configuration) ConfigurationSettings.GetConfig("aspnet1Configuration");// Work with the properties from the ASPNET1Configuration class...string msg = configInfo.Message;...
What's cool about the GetConfig() method is that is automatically caches the configuration information returned by the associated handler class. This data remains cached until the application is restarted (such as through restarting the webserver, modifying Web.config, uploading an assembly to the /bin folder, and so on). To convince yourself that this caching occurs, download the sample code at the end of this article and set a breakpoint in the above line of code and in the Create method of the handler class and then start debugging. What you'll find is that the first time the configuration data is read in after an application restart, the handler class's Create method is invoked when the GetConfig() method is called. On subsequent calls, however, the Create method is not executed, as its results have been cached.
Rather than having to enter this code each time we want to work with configuration data, we can add a static method to the ASPNET1Configuration that encapsulates this logic.
public static ASPNET1Configuration GetConfig(){ return ConfigurationSettings.GetConfig("customConfigDemo/aspnet1Configuration") as ASPNET1Configuration;}
With this method in place, accessing a configuration value is as easy as doing the following:
string msg = ASPNET1Configuration.GetConfig().Message;
The following ASP.NET page displays these configuration settings in a Label Web control, as the following code illustrates:
string messageHtml = ASPNET1Configuration.GetConfig().Message;if (ASPNET1Configuration.GetConfig().ShowMessageInBold) messageHtml = "<b>" + messageHtml + "</b>";int favNumber = ASPNET1Configuration.GetConfig().FavoriteNumber;// Display the configuration settingsaspnet1Values.Text = string.Format("The message is {0} and your favorite number is {1}.", messageHtml, favNumber);
Deserializing More "Interesting" Configuration Markup
The code we've examined thus far has only allowed for scalar properties defined as attributes in the configuration markup. But what if we want to have the custom configuration section specify properties through the XML elements' text nodes (like<someProperty<value</someProperty>) or what if we want to allow the configuration data to include an arbitrary collection of information? Since the configuration class's LoadValuesFromXml method is passed an XmlNode, we simply need to update that method to perform any of the more rigorous deserialization. For example, imagine that in addition to the message, favoriteNumber, and showMessageInBold properties we also wanted to allow the developer to specify a list of "favorite colors" through the following pattern:
Red Olive Purple ...
To accomplish this, we'd need to add a new property to the configuration class ASPNET1Configuration to hold the list of favorite colors. Moreover, we'd need to update the LoadValuesFromXml method to find the <favoriteColors> element and add its <color> elements' text node values to the corresponding property. The following code accomplishes these two tasks:
public class ASPNET1Configuration{ ... Prior property and member variable statements omitted for bevity ... private StringCollection _favColors = new StringCollection(); public StringCollection FavoriteColors { get { return _favColors; } } internal void LoadValuesFromXml(XmlNode section) { ... Prior deserialization logic removed for brevity ... // Now, get the child node bool processedFavColors = false; foreach (XmlNode childNode in section.ChildNodes) { if (!processedFavColors && childNode.Name == "favoriteColors") { processedFavColors = true; foreach (XmlNode favColorNode in childNode.ChildNodes) { if (favColorNode.Name == "color") { // Get the text node value XmlNode textNode = favColorNode.ChildNodes[0]; if (textNode == null) throw new ConfigurationException("You must provide a text value for each element, like Red"); else _favColors.Add(textNode.Value); } else throw new ConfigurationException(" can only contain child elements named "); } } else throw new ConfigurationException(" may only contain one child element and it must be named "); } }}
Conclusion
In this article we explored the technique used in ASP.NET 1.x for specifying custom configuration settings inWeb.config. This is accomplished by creating two classes: a handler class and a configuration class. The handler class is used to pump the XML data from the configuration file to the configuration class, where it is deserialized. In addition to its deserialization logic, the configuration class also contains the properties that model the configuration information. This class can be accessed programmatically via the ConfigurationSettings class's GetConfig method. This method for providing custom configuration sections can be used by both ASP.NET 1.x and 2.0 applications. However, .NET 2.0 provides configuration classes that require much less code, letting us focus more on defining the properties and declaratively mapping them to the XML markup rather than writing XML deserialization code. .NET 2.0's configuration features are explored in: .
Happy Programming!