Project Description

ConfigGen is a .Net tool used to generate configuration files based on a template file and a spreadsheet of settings, one row for each server or environment. It is written in C#/.Net 4.0, and aims to free developers from having to maintain multiple copies of their config files.

Overview (or "why do I need ConfigGen?")

ConfigGen aims to relieve the burden of having to manage different copies of your configuration files for each machine or environment that your application is deployed to. Rather than having to manually maintain copies of files for developer workstations, integration environments, uat servers, production servers, etc, ConfigGen reduces the problem to a single template (the core of your configuration file) together with a settings spreadsheet that contains the individual settings for each machine or environment.

At it simplest, the template file is your existing configuration file where the values that vary between machines are replaced with tokens, and the spreadsheet is a tabulated view of the value of these tokens for each machine. ConfigGen also allows the structure of the configuration file to vary between environments.

So why do you need it? Here are a few reasons:

  • You can see all the different configuration settings for all your environments and machines tabulated in a single spreadsheet
  • When your configuration file is changed, it only needs to be changed in one place.
  • The tabulated view makes it easy to spot missing configuration data for certain machines: no more deploying to UAT, only to find your app fails due to a config change that was applied to your dev boxes only.
  • ConfigGen warns if any inconsistencies are found between the template file and the settings spreadsheet.

How it works

Taking a simple example first - imagine we have a configuration file that has a single setting "EnvironmentName" that varies on each machine that the application is deployed to:

Template file

<?xml version="1.0" encoding="utf-8"?>
    <add key="Environment" value="[%Environment%]" />

Settings spreadsheet - xls/xlsx/csv


By default, ConfigGen will generate 5 configuration files for the above combination, one for each machine specified. Each one will have the appSetting value for "Environment" set according to the value in the spreadsheet. Why "by default"? Because the behaviour of ConfigGen may be altered using various command line switches!

For the second example, a change in configuration file structure is examined:

Template file

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:cg="">
    <add key="Environment" value="[%Environment%]"/>
    <customErrors cg:applyWhen="$CustomErrorMode = 'Off'"
    <customErrors cg:applyWhen="$CustomErrorMode != 'Off'"
      <error statusCode="500"

Settings spreadsheet - xls/xlsx/csv


Hopefully self-explanatory, you can see that there are two different forms of the "customErrors" node. The applyWhen attribute allows different versions to be switched in or out depending on a conditional check against a setting from the spreadsheet.

Downloading and building

Getting started is simple; download the source code package, and build the project in Visual Studio 2008 (or higher) using the solution file provided. This solution file contains a project, ConfigGen.ConsoleApp, which compiles to an executable, cfg.exe. This is the configuration generation tool.

Running ConfigGen

Once you have compiled ConfigGen and created a settings spreadsheet (in csv, .xls or .xlsx format only at the moment folks) and a configuration template file, ConfigGen can be run from the command line:


This will assume a template file called App.Config.Template.xml and a settings spreadsheet file called App.Config.Settings.xls, in the current directory. A directory will be created, called Configs, and configuration files will be created, each in its own machine named subdirectory, for each machine.

This default behaviour can be overriden using the various command line switches. For more information, type cfg.exe --help at the command line:

ConfigGen v0.2.5.5 - Configuration file generation tool
Copyright (C)2013 - Rob Levine and other contributors -

USAGE: cfg.exe [options]


-o <output-directory>
 or --output-directory <output-directory>
    specifies the output directory into which to write the generated config files.
    If this directory does not exist, it will be created.

-s <settings file>
 or --settings-file <settings file>
    specifies the settings spreadsheet file containing config gen settings (csv, .xls or
    .xlsx only)

-t <template file>
 or --template-file <template file>
    specifies the xml template file.

-d <default settings file> (new)
or --default-settings-file <default settings file>
specifies the path to a global defaults file for commonly used settings.
These are merged with the settings file as a pre-generation step, resulting
in a hybrid settings file that is processed in the usual way. If a setting
appears in both this default settings file as well as the local settings
file, the local value will override the global default.
-e or --error-on-warnings Causes the program to exit with a non-zero exit code (an error) if any warnings were raised during configuration generation. -f or --flat-output Outputs the generated configuration files in a flat directory structure, as opposed to one one subdirectory per file. -m or --machine-suffix specifies that each generated config file should be suffixed with the machine name to which it pertains. For example, an App.Config for machine DevServer1 would be output as App.Confing.DevServer1 -i or --inhibit-write Inhibits the actual writing of the generated config files, allowing a 'preview' of the process without overwriting exisitng files. -w or --write-unchanged Instructs the generator to write out configuration files, even if their contents has not changed. -v or --verbose Writes verbose logging to the console during execution -l or --local-only Causes only a configuration file for the local machine to be generated. If an entry in the spreadsheet matches the local machine name, it us used; otherwise an entry in the name of "default" is used instead. -g <comma-seperated-machine-list> or --generate-specified-only <comma-seperated-machine-list> specifies a list of machines, comma seperated without spaces, for which to generate configuration files.
Note: Cannot be used with --filter-machines-regex

-fmr <string> or --filter-machines-regex <string> specifies a Regular expression to identify machines in the settings document,
for which to generate configuration files.
Note: Because of the syntax of regex, you should surround the string with double
quotes, or on the command line, escaped quotes: &quote;<string>&quote; Otherwise,
the greater than symbol will be interpreted by the command line as a redirect.
Note: Cannot be used with --generate-specified-only
-n <filename> or --force-name <filename> Forces the filename of the any generated config files, ignoring the name specified in the settings spreadsheet -p or --pretty-print causes the generated xml to be pretty-printed. This is especially useful for heavily attributised configurations where a single element may contain many attributes and consist of a very long line. NOTE: This setting has been deprecated - pretty print preferences should now be set via the configuration template itself (in the preferences section). However, this setting will override the setting in the configuration template. -ppll <line-length> or --pretty-print-line-length <line-length> sets the maximum line length while pretty printing. This setting must be used in conjunction with the pretty print option, -p / --pretty-print. NOTE: This setting has been deprecated - pretty print preferences should now be set via the configuration template itself (in the preferences section). However, this setting will override the setting in the configuration template. -ves <empty-string-value> or --value-empty-string <empty-string-value> specifies the value to be used in the spreadsheet to represent an empty string being specified for a token. -vn <null-value-string> or --value-null <null-value-string> specifies the value to be used in the spreadsheet to represent a null (no value) being specified for a token. -str or --skip-token-replacement Skips the token replacement phase of config generation, thus just processing the raw xml template but leaving the tokens in the output -dso or --dump-settings-only Causes the program to write it's settings to a file, specified by -dsf or -dump-settings-file (one of which is compulsory if this setting is used), and exit. -dsf <dump settings file> or --dump-settings-file <dump settings file> specifies the file into which the configgen settings should be written. This setting is ignored unless -dso or -dump-settings-only is also specified cfg.exe with no options is equivalent to: cfg.exe -s App.Config.Settings.xls -t App.Config.Template.xml -o Configs -ves "EmptyString"

Last edited Oct 28, 2013 at 9:00 AM by dysondan, version 66