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:
<?xml version="1.0" encoding="utf-8"?>
<add key="Environment" value="[%Environment%]" />
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:
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:cg=" http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
<add key="Environment" value="[%Environment%]"/>
<customErrors cg:applyWhen="$CustomErrorMode = 'Off'"
<customErrors cg:applyWhen="$CustomErrorMode != 'Off'"
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.
Once you have compiled ConfigGen and created a settings spreadsheet (in .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)2010 - Rob Levine and other contributors - http://configgen.codeplex.com
USAGE: cfg.exe [options]
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 (.xls or
-t <template file>
or --template-file <template file>
specifies the xml template file.
Causes the program to exit with a non-zero exit code (an error) if any warnings
were raised during configuration generation.
Outputs the generated configuration files in a flat directory structure, as
opposed to one one subdirectory per file.
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
Inhibits the actual writing of the generated config files, allowing a 'preview'
of the process without overwriting exisitng files.
Instructs the generator to write out configuration files, even if their contents
has not changed.
Writes verbose logging to the console during execution
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.
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
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: "e;<string>"e; Otherwise,
the greater than symbol will be interpreted by the command line as a redirect.
Note: Cannot be used with --generate-specified-only
or --force-name <filename>
Forces the filename of the any generated config files, ignoring the name
specified in the settings spreadsheet
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.
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.
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.
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.
Skips the token replacement phase of config generation, thus just processing the
raw xml template but leaving the tokens in the output
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
-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"