Using config transforms in Umbraco projects

Nov 9th

In my last blogpost I outlined some of the problems connected with doing team development on Umbraco Projects. A lot of the problems had to do with sharing or not sharing the database the project is running on. Some problems also stems from needing to have a solid setup procedure, as well as a solid deployment procedure.

In the post I'll try to outline and explain how we setup Umbraco Web Application projects at Twins. Our setup is designed to enable the use of Visual Studio to edit all code files in the website: stylesheets, masterpages, javascript, razor scripts, usercontrols and xslt, as well as enabling the deployment of the website from any of the machines used by the developers. Also the setup is designed for having as much of the work done on the project in some kind of CVS. We use TFS, but we could Mercurial just as easily.

We use Web Application projects contained in a Visual Studio solution, which is a prerequisite for using the web.config transformations built into Web deploy function found in Visual Studio 2010. Also Web Application Projects have an associated project file (.csproj), which gives us an opportunity for using MSBuild to automate the deployment procedures.

Config transformations

We use config transforms when we deploy to test, staging and deployment scenarios, and some of us use it for having our own configuration setup (some have a SQLExpress server, others a full-fledged SQL Sever), but we might change that in the future.

Using config transformations requires having solution configurations for each of the deployment scenarios. You can manage your configurations by selecting Build -> Configuration manager which gives you this dialog:

Configuration manager

Every project comes preconfigured with Debug and Release configurations, but you can create as many as you like by selecting the menu item selected in the image, and as you can see, we use our initials to create our own configurations. Configurations are stored in the solution file, and are copied between developer machines with your CVS as long as you keep your solution (.sln), and project (.csproj) files in the CVS.

After creating a solution configuration, remember to leave the Create new project configurations checkbox checked, you can easily create new config transformation files by right-clicking the web.config file and select Add config transforms, this will create any missing config transformation files, which will be named Web.configname.config.

Add config transforms

What to do with config transformations

Config transformations is a set of transformation actions that is applied on the default config file during the project build. In an Umbraco project you'll typically need to change the connection string for the Umbraco database, set the compilation debug attribute to off and the customErrors mode to RemoteOnly, change the smtp settings and perhaps change your Elmah settings (If you don't already use Elmah you should).

Here's a sample transformation file:

<?xml version="1.0"?>
<configuration xmlns:xdt="">
        <add key="umbracoDbDSN"
            value="server=ProdServer;;user id=umbracouser;password=userpassword"
            xdt:Locator="Match(key)" />    
        <mailSettings xdt:Transform="Replace">
            <smtp from="">
                <network defaultCredentials="false" host="" port="25"/>
        <customErrors mode="RemoteOnly"
            xdt:Transform="Replace" />

How about the other config files?

Umbraco comes with a host of other config files, located in the config folder in the root of the website. You might want to have different dashboard setups in your development and production environments, then set up transformations for Dashboard.config. If you use Umbraco standard form handler you'd need to change the smtp settings for that in formHandlers.config. Or if you've configured error page id's in umbracoSettings.config, they might have other id's in production. Then you can change that with config transforms.

To achieve this you can use the SlowChetaah extension for Visual Studio. The extension transforms other config files when publishing the Web Application, and places the resulting files in the output folder. From here you can pick them up using MSBuild.

What did we achieve?

We achieved two goals by using config transforms:

  1. Using different solutions configurations and config transforms we can now easily have different database setups for different developers on different machines. This means that developers can work while offline, if they have some kind of SQL Server on their own machine. And that they can freely try out different doctype and templates setups without affecting the work of other developers before they're ready.
  2. We set up the project in a way that enables every developer on the team to create the artifacts necessary for deploying the site to test, staging and production environments.

Next on the list is determining which files to put in the web application project and setting up the project for easy deployment. This will be the subject for my next post.