Microsoft KB Archive/309045

= How To Create a Custom ASP.NET Configuration Section Handler in Visual C# .NET =

Article ID: 309045

Article Last Modified on 7/15/2004

-

APPLIES TO


 * Microsoft ASP.NET 1.1
 * Microsoft ASP.NET 1.0
 * Microsoft Visual C# .NET 2003 Standard Edition
 * Microsoft Visual C# .NET 2002 Standard Edition

-



This article was previously published under Q309045



For a Microsoft Visual Basic .NET version of this article, see 318457.

This article refers to the following Microsoft .NET Framework Class Library namespaces:
 * System.Configuration
 * System.Xml

IN THIS TASK
SUMMARY
 * Create the Configuration Section Handler and Its Components
 * Complete Code Listing
 * Test the Configuration Section Handler
 * Troubleshooting

REFERENCES



SUMMARY
This article describes how to use Visual C# .NET to create a custom configuration section handler for ASP.NET.

back to the top

Create the Configuration Section Handler and Its Components
These steps demonstrate how to create the configuration section handler and its components. So that you can better maintain and reuse the code, these steps demonstrate how to create a class named ConfigHelper that includes static methods. These static methods help you parse and retrieve the XML attributes in the configuration file. Because the code to build ConfigHelper uses an enumeration and a string in the configuration section, ConfigHelper contains two methods, GetEnumValue and GetStringValue.

The GetEnumValue method parses the configuration section for an attribute with predefined values, verifies that the value of the attribute is valid, and then returns the attribute and its value. The GetStringValue method parses the configuration section for an attribute and then returns the attribute and its value.  Start Microsoft Visual Studio .NET. On the File menu, point to New, and then click Project. In the New Project dialog box, click Visual C# Projects under Project Types, and then click Class Library under Templates. In the Name text box, type MyConfig, and then click OK. Add a reference to the System.Web.dll assembly. Rename Class1.cs as MyConfig.cs. From Solution Explorer, open MyConfig.cs.  Add the following namespace declarations to the top of the file: using System.Configuration; using System.Web; using System.Xml; </li> Delete the default class definition.</li>  Add an enumeration to hold an attribute for the custom configuration section: public enum LevelSetting {  High, Medium, Low, None }                   </li>  Create a class named MyConfigSection to hold the configuration information. This class is the object that the Create method implementation returns. public class MyConfigSection {  private LevelSetting level = LevelSetting.None; private string name = &quot;&quot;; public MyConfigSection(LevelSetting _level, string _name) {     level = _level; name = _name; }  public LevelSetting Level {     get {return level;} }  public string Name {     get {return name;} } }                   </li>  Create a class named ConfigHelper as follows: internal class ConfigHelper {  //Helper method for retrieving enum values from XmlNode. public static XmlNode GetEnumValue (XmlNode _node, string _attribute,Type _enumType, ref int _val) {     XmlNode a = _node.Attributes.RemoveNamedItem(_attribute); if(a==null) throw new ConfigurationException(&quot;Attribute required: &quot; + _attribute); if(Enum.IsDefined(_enumType, a.Value)) _val = (int)Enum.Parse(_enumType,a.Value); else throw new ConfigurationException(&quot;Invalid Level: '&quot; + a.Value + &quot;'&quot;,a); return a;  } //Helper method for retrieving string values from xmlnode. public static XmlNode GetStringValue(XmlNode _node, string _attribute, ref string _val) {     XmlNode a = _node.Attributes.RemoveNamedItem(_attribute); if(a==null) throw new ConfigurationException(&quot;Attribute required: &quot; + _attribute); else _val = a.Value; return a;       } } NOTE: You can also create a helper method for each data type for which you use your configuration section (for example, GetIntValue and GetBooleanValue). </li>  Create a class named MyConfigSectionHandler. This class inherits the IConfigurationSectionHandler interface and implements the Create method of that interface. In the Create method, this code uses the ConfigHelper class to retrieve the values from the configuration file. The sample then creates and returns the MyConfigSection object.

