15.3 System.Configuration Namespace Reference

The System.Configuration namespace contains classes that are used to read the contents of the hierarchy of .NET Framework configuration files. The main workhorse of the System.Configuration namespace is the ConfigurationSettings class, whose staticAppSettings property provides access to a collection of key-value pairs in the appSettings section of the configuration files, and whose GetConfig( ) method provides access to other, custom configuration sections. Another class, AppSettingsReader, enables typesafe access to configuration settings.

The appSettings configuration section may contain add, remove, and clear elements. add causes a key-value pair to be added to the configuration system. remove causes a key-value pair to be removed from the configuration system. clear causes any key-value pairs already in the configuration system to be removed. The configuration files themselves are not affected, only the key-value pairs in memory for an application instance.

Custom configuration sections may be added using the section element. Each section element specifies the name of the configuration section and the name of a type that implements IConfigurationSectionHandler to handle the configuration section.

This namespace contains several classes which, although public, are reserved for internal use by the .NET Framework. No documentation is included in this quick reference for those classes. Figure 15-1 shows the types in this namespace.

public class AppSettingsReader {
// Public Constructors
   public AppSettingsReader( );  
// Public Instance Methods
   public object GetValue( string key, Type type);  
}

The AppSettingsReader provides a single method, GetValue( ), which allows you to read a value from the configuration file while specifying the type of object to return.

Figure 15-1. The System.Configuration namespace

public class ConfigurationException : SystemException {
// Public Constructors
   public ConfigurationException( );  
   public ConfigurationException( string message);  
   public ConfigurationException( string message, Exception inner);  
   public ConfigurationException( string message, Exception inner, string filename, int line);  
   public ConfigurationException( string message, Exception inner, System.Xml.XmlNode node);  
   public ConfigurationException( string message, string filename, int line);  
   public ConfigurationException( string message, System.Xml.XmlNode node);  
// Protected Constructors
   protected ConfigurationException( System.Runtime.Serialization.SerializationInfo info, 
        System.Runtime.Serialization.StreamingContext context);  
// Public Instance Properties
   public string BareMessage{get; } 
   public string Filename{get; } 
   public int Line{get; } 
   public override string Message{get; }                              // overrides Exception
// Public Static Methods
   public static string GetXmlNodeFilename( System.Xml.XmlNode node);  
   public static int GetXmlNodeLineNumber( System.Xml.XmlNode node);  
// Public Instance Methods
   public override void GetObjectData( System.Runtime.Serialization.SerializationInfo info, 
       System.Runtime.Serialization.StreamingContext context);    // overrides Exception
}

This exception indicates that a problem was encountered in the Configuration system.

Hierarchy

System.Object System.Exception(System.Runtime.Serialization.ISerializable) System.SystemException ConfigurationException

public sealed class ConfigurationSettings {
// Public Static Properties
   public static NameValueCollection AppSettings{get; } 
// Public Static Methods
   public static object GetConfig( string sectionName);  
}

This class includes a static method and property that provide access to the configuration settings in the .NET Framework configuration files. GetConfig( ) returns an object that represents a specific configuration section; the type of object returned is determined by the configuration section handler associated with the configuration section by the section element in the configuration file. The AppSettings property is a proxy for the GetConfig( ) method that returns a NameValueCollection of key-value pairs for the appSettings configuration section.

public class DictionarySectionHandler : IConfigurationSectionHandler {
// Public Constructors
   public DictionarySectionHandler( );  
// Protected Instance Properties
   protected virtual string KeyAttributeName{get; } 
   protected virtual string ValueAttributeName{get; } 
// Public Instance Methods
   public virtual object Create( object parent, object context, System.Xml.XmlNode section);    // implements IConfigurationSectionHandler
}

This type implements IConfigurationSectionHandler. Its Create( ) method returns a System.Collections.Hashtable containing all the key-value pairs read from a configuration section.

public interface IConfigurationSectionHandler {
// Public Instance Methods
   public object Create( object parent, object configContext, System.Xml.XmlNode section);  
}

This is the interface that all configuration section handlers must implement. Its Create( ) method reads the System.Xml.XmlNode passed in and returns a System.Object containing the configuration settings for the configuration section.

public class IgnoreSectionHandler : IConfigurationSectionHandler {
// Public Constructors
   public IgnoreSectionHandler( );  
// Public Instance Methods
   public virtual object Create( object parent, object configContext, 
        System.Xml.XmlNode section);// implements IConfigurationSectionHandler
}

IgnoreSectionHandler is used to instruct the configuration system to ignore the configuration section. Its Create( ) methods always returns null. A configuration section with this type of configuration section handler will usually read the XML data from the configuration file using some method other than the .NET Framework's configuration system.

public class NameValueFileSectionHandler : IConfigurationSectionHandler {
// Public Constructors
   public NameValueFileSectionHandler( );  
// Public Instance Methods
   public object Create( object parent, object configContext, System.Xml.XmlNode section);// implements IConfigurationSectionHandler
}

This type's Create( ) method returns a System.Collections.Specialized.NameValueCollection containing all the key-value pairs read from a configuration section. It also allows the configuration section element to have an attribute named file, which contains the name of an external file containing additional configuration settings. The root element of the external file must have the same name as the configuration section. NameValueFileSectionHandler is the configuration section handler used for the appSettings configuration section.

public class NameValueSectionHandler : IConfigurationSectionHandler {
// Public Constructors
   public NameValueSectionHandler( );  
// Protected Instance Properties
   protected virtual string KeyAttributeName{get; } 
   protected virtual string ValueAttributeName{get; } 
// Public Instance Methods
   public object Create( object parent, object context, System.Xml.XmlNode section); // implements IConfigurationSectionHandler
}

This type's Create( ) method returns a System.Collections.Specialized.NameValueCollection containing all the key-value pairs read from a configuration section. NameValueSectionHandler behaves identically to NameValueFileSectionHandler except that it does not allow the file attribute.

public class SingleTagSectionHandler : IConfigurationSectionHandler {
// Public Constructors
   public SingleTagSectionHandler( );  
// Public Instance Methods
   public virtual object Create( object parent, object context, System.Xml.XmlNode section); // implements IConfigurationSectionHandler
}

SingleTagSectionHandler is the configuration section handler that should be used when the configuration section consists of a single element with one or more attributes and without child nodes. Its Create( ) methods returns a System.Collections.Hashtable whose keys are the attributes' names and whose values are the attributes' values.