Create and Use a Custom Config File
Published: 10 Aug 2005
Unedited - Community Contributed
This article documents how to easily create a separate custom .config file for your ASP.NET application, and how to retrieve the custom configuration information using the existing framework ConfigurationSectionHandler.
by Steven Archibald
Average Rating: This article has not yet been rated.
Views (Total / Last 10 Days): 53152/ 143

Background Information

When you create a web project in Visual Studio, a standard configuration file, named Web.config, is automatically created for you. This file is actually an XML document file. For a greater understanding regarding the format of this file, read the Microsoft reference titled Format of ASP.NET Configuration Files. If you want to store application-wide configuration information in an external file, such as an SQL Server connection string, it is usually recommended that you add an <appSettings> section to your Web.config file and store your information in this ‘additional’ section. This works well if the information is fairly static, and is not subject to change outside of your control.

One of my clients wanted to have some application-wide information available for their website, namely release information in text format, but did not wish to put it in the web.config file. They have a separate department that is responsible for doing builds and releasing them to QA and Production. The one thing this department wanted to do was to place a simple text file in the root web directory that any page could then have available. I suggested using a custom .config file, named Release.config. Below, I document what goes in this custom .config file and then how to access its values using a simple static method in a utility class.

Most samples of custom application configuration processing that you find on the web document how to add sections to an existing Web.config file. That particular solution was not appropriate here since the department responsible for producing the information was not a development department.

The steps are fairly simple:

  1. Create our own custom .config file which is itself an XML document.
  2. Modify the standard Web.config file to reference our custom .config file.
  3. Create a utility method to extract the desired values from the custom .config file.
  4. Modify our application code to utilize the utility method.
Create the Custom .config File

We’ll name the custom file Release.config. It will be placed in the same directory in which the standard Web.config file is found. The structure of this XML document is simple. The root element of this document is simply a name of a section that we will add to the standard Web.config file, following some rules described below. The name doesn’t really matter--we make it up. It would be nice to have it reflect the data and purpose of the section. We’ll call our section appReleaseSection.  It is within this element that we add the code to define the names of our data elements and their values.

Listing 1 -The Custom .config File

<?xml version="1.0" encoding="utf-8" ?>
      <add key="ReleaseNumber" value="" />
      <add key="ReleaseDate" value="08/03/2005" />

Seems simple so far. Note that we are using the same simple <add key> mechanism used in the normal <appSettings> section of the standard Web.config file. That means we can use the same handler in the next step.

Change the Standard Web.config File

We need to modify Web.config in two different areas; near the top, and near the bottom.

Listing 2 – Change the Top Area

<?xml version="1.0" encoding="utf-8" ?>
 <section name="appReleaseSection" type="System.Configuration.NameValueFileSectionHandler, 
 System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>

Note that this code goes between the <configuration> opening tag and the <system.web> opening tag. You really do need all the gobbledy-gook in the type attribute. I’ve tried taking parts of it out, and it just stops working without it. Note that here we are referencing the NameValueFileSectionHandler alluded to earlier. There is a useful Microsoft reference on creating new configuration sections that you should take a moment to read. The most useful part of this reference is how to use the same configuration section handler that is used for the <appSettings> section. That is what we are doing here. The tag <section> above was merely lifted from similar code. The code sample in the link has some additional section tags that aren’t required, so I’ve eliminated them. You can also create your own IConfigurationSectionHandler object, but it’s just simpler to use one that already exists, particularly since our data is so simple.

If you are not familiar where to locate the Version, Culture, and PublicKeyToken values for the NameValueFileSectionHandler, all you have to do is look at the machine.config file on server.

The following code goes just below the closing </appSettings> or </system.web> depending on whether you have an <appSettings> section or not. In my example, we do.

Listing 3 – Change the Bottom Area

<appReleaseSection file="Release.config">

Note that the file attribute is a relative path assignment. You can probably place your custom file lower down from the root, say in a special "config" directory if you want to be clever, but this suffices for the example.

Create a Static Utility Method to Extract the Values

I have a utility class, cleverly named Utility.cs, that is present in all my websites. I’ll present a sample as though this were the only method in the class (don’t want to give away too many secrets all at once, eh?). In my example, I exclude the constructor and remove some tabs to conserve valuable web page space and protect the environment.

Listing 4 – The utility method

using System;
using System.Collections;
using System.Collections.Specialized;
using System.Configuration;

namespace MyWebSite
public class Utility
      public static string GetCustomConfigValue(string SectionName,string KeyName)
  NameValueCollection myData = (NameValueCollection)


    if (myData == null)
    throw(new NullReferenceException("Section Name not found: " + SectionName));
            string myValue = myData.Get(KeyName);

            if (myValue == null)
                  throw(new NullReferenceException("Key Name not found: " + KeyName));
            return myValue;

Note that we are raising exceptions here. It’s recommended, but you could just return a value like “Key name not found” so you present some value that indicates to you (when you are testing) that something didn’t work. Note the System namespaces imported at the top of the file. You need them.

Now, we go get those valuable little puppies of information!

Retrieving Our Valuable Data

To demonstrate retrieving the separated information, create a new webform named TestNewConfigurationFile. I could have used a longer name, but brevity is considered a virtue. Don’t bother to put any controls on it.