The MyConfigSectionHandler class should appear as follows: public class MyConfigSectionHandler : IConfigurationSectionHandler {  public virtual object Create(object parent,object configContext,XmlNode section) {     int iLevel = 0; string sName = &quot;&quot;;

ConfigHelper.GetEnumValue(section, &quot;level&quot;, typeof(LevelSetting), ref iLevel); ConfigHelper.GetStringValue(section, &quot;name&quot;, ref sName); return new MyConfigSection((LevelSetting)iLevel,sName); } }                   </li> Save and compile the project.</li></ol>

back to the top

Complete Code Listing
In its final form, your class file should appear as follows: using System; using System.Web; using System.Xml; using System.Configuration;

namespace MyConfig {  public enum LevelSetting {     High, Medium, Low, None }  public class MyConfigSectionHandler : IConfigurationSectionHandler {     public virtual object Create(object parent,object configContext,XmlNode section) {        int iLevel = 0; string sName = &quot;&quot;; ConfigHelper.GetEnumValue(section, &quot;level&quot;, typeof(LevelSetting), ref iLevel); ConfigHelper.GetStringValue(section,&quot;name&quot;,ref sName); return new MyConfigSection((LevelSetting)iLevel,sName); }  }   public class MyConfigSection {     private LevelSetting level = LevelSetting.None; private string name = null; public MyConfigSection(LevelSetting _level,string _name) {        level = _level; name = _name; }     public LevelSetting Level {        get {return level;} }     public string Name {        get {return name;} }  }   internal class ConfigHelper {     public static XmlNode GetEnumValue (XmlNode _node, string _attribute,Type _enumType, ref int _val) {        XmlNode a = _node.Attributes.RemoveNamedItem(_attribute); if(a==null) throw new ConfigurationException(&quot;Attribute required: &quot; + _attribute); if(Enum.IsDefined(_enumType, a.Value)) _val = (int)Enum.Parse(_enumType,a.Value); else throw new ConfigurationException(&quot;Invalid Level&quot;,a); return a;     } public static XmlNode GetStringValue(XmlNode _node, string _attribute, ref string _val) {        XmlNode a = _node.Attributes.RemoveNamedItem(_attribute); if(a==null) throw new ConfigurationException(&quot;Attribute required: &quot; + _attribute); else _val = a.Value; return a;           } } } back to the top

Test the Configuration Handler
<ol> Open Visual Studio .NET.</li> In the New Project dialog box, click Visual C# Projects under Project Types, and click ASP.NET Web Application under Templates. Specify the name and location for your new project.</li> Add a reference to MyConfig.dll.</li>  Open the Web.config file. Add the following code within the   section: <configSections> <sectionGroup name=&quot;system.web&quot;> <section name=&quot;myConfig&quot; type=&quot;MyConfig.MyConfigSectionHandler,MyConfig&quot; /> </sectionGroup> </configSections> </li>  Add the following code within the <system.web> section: <myConfig level=&quot;High&quot; name=&quot;hello world&quot; /> </li>  Open the code-behind file for WebForm1.aspx, which is named WebForm1.aspx.cs by default. Add the following namespace declaration to the top of WebForm1.aspx.cs: using MyConfig; </li>  Add the following code to the Page_Load event. This code calls the GetConfig method to retrieve an instance of the MyConfigSection object and then writes out the values of the two properties of the object. MyConfigSection s = (MyConfigSection)Context.GetConfig(&quot;system.web/myConfig&quot;); Response.Write(&quot;Level: &quot; + s.Level + &quot; &quot;); Response.Write(&quot;Name: &quot; + s.Name); </li> Save and compile the application.</li> View the page in the browser. The following output should appear:

Level: High

Name: hello world

</li></ol>

back to the top

Troubleshooting
When you create a custom ASP.NET configuration section handler, use the following guidelines when you implement the IConfigurationSectionHandler interface:
 * Instances of your class that implement the IConfigurationSectionHandler interface must be thread-safe and stateless. You must be able to call the IConfigurationSectionHandler.Create method from multiple threads simultaneously.
 * The configuration object that IConfigurationSectionHandler.Create returns must be thread-safe and immutable.
 * Do not modify the parent argument to IConfigurationSectionHandler.Create. Because the configuration system caches the configuration objects, it is important that you not modify the parent argument to IConfigurationSectionHandler.Create. For example, if the return value of IConfigurationSectionHandler.Create is only a small modification of the parent, you must modify a clone of the parent, not the original.

back to the top

<div class="references_section">