Transforming config files using SlowCheetah

It’s not unusual for our applications to require different configuration files (whether App.config or other) which might reflect different environments or build configurations. Under such circumstances I’ve tended to stick to using (good old) Nant to switch tokens in my configuration files as and when required.

An alternative to Nant or Cake etc. is Microsoft’s SlowCheetah, which allows us to create transformations within our configuration files, whether XML or JSON based as part of the build process within Visual Studio. These files will be named after the build configuration that you build your project with, i.e. Debug, Release etc.

To try this out, we first need to install SlowCheetah. So from Tools | Extensions and Updates, search for SlowCheetah and download it – you’ll need to restart Visual Studio to get it to installed.

Once installed we can right mouse click on the App.config and should see the option Add Transform.

Note: When we first add a transform Visual Studio will ask you to install the SlowCheetah NuGet package, select Yes when prompted.

Once you’ve executed Add Transform against the App.config you’ll find child nodes in solution explorer for App.Debug.config and App.Release.config (and any other build configurations you have).

If you right mouse click on either of these new config files, the context menu should show the option to Preview Transform. As the name suggests, this allows us to see what the transform will look like instead of having to build our solution to view the App.config within the bin folder.

Transforming .config files

In our simple implementation/example, we’ve got three App.config files now. The original App.config (which is ultimately what we’ll see in the bin folder as the exe.config) and a version of this file for Debug and Release builds.

What we need to do is add some configuration into the App.config as normal, so for example add the following

<appSettings>
   <add key="environment" value="NONE" />
</appSettings>

We can now add configuration to the Debug and Release config files to override this value. To save on duplicated config let’s concentrate on the App.Debug.config, so when we build using the Debug configuration SlowCheetah will transform our App.config with instructions from the App.Debug.config. Here’s an update to the App.Debug.config file

<appSettings>
   <add key="environment" value="DEBUG" 
      xdt:Transform="Replace" 
      xdt:Locator="Match(key)" />
</appSettings>

Note: the syntax for XML transformations is taken from XDT and for JSON from JDT.

As you can probably work out for yourself, we’re telling the transformation engine to replace the value for the given key. Without these two attributes no transformation takes place. Just adding configuration to this file, i.e. if we added another key/value solely to the App.Debug.config, will simply be ignored unless we tell the transformer what to do. For example if we wanted the App.Debug.config build to insert/add a new app settings key/value we can tell the transformer to do this using

<add key="url" 
   value="http://somewhere.com" 
   xdt:Transform="Insert"/>

Transformation syntax for XDT can be found here Transform Attribute Syntax.

Transform attributes include

  • Replace
  • Insert
  • InsertBefore
  • InsertAfter
  • Remove
  • RemoveAll
  • RemoveAttributes
  • SetAttributes

Transforming .json files

We may be using JSON files for configuration or support files (for example when creating .NET core applications or in any other type of application). SlowCheetah allows transformations on JSON as well using JDT.

Let’s add a JSON file to our test application, mine’s named Config.json and includes the following 

{
  "appSettings" : {
     "environment" : "None" 
  }
}

Now in solution explorer within Visual Studio, right mouse click on Config.json and select Add Tranform. Again we’ll concentrate solely on the Config.Debug.json file that’s created as part of this process. Add the following to this file

{
  "appSettings" : {
    "@jdt.replace" : {
      "environment" :  "Debug" 
    } 
  }
}

As I’m sure you can see, we’re aiming to replace the value of the environment key to Debug (as we did with the .config previously). Obviously to see this happen and output to the relevant bin folder, select the Config.json (parent node) and set its property Copy to Output Directory to Copy if newer, now select each of the child nodes and switch those back to Do not copy as Visual Studio will set the child nodes to the same build action as the parent and we do not want/need these environment configurations in our output folder.

JDT includes the following verbs

References

SlowCheetah
SlowCheetah on GitHub