Setting up Your Sitecore Project To Use Config Transforms

In today's post, I'm going to talk about config transforms in Sitecore to help promote continuous integration. To run a Sitecore website, a lot of config file configuration is required. In Sitecore 6 the ability to use 'include' files were introduced to help developers manage change in the section. This was a great step forward but also raised the question of how do you transform values outside of the section. Some of the solutions in this post rely on TDS to be installed. TDS is a licensed deployment product for site, more information about it can be found from, here. There are two considers you have to think about when dealing with transforms and Sitecore. First, is an understanding about how Sitecore configs are split up. Using config transforms is a staple of any standard .NET project but in Sitecore things might not work as you first expect. Out of every CMS system I've encountered, Sitecore by far uses the most amount of config files. There are so many that I'm fairly confident no developer will (or would want to) understand exactly what each one does. Instead of having one mega config file Sitecore has split the config files into smaller chunks that you can find in the 'App_Config' folder. It's very standard in Sitecore to have 40+ config files. When the application loads, Sitecore combines all these config files together to create one giant config file. The key thing to note is that Sitecore does this. This hasn't been done via Visual Studio, a build script or anything else. This means the way transforms are done for Sitecore do not work the same as other .NET solutions. The second consideration about config files surrounds upgrading. On a normal web project, it is very common to have all your config settings and changes in your web.config file and the use a few transforms to deal with a handful of different environment level settings. When you upgrade Sitecore from 7.2 -> 7.5, or, 7.5 -> 8.0 for example, as part of the upgrade process you will need to make a number of config changes to the web.config. As the Sitecore web.config is pretty large and complex the easiest way to upgrade is to use the default Sitecore web.config for the version you want to upgrade to and then re-merge your custom changes back in. For this reason, when using Sitecore, it is recommended to keep your web.config as simple as possible and to add any customization as config includes in your 'App_Config' folder. This makes the upgrade merge as simple as possible.

File Replacement

A very simple approach for dealing with different config files is to create an 'App_Config' folder for each of your environments. TDS has an option to do this for us. In your solution, if you right click on your TDS project to open up the context menu and select 'Properties' the TDS properties dialog should load: tds_config_transforms If you click on the 'File Replacement' tab, you can select a configuration type, set a folder source location and set a target folder location. This approach does allow you to customize your config files per environment, but, in my opinion, it's a lot of overkill for something that should be pretty simple. When you replace a whole folder you needed to have whole copies of files. When you need to upgrade you need to deal with 3 or 4 times the amount of files. I try to follow the DRY (Don't Repeat Yourself) principle on all aspects of development, so duplicating config files isn't that appealing.


Transforms make life a lot easier, instead of having to duplicate whole files, you can replace a handful of environment based properties within each file instead. Using transforms, you don't modify or change the original file but have environment based config files to store the different data. As the changes are stored outside of the original file, this passes the upgrade requirement of not modifying the web.config too much. With Sitecore and Visual studio in order to use a transform, a developer would have to use web deploy in order to do the transform. As of version 4 of TDS config transformations have been included within the Visual Studio build process. This is a great benefit as it means you can deploy your solution completely with TDS and not have to go via web deploy or any other external program. This means you can use Visual Studio out of the box with something like Slow Cheeta. If you haven't used Slow Cheeta I've talked about it a few times, more information can be found in, Configuring SlowCheetah to transform your web.config in your MSBuild script. Using TDS 4 means you can now perform transforms on your Sitecore include files as well.

Crash Course In Transforms

First, install Slow Cheeta, in Visual Studio right click on your solution in 'Solution Explorer' and select 'Manage Nuget packages For Solution' slow_cheeta_sitecore Type 'SlowCheetah' into the browse section and then install it against your web project. slow_cheeta_sitecore_1 Next, you need to install the SlowCheeta Visual Studio extension. Select 'Tools' -> 'Extensions and Updates' slow_cheeta_sitecore_2 Type in SlowCheeta in the search bar, click 'Install' and you are ready to start transforming. slow_cheeta_sitecore_1 In your 'App_Config' folder, right click on the file you want to perform a transform on and select 'Add Transform'. This will add in variations for each configuration build you have set-up in your project. slow_cheeta_sitecore_3 In here you can now add in your transforms. Below lists some of the more standard transform commands: Replace on a name
    <setting name="MailServer" value="" xdt:Transform="SetAttributes" xdt:Locator="Match(name)" />
Replace on a key (App Setting)
  <add key="Setting" value="Value"  xdt:Transform="SetAttributes" xdt:Locator="Match(key)" />
  <add key="Setting" value="Value" xdt:Transform="Insert" />

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top