C# Class Azavea.Open.Common.Config

This class reads configuration parameters from a standalone config file identified in the app.config or web.config's "appSettings" section.

Show file Open project: azavea/net-om-utils-common Class Usage Examples

Public Properties

Property	Type	Description
Application	string
ConfigFile	string
ConfigXmlDoc	System.Xml.XmlDocument

Protected Properties

Property	Type	Description
_innerXmlByComponent	string>.IDictionary
_log	log4net.ILog
_orderedParamsByComponent	IDictionary>>
_outerXmlByComponent	string>.IDictionary
_paramsByComponent	IDictionary>

Public Methods

Method	Description
ClearConfigCache ( string appName ) : void	Allows you to explicitly remove a config from the cache, for example during unit testing, or any time when you know the config file in the cache is no longer valid.
ComponentExists ( string component ) : bool	Method to check if a config section exists for a component, prior to calling GetConfigXml or GetParametersAsHashTable (which throw exceptions if you request an invalid component name).
Config ( string appName ) : System	Constructs a config class given the "appName", or the key to look up in the app/web.config's "appSettings" section. The value for that key is the path to the config file we're interested in.
Config ( string appName, XmlDocument configXml ) : System	Construct a config directly from an XML document rather than from a file.
Config ( string configFileName, string appName ) : System	Constructs a config class given a specific config file to load.
Config ( string configFileName, string appName, XmlDocument configXml ) : System	Construct a config class. The app name is used for logging, and to get the config file name if the file name was not specified and the XML was not passed directly. If you provide the XML, the app name is just used for logging, and the filename is stored but not used for anything (and may be blank).
Equals ( object obj ) : bool	Two Configs with the same config file and appname are Equal.
GetConfig ( string appName ) : Config	This allows you to avoid reading the same config file over and over again. Since Config objects are read-only, we can read the file once and hand the same object out over and over without worrying about threading issues.
GetConfigInnerXml ( string component ) : string	Gets you the XML section for the component, allowing you to do any special parsing that may be necessary. This includes ONLY the children of the "component" tag, and will not have any text included in that tag.
GetConfigXml ( string component ) : string	Gets you the XML section for the component, allowing you to do any special parsing that may be necessary. This includes the "component" tag, and any text included in that tag.
GetHashCode ( ) : int	Hash code, based on the config file name and app name.
GetParameter ( string component, string parameter ) : string	Returns the config parameter for the given component. Throws an exception if there is no such parameter. If you want to know if the parameter exists, call ParameterExists(...).
GetParameter ( string component, string parameter, string defaultValue ) : string	Similar to GetParameter, except rather than throwing an exception if a parameter doesn't exist, returns the default value.
GetParameterAsBool ( string component, string parameter ) : bool	Similar to GetParameter, but converts the type for you (if possible, throws if not).
GetParameterAsBool ( string component, string parameter, bool defaultValue ) : bool	Similar to GetParameterWithDefault, except converts the type of the value (if present).
GetParameterAsBool ( string component, string parameter, bool defaultValue ) : bool?	Similar to GetParameterWithDefault, except converts the type of the value (if present).
GetParameterAsDouble ( string component, string parameter ) : double	Similar to GetParameter, but converts the type for you (if possible, throws if not).
GetParameterAsDouble ( string component, string parameter, double defaultValue ) : double	Similar to GetParameterWithDefault, except converts the type of the value (if present).
GetParameterAsDouble ( string component, string parameter, double defaultValue ) : double?	Similar to GetParameterWithDefault, except converts the type of the value (if present).
GetParameterAsInt ( string component, string parameter ) : int	Similar to GetParameter, but converts the type for you (if possible, throws if not).
GetParameterAsInt ( string component, string parameter, int defaultValue ) : int	Similar to GetParameterWithDefault, except converts the type of the value (if present).
GetParameterAsInt ( string component, string parameter, int defaultValue ) : int?	Similar to GetParameterWithDefault, except converts the type of the value (if present).
GetParameterWithSubstitution ( string component, string parameter, bool tolerant ) : string	Similar to the regular GetParameter method, except it will substitute environment variables in the values if present.
GetParameterWithSubstitution ( string component, string parameter, bool tolerant, string defaultValue ) : string	Similar to the regular GetParameter method, except it will substitute environment variables in the values if present.
GetParametersAsDictionary ( string component ) : string>.Dictionary	Gets you a Dictionary of all the parameters for the component.
GetParametersAsList ( string component ) : string>>.IList	Gets you a list of all the parameters for the component as key-value-pairs. This preserves the order of parameters from the config file.
ParameterExists ( string component, string parameter ) : bool	Method to check if a parameter exists, prior to calling GetParameter (which throws exceptions if you request an invalid parameter).
ReplaceEnvironmentVariables ( string val, bool tolerant ) : string	If there are any environment variables (in the form %VAR%) in the input string, replaces them with the values from the environment. This method can be tolerant or intolerant of errors, so: "abc" -> "abc" "abc%windir%abc" -> "abcC:\WINDOWSabc" "abc%abc" -> exception (intolerant) or "abc%abc" (tolerant) "abc%nosuchvar%abc" -> exception (intolerant) or "abc%nosuchvar%abc" (tolerant) "abc%windir%abc%" -> exception (intolerant) or "abcC:\WINDOWSabc%" (tolerant) Calling this method with "false" for tolerant matches the previous behavior. Methods like File.Exists do not parse environment variables, so this method should be called before attempting to use filenames etc.
ToString ( ) : string	Returns the config file name and app name./>.

