Home What's New Properties Command Line Managing Properties MSI Integration Samples Roadmap

 

What is XML Preprocess?

XmlPreprocess is a command-line utility that can modify annotated XML files much like a code preprocessor. It is useful for deploying configuration files to different environments making substitutions such as connection strings. It is easily integrated into almost any script, build tool or deployment package to simplify and centralize your deployment strategy.

Goals

  1. Single source of truth - Avoid maintaining parallel copies of configuration files, templates or transforms of configuration files for each environment. This eliminates the "getting out of sync" problem experienced when developers need to add something to configuration and forget to update it in several places.
  2. Get and Go - Keep the configuration files fully operational right out of source control. Ideally, developers should be able to get the file directly from source control and run without having to touch it up for their local development environment. This is accomplished by decorating the configuration files with non-breaking XML comments that contain instructions for the preprocessor. These comments lay dormant, invisible to the configuration system, allowing reasonable development defaults to be used in the file. The comments are only used by the preprocessor at deployment-time.
  3. Central Configuration Management - Provide a single, central place to manage all configuration settings for the entire system without needing to know anything about where the settings go, nor having to edit XML. The Excel spreadsheet is an easy-to-use tool for anyone, including non-developers to manage all of your configuration settings. If you don’t want to use Excel, version 2.0.15 has added new data sources such as CSV files, databases, and custom data sources where you can store and manage them however you want.

Examples

If you want to turn debug page compilation off when in production, you might do something like this:

(Note: There is a more flexible approach that using replaceable properties that we will discuss in a moment, but this should look familiar since it’s a close parallel to the way code preprocessors work)

<configuration>
  <system.web>
    <!-- #ifdef production -->
    <!-- <compilation defaultLanguage="c#" debug="false"/> -->
    <!-- #else -->
    <compilation defaultLanguage="c#" debug="true"/>
    <!-- #endif -->
  </system.web>
</configuration>

The debug setting will remain true for an unprocessed file, but when this file is deployed using the XmlPreprocess tool with the "production" property defined, the #ifdef condition will be tested, and if true, the comments around its body content will be removed, and the else branch will be omitted entirely. This will render the following:

<configuration>
  <system.web>
    <compilation defaultLanguage="c#" debug="false"/>
  </system.web>
</configuration>

Another powerful way to use the preprocessor is to substitute properties into placeholders in your XML file much like in Ant, NAnt or MSBuild. Properties can be defined in a number of ways including external XML files and Excel spreadsheets or passed on the command line to XmlPreprocess.exe.

For example if you have an application setting that contains the name of a remote server, but the name of that server changes from environment to environment, you may want to mark-up your XML like this:

<configuration>
  <appSettings>
    <!-- #ifdef _xml_preprocess -->
    <!-- <add key="server" value="${remoteserver}"/> -->
    <!-- #else -->
    <add key="server" value="developmentserver1"/>
    <!-- #endif -->
  </appSettings>
</configuration>

Then you can provide the value for the "remoteserver" property at deployment time via the Command Line or external settings file. For more information see Properties.

Last edited Jun 22, 2012 at 10:32 PM by lorenh, version 7

Comments

No comments yet.