NEWS: ConfigGen has moved to GitHub. Version 2 is under development bringing a host of improvements. Please visit us there.

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"?>
<configuration>
  <appSettings>
    <add key="Environment" value="[%Environment%]" />
  </appSettings>
</configuration>

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="http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
  <appSettings>
    <add key="Environment" value="[%Environment%]"/>
  </appSettings>
  <system.web>
    <customErrors cg:applyWhen="$CustomErrorMode = 'Off'"
      mode="[%CustomErrorMode%]"/>
    <customErrors cg:applyWhen="$CustomErrorMode != 'Off'"
      mode="[%CustomErrorMode%]"
      defaultRedirect="GenericError.htm">
      <error statusCode="500"
        redirect="InternalError.htm"/>
    </customErrors>
  </system.web>
</configuration>

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:

cfg.exe

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 - http://configgen.codeplex.com
--

USAGE: cfg.exe [options]

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