Protected Methods

Method	Description
Config ( string configFileName, string appName, XmlDocument configXml, bool treatMissingFileAsEmpty ) : System	The default behavior of Config is to throw an exception if the config file does not exist. This constructor allows a child class to override that, in which case a missing file will be treated as though it were empty (no values loaded, but no exception thrown).
Config ( string configFileName, string appName, XmlDocument configXml, bool treatMissingFileAsEmpty, string>.IDictionary paramsByComponent, string>.IDictionary orderedParamsByComponent, string>.IDictionary outerXmlByComponent, string>.IDictionary innerXmlByComponent ) : System	This signature lets a child class provide more complicated or specific types of collections. Reminder: You probably want to use CaseInsensitiveStringComparers in your dictionaries!
MakeParameterCollection ( ) : string>.IDictionary	This is a ugly hack at the moment. This allows child classes to override the internal type of collection we use. This will be removed when we refactor the architecture to have an abstract base class so we can have a "writeable" version of Config that does not conflict with the implementation of this "readonly" Config.
ReThrowException ( string msg, object paramList, Exception orig ) : void	All the checks for null are because there was an issue where something about a caught exception was null, which caused the error handling code to bomb. Since error handling code is the worst place to bomb (you lose the original exception), to be safe we manually convert null values into "null" strings.

Private Methods

Method	Description
ParseConfigXml ( ) : void	Reads the XML and populates the various attributes based on it (lists of params, dictionaries of params, etc).

Method Details

ClearConfigCache() public static method

Allows you to explicitly remove a config from the cache, for example during unit testing, or any time when you know the config file in the cache is no longer valid.

public static ClearConfigCache ( string appName ) : void
appName	string	Identifies which config file we want.
return	void

ComponentExists() public method

Method to check if a config section exists for a component, prior to calling GetConfigXml or GetParametersAsHashTable (which throw exceptions if you request an invalid component name).

public ComponentExists ( string component ) : bool
component	string	The component or section of the config file, used to /// locate the parameter.
return	bool

Config() public method

Constructs a config class given the "appName", or the key to look up in the app/web.config's "appSettings" section. The value for that key is the path to the config file we're interested in.

public Config ( string appName ) : System
appName	string	Identifies which config file we want.
return	System

Config() public method

Construct a config directly from an XML document rather than from a file.

public Config ( string appName, XmlDocument configXml ) : System
appName	string	App name (I.E. config file name or whatever), used for logging.
configXml	System.Xml.XmlDocument	The XML containing all the config information.
return	System

Config() public method

Constructs a config class given a specific config file to load.

public Config ( string configFileName, string appName ) : System
configFileName	string	The file name of the configuration file to load.
appName	string	Since the config file is specified, this app name is just /// used for identification in log/error messages.
return	System

