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>

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" -->

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>

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"   -->

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:

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.