ConfigManager.Net - App.config and Web.config helper utility

• Download demo project - 47.2 KB
• Download source code - 123 KB

Introduction

In developing ConfigManager.Net, I set out to address the following problems:

• While many of the items in the app.config\web.config file are generic to all team members, some settings, especially in the appSettings and connectionStrings sections, may need to be different.
• The configuration sections of referenced assemblies is not automatically merged into the configuration file of the main application.
• Although it is possible to store the appSettings and connectionStrings sections in external files, the same cannot be done for other sections (e.g., system.ServiceModel).

ConfigManager.Net solves these problems by executing embedded instructions in the app.config. These instructions are stored in the file as XML comments, and executed in place.

Alternatives

Other projects have also sought to address the problem of merging configuration files, including XmlConfigMerge. The most common methods of allowing for different settings among team members are:

Check-in the settings most appropriate for most team members

Developers who need to use different settings must then use a writable copy of the file. The main drawback of this approach is the difficulty of keeping the files in sync. Additionally, every time developers with the writable file gets the latest set of files from the source control, they will be prompted each time to replace the file.

Using the external file features of the app.config\web.config file

The appSettings and connectionStrings sections can include references to external files.

<!-- Reference appSetting in the file localAppSettings.config -->
<appSettings file="localAppSettings.config" />

<!-- Reference appSetting in the file localConnectionStrings.config -->
<connectionStrings configSource="localConnectionStrings.config" />

This approach results in more configuration files that need to be managed and synchronized. It is also limited to the above mentioned sections of the app.config, sections like system.ServiceModel cannot reference external files in the same way.

Using ConfigManager.Net

Valid instructions to ConfigManager.Net must begin with the #ConfigManager.Net# keyword, followed by the instruction type (e.g., ExternalSection), and finally, parameters in the form paramName="paramValue". Properties can be used in these parameters, these properties are discussed later.

All instructions support the special parameter condition. This parameter does a string compare, and only if it evaluates to true is the instruction executed. It takes the form condition="value1==value2" or condition="value1!=value2". For example, to only execute the instruction on the the computer "MyComputer", the condition would be condition="$(Environment.MachineName)==MyComputer".

To run the utility, call:

ConfigManager.exe app.config

The best place to do this is either in the post built event of the project or as part of a build script.

Instructions

EmbeddedSection instruction

XML can be specified within the comments of this instruction. This XML will be added to the configuration file if the condition parameter evaluates to true.

<connectionStrings>
    <!-- You can embed a section based on a condition, such as the user name. -->
    <!-- #ConfigManager.Net# EmbeddedSection condition="$(Environment.UserName)==user"
    <add name="MyConnectionString"
         connectionString="Data Source=localhost;
                           Initial Catalog=MyDatabase;Integrated Security=True"
         providerName="System.Data.SqlClient" />
    -->
</connectionStrings>

Parameter	Mandatory	Description
condition	no	If this parameter evaluates to true, the instruction will be executed.

ExternalSection instruction

This instruction copies the contents (or part of the contents) of an external file into the configuration file. If no value is supplied for the xpath parameter, the entire contents of the file are copied. The file must contain valid XML or XML fragments.

   <!--Copy the appSettings from another app.config file into the current file. -->
   <!-- #ConfigManager.Net# ExternalSection 
      source="alternative.config" 
      xpath="/configuration/applicationSettings/Alternative.Properties.Settings" -->

Parameter	Mandatory	Description
condition	no	If this parameter evaluates to true, the instruction will be executed.
source	yes	The path to the external file.
xpath	no	The XPath expression for the fragment of the file to be copied.

OpenSection instruction

An OpenSection instruction allows a section of the XML file to be kept or removed from the configuration file, based on the condition parameter. The scope of this instruction is from the OpenSection to the corresponding EndOpenSection. If the condition parameter evaluate to false, the XML fragment surrounded by the instruction will be removed from the file. Although the condition parameter is not mandatory, if it is not provided, the instruction will evaluate to true and the XML fragment will not be removed from the file.

<connectionStrings>
    <!-- #ConfigManager.Net# OpenSection condition="$(Environment.UserName)!=fergal" -->
    <!-- You you can remove a section based on a condition. -->
    <add name="RemoveConnectionString"
         connectionString="Data Source=localhost;
                           Initial Catalog=MyDatabase;Integrated Security=True"
         providerName="System.Data.SqlClient" />
    <!-- #ConfigManager.Net# EndOpenSection -->
</connectionStrings>

Parameter	Mandatory	Description
condition	no	If this parameter evaluates to true, the instruction will be executed.

SetValue instruction

Changes a value within the configuration file. This can be the inner text of a node of the value of an attribute.

   <!-- Change the value of the UserName application setting. -->
   <!-- #ConfigManager.Net# SetValue 
      xpath="/configuration/applicationSettings/ConfigManagerDemo.
             Properties.Settings/setting[@name='UserName']/value"
      value="newUser"   -->

Parameter	Mandatory	Description
condition	no	If this parameter evaluates to true, the instruction will be executed.
xpath	yes	The XPath address of the value to be changed.
value	yes	The new value.

Properties

A property can be used anywhere in an instruction. This is done by placing the property name between "$(" and ")" in the instruction. ConfigManager.Net has the following built-in instructions:

Environment.CurrentDirectory	The fully qualified path of the current working directory.
Environment.MachineName	The NetBIOS name of this local computer.
Environment.OSVersion	The current platform identifier and version number.
Environment.SystemDirectory	The fully qualified path of the system directory.
Environment.UserDomainName	The network domain name associated with the current user.
Environment.UserName	The user name of the person who is currently logged on to the Windows operating system.

In addition to these properties, all environment variables are exposed as properties. They can be accessed as Environment.Variable.xxx. To get the full list of properties in the ConfigManager.Net, run: ConfigManager --properties.

Command line properties

Additional properties can be passed into the ConfigManager.Net on the command line:

ConfigManager.exe app.config prop1="value1" prop2="value2" 

Changes

• 2 June 2008 - Changed the utility to produce UTF-8 instead of UTF-16 output.
• 22 June 2008 - Fixed bugs found by oupoi.