Config() public method

Construct a config class. The app name is used for logging, and to get the config file name if the file name was not specified and the XML was not passed directly. If you provide the XML, the app name is just used for logging, and the filename is stored but not used for anything (and may be blank).

public Config ( string configFileName, string appName, XmlDocument configXml ) : System
configFileName	string	The file name of the configuration file to load.
appName	string	App name (I.E. config file name or whatever), used for logging.
configXml	System.Xml.XmlDocument	The XML containing all the config information.
return	System

Config() protected method

The default behavior of Config is to throw an exception if the config file does not exist. This constructor allows a child class to override that, in which case a missing file will be treated as though it were empty (no values loaded, but no exception thrown).

protected Config ( string configFileName, string appName, XmlDocument configXml, bool treatMissingFileAsEmpty ) : System
configFileName	string	The file name of the configuration file to load.
appName	string	App name (I.E. config file name or whatever), used for logging.
configXml	System.Xml.XmlDocument	The XML containing all the config information.
treatMissingFileAsEmpty	bool	If true, a missing config file will not cause an exception.
return	System

Config() protected method

This signature lets a child class provide more complicated or specific types of collections. Reminder: You probably want to use CaseInsensitiveStringComparers in your dictionaries!

protected Config ( string configFileName, string appName, XmlDocument configXml, bool treatMissingFileAsEmpty, string>.IDictionary paramsByComponent, string>.IDictionary orderedParamsByComponent, string>.IDictionary outerXmlByComponent, string>.IDictionary innerXmlByComponent ) : System
configFileName	string	The file name of the configuration file to load.
appName	string	App name (I.E. config file name or whatever), used for logging.
configXml	System.Xml.XmlDocument	The XML containing all the config information.
treatMissingFileAsEmpty	bool	If true, a missing config file will not cause an exception.
paramsByComponent	string>.IDictionary	The dictionary that will hold the parameters keyed by component.
orderedParamsByComponent	string>.IDictionary	The dictionary that will hold the parameters in order from the file, keyed by component.
outerXmlByComponent	string>.IDictionary	The dictionary that will hold XML chunks from the file, keyed by component.
innerXmlByComponent	string>.IDictionary	The dictionary that will hold XML chunks from the file, keyed by component.
return	System

Equals() public method

Two Configs with the same config file and appname are Equal.

The parameter is null.

public Equals ( object obj ) : bool
obj	object	The to compare with the current .
return	bool

GetConfig() public static method

This allows you to avoid reading the same config file over and over again. Since Config objects are read-only, we can read the file once and hand the same object out over and over without worrying about threading issues.

public static GetConfig ( string appName ) : Config
appName	string	Identifies which config file we want.
return	Config

GetConfigInnerXml() public method

Gets you the XML section for the component, allowing you to do any special parsing that may be necessary. This includes ONLY the children of the "component" tag, and will not have any text included in that tag.

public GetConfigInnerXml ( string component ) : string
component	string	The component or section of the config file, used to /// locate the parameter.
return	string

GetConfigXml() public method

Gets you the XML section for the component, allowing you to do any special parsing that may be necessary. This includes the "component" tag, and any text included in that tag.

public GetConfigXml ( string component ) : string
component	string	The component or section of the config file, used to /// locate the parameter.
return	string

GetHashCode() public method

Hash code, based on the config file name and app name.

public GetHashCode ( ) : int
return	int

GetParameter() public method

Returns the config parameter for the given component. Throws an exception if there is no such parameter. If you want to know if the parameter exists, call ParameterExists(...).

public GetParameter ( string component, string parameter ) : string
component	string	The component or section of the config file, used to /// locate the parameter.
parameter	string	The name of the config parameter.
return	string

GetParameter() public method

Similar to GetParameter, except rather than throwing an exception if a parameter doesn't exist, returns the default value.

public GetParameter ( string component, string parameter, string defaultValue ) : string
component	string	The component or section of the config file, used to /// locate the parameter.
parameter	string	The name of the config parameter.
defaultValue	string	Value to return if the parameter doesn't exist.
return	string