Learn the Basics of System.Configuration: Part II

Troubleshooting Tricks

LANGUAGES: All .NET Languages

TECHNOLOGIES: System.Configuration

Learn the Basics of System.Configuration: Part II

When working with configuration sections, you don't have to sacrifice flexibility for simplicity.

By Don Kiely

The System.Configuration namespace sports many features, yet it has a surprisingly simple set of classes and interfaces - don't look for any complex objects here. Figure 1 describes the contents of the namespace. In this article, I'll continue the dialogue on configuration by walking you through the basics of the namespace as well as four key classes: DictionarySectionHandler, NameValueSectionHandler, SingleTagSectionHandler, and IgnoreSectionHandler.

Class	Description
AppSettingsReader	Provides a single method, GetValue, which gets the value for a specified key from the AppSettings property and returns an object of the specified type containing the value from the .config file. Handy when the value is not a string but a serialized object.
ConfigurationException	The exception thrown when an error occurs in a configuration setting.
ConfigurationSettings	A sealed class that provides two ways to read configuration settings: an AppSettings property for the standard section and a GetConfig method for custom sections, which is a more generalized version of AppSettings.
DictionarySectionHandler	Reads key-value pair configuration information for a configuration section. Provides a Create method that evaluates the given XML section and returns a HashTable that contains the results of the evaluation, as well as KeyAttributeName and ValueAttributeName properties to get the name of the respective attributes.
IgnoreSectionHandler	Provides a section handler definition for configuration sections read and handled by systems other than System.Configuration. Gives you a way to include information in a .config file that you're not using System.Configuration to read, but avoiding parsing errors.
NameValueSectionHandler	Provides name-value pair configuration information from a configuration section. Similar to DictionarySectionHandler except it returns a NameValueCollection instead of a HashTable.
SingleTagSectionHandler	Provides only a Create method that returns a HashTable object. Unlike the other handlers that use elements for each value, the settings are specified as a group of attributes of a single XML element.

Interface	Description
IConfigurationSectionHandler	Interface all configuration section handlers must implement to read and resolve configuration settings.

Figure 1. Here are the objects and interfaces in the System.Configuration namespace classes. Note the absence of overly complicated objects.

Incidentally, you might have noticed that Figure 1 does not include the NameValueFileSectionHandler specified by the machine.config file for the appSettings section I discussed in part I of this series (see Manage App Settings With web.config). That's because this handler, according to the .NET Framework documentation, "supports the .NET Framework infrastructure and is not intended to be used directly from your code." But it is generally similar to the NameValueSectionHandler.

The DictionarySectionHandler class reads key-value pair configuration information. Besides other interface elements it inherits from System.Object, it includes one method and two properties. The Create method, mandated by the IConfigurationSectionHandler interface, evaluates the given XML section and returns a HashTable with the contents of that section when you call the GetConfig method of the ConfigurationSettings class. Using that HashTable, you can read whatever values you need.

This handler also includes KeyAttributeName and ValueAttributeName properties to get the name of the respective attributes:

<section name="DBSettings"

type="System.Configuration.DictionarySectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

</configSections>

</DBSettings>

The NameValueSectionHandler class provides name-value pair configuration information from a configuration section. It is similar to the DictionarySectionHandler, but it exposes your data as a NameValueCollection instead of a HashTable and it doesn't have the custom properties to retrieve the key and value attribute names:

<section name="DBSettings"

type="System.Configuration.NameValueSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

</configSections>

</DBSettings>

The SingleTagSectionHandler class provides only a Create method that returns a HashTable object. Unlike DictionarySectionHandler and NameValueSectionHandler, which both require a new element in the custom section for each piece of data, the data is included as attributes of a single element in the section:

<section name="DBSettings"

type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

</configSections>

IgnoreSectionHandler is a bit of an anomaly in configuration section handlers. According to the .NET documentation, this class provides a section handler definition for configuration sections read and handled by systems other than System.Configuration. It gives you a way to include information in a .config file that you're not reading with System.Configuration while avoiding parsing errors. The data you include still needs to be well-formed XML. But even if your application never reads the data, the app won't run because .NET finds data in the .config file it's incapable of reading. If you use this section handler, your application will run and ignore the data in this section.

System.Configuration's built-in features provide plenty of flexibility for how you work with configuration sections. But when you need more, you can create custom configuration sections and implement your own section handler. I'll cover this topic in the final installment of this series.

Don Kiely is senior technology consultant for Information Insights, a business and technology consultancy in Fairbanks, Alaska. E-mail him at mailto:[email protected].

Comments

Plain text