Thursday, November 14, 2013

Managing Configuration Files With Multiple Developers

The Problem:
This is something that has come up several times now. A client will have a Sitecore instance. There will be multiple developers on the project. There will be multiple environments (local developer machines, QA, Staging, Production, etc.).

How do you keep all the configuration files organized and clean, so developers aren't overwriting each other and each environment gets the correct files?

The Previous Solution:
Up until now, I've usually went with separate projects to keep all the config files organized. Folders for each developer, each environment and any global files that didn't need to be changed. Then I would use TDS's File Replacement to handle copying the required files over to the Website folder on build.

There are several problems with this though. It's somewhat confusing to setup. You end up having to make the same change to multiple config files. It didn't handle instance-wide config files (ones that had to span multiple projects) very well.

The New Solution:
Enter configuration transformations.

Effectively, this will allow you to have 1 master configuration file for each specific config file and create transformations for any specific information that needs to be changed (ie: connection strings for different developers).

Things you will need for this setup...
 * TDS
 * Visual Studio 2012
 * Slow Cheetah, a Visual Studio Extension

For this example we have a very simple solution...

Here you have 2 projects. Your empty Web Application and a TDS project. Delete the Web.config that was automatically added, and add in the Web.config from your Sitecore install.

Next, setup a configuration for yourself in Visual Studio's Configuration Manager.

Right click the Web.config and select the "Add Config Transform" option. You may get a popup about the project having to be reloaded. Make sure you have any changes saved and click "Yes".

You should now see a new configuration transformation added to your project.

This new transformation file is where you add any environment specific changes. For instance, each developer's "dataFolder" might be slightly different. So in the transformation file (ie: Web.Sarkis.config) you tell it to find and set the attribute for the "dataFolder" variable in the Web.Config.

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="">
  <sitecore database="SqlServer">
    <sc.variable name="dataFolder" value="C:\Inetpub\wwwroot\MyCustomInstall\Data\" xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>

    <pages configSource="App_Config\Custom\WebControls.config" xdt:Transform="Replace" />   
You can then preview what your configuration file will look like after all the transformations have been applied to it. Just right click on the transformation file you want to preview (ie: Web.Sarkis.config), and select the "Preview Transform" menu option. As you can see, the "dataFolder" string has been changed to use my personal value.

You can now setup in your Web project any and all config files you might use in your Sitecore project. Just mimic the folder structure you would find in your Sitecore's Website folder (ie: \App_Config\Include), create Configuration Manager settings for any environment you might install to and create transformation files for each of the config files.

Now we use a combination of TDS and Slow Cheetah to get these configuration files to your Sitecore's Website folder on build.

Install TDS and add a TDS project to your solution. In the Configuration Manager, create a custom configuration for the new TDS project. Once this has been done, right click on the TDS project and select "Properties".

In the General tab, you will set the "Source Web Project" to be your Web Application project.

In the Build tab you will set the Web Url of your Sitecore install, as well as your local installation location of the Website folder.

Save these changes.

Next, go to Visual Studio's extensions and updates. From the Tools menu, click the "Extensions and Updates" option. In the "Online" tab search for "slow cheetah", download and install the extension. Normally configuration transformations only take place when you publish a site. This extension allows it to take place on a build.

Once TDS and Slow Cheetah have been setup, just build your solution and the Web.config (and other config files) with the proper transformations applied to it should be copied to your Sitecore Website folder.

If you use TDS' Update Package capabilities, the files in the update package that gets generated will also have the transformations applied to them.

This makes deployment to different environments much easier. Just create a Configuration Manager setting for that environment, create the transformation file that only contains the differences, build the solution and then deploy the update package through Sitecore's Update Installation Wizard.