Monthly Archives: March 2010

Application Configuration Files

Application Configuration Files March 10th, 2010

Common in .NET development is the use of the Application Configuration Files, more commonly refereed to as the app.config file and the web.config file. I thought it would be nice to learn a little more about them, since a lot of developers I meet know how to use Application Configuration Files without really knowing anything about Application Configuration Files – they allow Visual Studio to create and populate these config files – and I don’t want to be one of them.

So the first thing I did was write up a C# FizzBuzz program. The program I wrote was inspired by this Coding Horror blog entry. It will:

  • Print the numbers 1 to 100
  • … But for multiples of some number ‘N’ it should – instead of outputting the number – output "FizzBuzz".
  • I want ‘N’ to be configurable in my Application Configuration File

I’m going to start with the easy way to provide configuration options using an app.config file; using the <appSettings> config section. I’m then going to touch on defining custom config sections.

The Easy Way: <appSettings>

While the Application Configuration File provides a wide range of configuration functionality, I’m going to start with the simplest means of configuration available; the appSettings configuration section.

Step 1: Writing the (basic) Program

This is the program I will be working with, excluding any Application Configuration File related functionality.

using System;
	
public class FizzBuzz {
	
	public static void Main() {
	
		int configurableN = 3;
		for(int index=1;index<=100;index++) {
			if(index%configurableN!=0) {
				System.Console.WriteLine(index);
			}
			else {
				System.Console.WriteLine("FizzBuzz!");
			}
		}
	
	}
	
}

I have chosen to name this .cs file FizzBizz.cs. This will be important as the name of the Application Configuration File will depend on the name of the .exe file.

Step 2: Creating the Application Configuration File

At its simplest, the basic structure of an app.config file is an xml file with a <configuration> root element.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<!-- This is my first app.config file! -->
</configuration>

The name of this file should be the same the .exe file (including the .exe extension) with an added .config extension. So I’ve named this file FizzBuzz.exe.config.

Step 3: Add an <appSettings> Section to the Application Configuration File

An Application Configuration File is divided into sections. In this first example, I’m using the out of the box <appSeettiongs> so I need to add that section. While I’m at it, I might as well also add my key-value pair:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<appSettings>
		<add key="N" value="5" />
	</appSettings>
</configuration>

When I run FizzBuzz.exe I will now be able to programatically access this application setting which I have named "N".

Step 4: Reading the <appSetting> Entry

I now need to change our FizzBuzz.cs file to read the application settings we’ve added to the config file.

Technically, I’m donig this backwards:I should have started with writing code which can be configured and then written the config file, but this is a learning exercise.

using System;
using System.Configuration;
	
public class FizzBuzz {
	
	public static void Main() {
	
		string configurableNSetting = ConfigurationSettings.AppSettings["N"];
		int configurableN;
		if(int.TryParse(configurableNSetting, out configurableN)) {
			for(int index=1;index<=100;index++) {
				if(index%configurableN!=0) {
					System.Console.WriteLine(index);
				}
				else {
					System.Console.WriteLine("FizzBuzz!");
				}
			}
		}
	
	}
	
}

… it should be noted that in order to read from the <appSettings> in this way you have to use System.Configuration.

Compile and Run!

Since I have the Windows SDK installed, my computer has a command line C# compiler. From a command prompt I just type in the following;

> C:\Windows\Microsoft.NET\Framework\v3.5\csc.exe FizzBuzz.cs

… to compile FizzBuzz.cs file into an executable (.exe) file. I can now run FizzBuzz.exe and I can see that the code uses the value of N in my configuration file. I can change the value in my config file without re-compiling my code.

The More Advanced Way: Custom Config Sections

If using the <appSettings> config section runs the risk of bloating that section and – if the code should be reused – suffering namespace collisions between the key-names of different settings; what if code you written later uses a setting with the key-name ‘N’, and has to be integrated with this code?

The solution I’m trying is to define a custom config section. First, I need to write a new class which extends class System.Configuration.ConfigurationSection:

using System.Configuration;
	
namespace ConfigSectionExample {
	
	public class FizzBuzzConfigSection : ConfigurationSection
	{
		// More to come…
	}
	
}

… I now need to add a <configSections> element to my app.config, and in it a <section>:

<configSections>
	<section name="richard" type="ConfigSectionExample.FizzBuzzConfigSection,FizzBuzzConfigSection"/>
</configSections>

This <section> element means I can now add a <richard> element to my app.config file, and settings defined in that <richard> element are associated with my class ConfigSectionExample.FizzBuzzConfigSection which will be in an assembly named FizzBuzzConfigSection.dll.

While there are a few ways I could proceed, the main two options for defining custom config sections would be to either provide my configurable ‘N’ as an XML attribute (or what Microsoft would call a Configuration Property) of this section, or as XML elements nested within my section.

XML Attributes for a Custom Section

What if I want to use XML Attributes to define my configurable value of ‘N’? I’ll start by adding an XML attribute on this config section, so all together my app.config file now looks like this:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<configSections>
		<section name="richard" type="ConfigSectionExample.FizzBuzzConfigSection,FizzBuzzConfigSection"/>
	</configSections>
	<richard N="5" />
</configuration>

In order to read and utilize this "N" XML attribute I need to make some code changes to the custom config section class:

using System.Configuration;
	
namespace ConfigSectionExample {
	
	public class FizzBuzzConfigSection : ConfigurationSection
	{
		[ConfigurationProperty( "N" )]
		public string N {
			get {
				// Note the ConfigurationProperty( "N" ) attribute,
				// and how the "N" there matches the "N" index here…
				return this["N"].ToString();
			}
		}
	}
	
}

What I’ve had to do is add a property ‘N’ to my FizzBuzzConfigSection class. I have applied the ConfigurationProperty attribute to this new property, associating it with the ‘N’ XML attribute in my app.config file. Doing this allows me to access this XML attribute using an indexer:

this["N"]

… without the ConfigurationProperty attribute, this would generate a runtime exception.

Accessing this custom config section as opposed to the <appSettings> also requires a change in the main program.

using System;
using System.Configuration;
	
public class FizzBuzz {
	
	public static void Main() {
	
		FizzBuzzConfigSection section = (FizzBuzzConfigSection)ConfigurationManager.GetSection( "richard" );
		string configurableNSetting = section.N;
		int configurableN;
		if(int.TryParse(configurableNSetting, out configurableN)) {
			for(int index=1;index<=100;index++) {
				if(index%configurableN!=0) {
					System.Console.WriteLine(index);
				}
				else {
					System.Console.WriteLine("FizzBuzz!");
				}
			}
		}
	
	}
	
}
Compiling the Custom Confi Section

Lastly, I need to compile the two .cs files. To compile FizzBuzzConfigSection.cs into a DLL (since it has no main it can’t be a .exe. file) I can use the /t:library switch on the command prompt:

> csc /t:library FizzBuzzConfigSection.cs

I can then reference the newly creaetd FizzBuzzConfigSection.dll when I compile FizzBuzz.cs into a .exe file, using the /r: switch.

> csc /r:FizzBuzzConfigSection.cs FizzBuzz.cs

Custom Configuration Elements

You may have noticed that the original app.config – when I was using <appSettings> – was using an <add> element instead of an XML attribute on the config section. I’m not going to document my attempts to do this here; maybe in a future news entry. I will, however, link to the tutorial I’m reading to figure it out: http://devlicio.us/blogs/derik_whittaker/archive/2006/11/13/app-config-and-custom-configuration-sections.aspx