Enter the following code in the Page_Load method of your .aspx.cs file.

Listing 5 – The Web Form Code

private void Page_Load(object sender, System.EventArgs e)
      string myNumber = Utility.GetCustomConfigValue("appReleaseSection", "ReleaseNumber");
      string myDate = Utility.GetCustomConfigValue("appReleaseSection", "ReleaseDate");
      Response.Write("Release: " + myNumber + "<br />Date: " + myDate);

Build and run!

Bing, Bam, Boom – we be done!


This methodology provides several benefits:

  1. We are using standard .NET configuration processing for custom work.
  2. It probably meets “Best Practices” standards.
  3. It is extremely simple to add new custom configuration files and data in the future.
  4. By having the section name as a parameter of our utility method, we don’t have to write methods for each new file in the future.
Caveats & Limitations

The biggest limitation is we are limited to using the name/value pair type of data in our custom configuration file. One work-around would be to have the utility method figure out what type of handler was expected for the section name. Another is to have a separate method for each section name, i.e., custom .config file. I’ll leave those exercises to the clever reader. Finally, take the time to read the following Microsoft dissertation the format of ASP.NET configuration files.

User Comments

Title: Thanks   
Name: Rauf
Date: 2009-12-22 7:03:28 AM
Very useful article. keep the good work going
Title: Thanks   
Name: Fawad
Date: 2009-11-20 10:22:09 AM
Thanks buddy, loved the article. Here is a VB counterpart if anyone needs it:
********* Get Config Values ******************************
Public Shared Function GetConfigValue(ByVal strSectionName As String, ByVal strKeyName As String) As String

Dim temp As String = Nothing

Dim myData As NameValueCollection = DirectCast(ConfigurationManager.GetSection(strSectionName), _

If myData Is Nothing Then
'Section name not found
Throw New NullReferenceException("Section name not found:" & strSectionName)
'section found, try to get the value
temp = myData.Get(strKeyName)

If temp Is Nothing Then
'Key name not found, throw new exception
Throw New NullReferenceException("Key name not found: " & strKeyName)
End If
End If

End Function

**** Write Config Values (NOT TESTED BUT SHOULD WORK) ****

Public Shared Function UpdateConfigValue(ByVal strConfigFilePath As String, ByVal strSectionName As String, _
ByVal strKeyName As String, ByVal strValue As String) As Boolean

Dim xmlDoc As New XmlDocument
Dim flag As Boolean = False


For Each node As XmlNode In xmlDoc.Item(strSectionName)

'Look for add attribute
If node.Name = "add" Then

'see if we have specified key in config file
If node.Attributes.GetNamedItem("key").Value = strKeyName Then

'Key found, upd
Title: value not updated   
Name: monaung
Date: 2009-05-10 2:44:36 AM
if i am chaging the value in appReleaseSection in Cutom.Config file it is not reflecting. it gives me previous entered value why?
please can you mail me back how can i do this?
Title: config file not web.config/app.config   
Name: sixYo
Date: 2009-04-07 12:51:29 AM
you can store the data in a xml file without web.config / app.config
Title: Little Change   
Name: ACostaF
Date: 2008-04-18 9:51:47 AM
Good article. In order to MSDN Library suggestion, you must use System.Configuration.ConfigurationManager.GetSection instead of System.Configuration.ConfigurationSettings.GetConfig as ConfigurationSettings is obsolete.
Title: Need your help   
Name: Sukki
Date: 2008-03-01 12:17:10 PM
it works well for me but when i try to add a subsection it fails. How can i handle this
Title: Good One   
Name: Rajesh
Date: 2007-07-24 6:16:13 AM
Thanks Steven Archibald, this article was good and helped me a lot.

In addition to this, i wanted to use Release.xml file rather than Release.config file. Is the code works same for the .xml file?

Anticipating your response.

Title: Thank you!   
Name: Chris Bidwill
Date: 2007-05-23 10:27:30 PM
Thanks, this was a huge help. From all the other posts I've found out there it looked like creating custom sections was a huge pain (so much it was easier just to parse the xml doc). This saved me a lot of frustration.
Title: Good Work   
Name: Satyam Kumar
Date: 2006-10-18 3:04:39 PM
Thanks to aspalliance team.

Nice work done by team that i was looking for long time.

If any addition or Enhancement then pls let me know.

Title: Custom.Config File   
Name: Satyadeep Behera
Date: 2006-06-16 4:57:48 AM
after updating the Custom.config file can i able to get the
new values that has been saved at run time, i have dataaccess layer and i want to fix this value here.
please help me.
Title: Custom.Config File   
Name: Satyadeep Behera
Date: 2006-06-15 3:21:08 AM
but is if i am chaging the value in appReleaseSection in Cutom.Config file it is not reflecting it gives me previous entered value why?
please can you mail me back how can i do this?

Community Advice: ASP | SQL | XML | Regular Expressions | Windows

©Copyright 1998-2020  |  Page Processed at 2020-04-04 11:14:43 PM  AspAlliance Recent Articles RSS Feed
About ASPAlliance | Newsgroups | Advertise | Authors | Email Lists | Feedback | Link To Us | Privacy | Search