Basic Template File Format

At its simplest, the file format of the template is just that of a .Net configuration file in which values for substitution are replaced by a token as follows:

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

In the above sample, the token [%MyAppSetting%] would be replaced with the corresponding value for this token from the spreadsheet for the machine config being generated.

Template Preferences

Template preferences allow preferences that affect the rendering of the template to be specified in the template xml, rather than on the command line as switches. The rationale behind this is that you shouldn't have to remember command line switches to get the same template to render out the same each time you use ConfigGen.

Note that the TemplatePreferences section is removed by the configuration file generation process and does not appear in the generated configuration files.

Pretty Print

Pretty print allows a maximum line length to be set for the the generated configuration files. This option is mainly used with heavily "attributised" configurations where an individual element may have many attributes. This leads to very long line lengths when output by the standard XmlWriter in .Net. This setting helps to "pretty print" the output in these situations.
The two pretty-print options (enabled and line-length) can now be specified in the template file. This change deprecates the command line equivalent switches (-p/--pretty-print and -ppll/--pretty-print-line-length) and is now the preferred way of setting template preferences. Note that if the command line equivalents are supplied, they will override the template preferences.
The example below illustrates enabling pretty-print functionality, and setting the line length
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:cg="http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
  <cg:TemplatePreferences>
    <cg:PrettyPrint enabled="true" lineLength="100"/>
  </cg:TemplatePreferences>
  <system.web>
    <!-- my configuration here -->
  </system.web>
</configuration>

Token Start/End Delimiters

Token start/end delimiters can now be changed from their defaults (being [% and %] respectively) using the "Token" template preferences:
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:cg="http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
  <cg:TemplatePreferences>
    <cg:Token startDelimiter="{%" endDelimiter="%}" />
  </cg:TemplatePreferences>
  <appSettings>
    <!-- Note changed start/end token delimiters on the token below. This would normally be [%MyAppSetting%] -->
    <add key="MyAppSetting" value="{%MyAppSetting%}"/>
  </appSettings>
</configuration>

Remove Root Element

This template preferences instructs ConfigGen to remove the root document element from the generated output files. This can be useful for generating non xml files:
<?xml version="1.0" encoding="utf-8"?>
<template xmlns:cg="http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
 <cg:TemplatePreferences>
   <cg:OutputProcessing removeRootElement="true"/>
 </cg:TemplatePreferences>
@ECHO OFF

REM -- THE OUTPUT FROM THIS IS NOT XML --	
ECHO "Hello World: this is [%Environment%]"
</template>

This gives rise to the following example output:
@ECHO OFF

REM -- THE OUTPUT FROM THIS IS NOT XML --	
ECHO "Hello World: this is DEV"

Node Processors

ConfigGen is designed to support the concept of template file "node processors". These are processors that manipulate the contents of the template depending on spreadsheet values for the machine config being generated.
Node processors are (and will be) specified as xml attributes (and probably elements) in the future, all of which are in the custom xml namespace: http://roblevine.co.uk/Namespaces/ConfigGen/1/0/

The applyWhen attribute

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:cg="http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
  <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>

In the above sample a conditional expression is supplied as the value to the applyWhen attribute and it is this that is evaluated to work out whether to include the element on which the applyWhen attribute lives, or not. Note that in the conditional expression, the token is prefixed with a dollar sign.

To test if a token has a value at all, simply specify the token name:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:cg="http://roblevine.co.uk/Namespaces/ConfigGen/1/0/">
  <appSettings>
    <add key="item1" value="[%value1%]" cg:applyWhen="$value1"/>
    <add key="item1" value="default" cg:applyWhen="not($value1)"/>
  </appSettings>
</configuration>

In fact, the underlying process that evaluates these expressions uses XPath. The settings spreadsheet is converted into a particular xml format, and then the conditional expression from the applyWhen attribute is evalutated as XPath against this xml (with the dollar having been removed from the token).

Last edited Jul 27, 2012 at 2:43 PM by dysondan, version 25

Comments

No comments yet.