23.5. Application Configuration

Many applications rely on external static settings that they read before they do something useful. Such settings are never hardcoded in the application itself, because doing so forces a recompilation of the application whenever a simple static setting changes.

A traditional approach is to store these static settings in a static configuration file. Java programmers are probably thinking about .properties files. A Java property file is a file containing name/value pairs that can be used at runtime by the application. JDK 1.4 introduced a more structured way of storing these settings in a class called java.util.Preferences.

The .NET Framework comes with its own arsenal of classes that allow configuration of the application. Because everything is XML-based in the .NET Framework, there is no special syntax to be learned. The framework provides a rich API for reading these configuration files.

A .NET configuration file ends with the .config file extension. For the application MyApp.exe the configuration file would be MyApp.exe.config. For multiple-file assemblies, the configuration file is named after the file that contains the manifest. The CLR ensures that the configuration files are loaded automatically, and therefore no special effort is needed by the programmer. The configuration files must contain the root XML node <configuration>.

In its simplest form, custom application settings are defined in the <appSettings> section of the configuration file. The settings are defined as key-value pairs.

<configuration>
  <appSettings>
  <add key="Key1" value="Value1"/>
  <add key="Key2" value="Value2"/>
  <add key="Key3" value="Value3"/>
</appSettings>

You can also specify sections in the configuration file. Sections are used to define complex settings. There are three types of sections depending on the handler that is specified for each section: a single-tag section, a name/value section, and a dictionary section.

23.5.1. Single-Tag Section

A single-tag section allows you to define the key-value pairs as an attribute of a single XML tag:

<configuration>
  <configSections>
  <section name="Single"
    type="System.Configuration.SingleTagSectionHandler"/>
  </configSections>
  <Single Key1 = "Value1"
          Key2 = "Value2"
          Key3 = "Value3"></Single>
</configuration>

23.5.2. Name/Value Section

A name/value section allows you to define the key-value pairs in the same way as the simple settings are defined:

<configuration>
  <configSections>
  <section name="NameValue"
    type="System.Configuration.NameValueSectionHandler" />
  </configSections>
  <NameValue>
    <add key="Key1" value="Value1"/>
    <add key="Key2" value="Value2"/>
    <add key="Key3" value="Value3"/>
  </NameValue>
</configuration>

23.5.3. Dictionary Section

A dictionary section is similar to a name/value section except that a dictionary section uses a different section handler:

<configuration>
  <configSections>
    <section name=" Dictionary"
      type="System.Configuration.DictionarySectionHandler" />
  </ configSections >
  <Dictionary>
    <add key="Key1" value="Value1"/>
    <add key="Key2" value="Value2"/>
    <add key="Key3" value="Value3"/>
  </Dictionary>
</configuration>

You can even signal the configuration file parser to ignore sections by making the section handler an IgnoreSectionHandler.

<configuration>
  <configSections>
<section name="Advanced"
type="System.Configuration.IgnoreSectionHandler" />
  </configSections>
<Advanced>
<add key="Key1" value="Value1"/>
<add key="Key2" value="Value2"/>
<add key="Key3" value="Value3"/>
</Advanced>
</configuration>

23.5.4. A Sample Config File

Listings 23.10 and 23.11 show how to handle the simple application settings along with the section settings we've discussed. Listing 23.10 shows the complete MyApp.config file.

Listing 23.10. A Sample .NET Config File (C#)

<configuration>
  <configSections>
    <section name="Single"
    type="System.Configuration.SingleTagSectionHandler" />

    <section name="NameValue"
    type="System.Configuration.NameValueSectionHandler" />

    <section name="Dictionary"
    type="System.Configuration.DictionarySectionHandler" />
  </configSections>

<appSettings>
  <add key="SimpleKey1" value="SimpleValue1"/>
  <add key="SimpleKey2" value="SimpleValue2"/>
  <add key="SimpleKey3" value="SimpleValue3"/>
</appSettings>
  <Single SingleKey1 = "SingleValue1"
    SingleKey2 = "SingleValue2"
    SingleKey3 = "SingleValue3" />

  <NameValue>
  <add key="NameValueKey1" value="NameValueValue1"/>
  <add key="NameValueKey2" value="NameValueValue2"/>
  <add key="NameValueKey3" value="NameValueValue3"/>
  </NameValue>

  <Dictionary>
    <add key="DictionaryKey1" value="DictionaryValue1"/>
    <add key="DictionaryKey2" value="DictionaryValue2"/>
    <add key="DictionaryKey3" value="DictionaryValue3"/>
  </Dictionary>

</configuration>

Note that there can be only one <configSections> element of the <configuration> root, and it must be the first child of the root node. Listing 23.11 shows how the different settings of the config file are read.

Listing 23.11. A Simple C# Class to Read the Application Settings

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

public class MyApp {

  public static void Main(string[] args) {
    //Read simple settings
    ReadSimpleSettings();
    //Read single-tag settings
    ReadSingleTagSettings();
    //Read single-tag settings
    ReadNameValueSettings();
    //Read single-tag settings
    ReadDictionarySettings();
  }

  private static void ReadSimpleSettings() {
    Console.WriteLine(
    ConfigurationSettings.AppSettings["SimpleKey1"]);
  }

  private static void ReadSingleTagSettings() {
    IDictionary dict = (IDictionary)
    ConfigurationSettings.GetConfig("Single");
    Console.WriteLine(dict["SingleKey2"]);
  }

  private static void ReadNameValueSettings() {
    NameValueCollection dict = (NameValueCollection)
    ConfigurationSettings.GetConfig("NameValue");
    Console.WriteLine(dict["NameValueKey3"]);
  }

  private static void ReadDictionarySettings() {
    Hashtable dict = (Hashtable)
    ConfigurationSettings.GetConfig("Dictionary");
    Console.WriteLine(dict["DictionaryKey1"]);
  }
}

The output of Listing 23.11 is as follows:

SimpleValue1
SingleValue2
NameValueValue3
DictionaryValue1

The code in Listing 23.11 is self-explanatory. The ConfigurationSettings class of the System.Configuration namespace contains all the methods needed to parse a config file. Note that the object returned by the GetConfig method is cast to the appropriate collection depending on the section being read.

Note also that the collections returned by the ConfigurationSettings class are read-only. You cannot use this class to modify the config file. You should do this manually.