Using config transforms in Umbraco projects
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.
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.
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
Build -> Configuration manager which gives you this dialog:
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
new project configurations checkbox checked, you can easily create
new config transformation files by right-clicking the web.config file
Add config transforms, this will create any missing
config transformation files, which will be named
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="http://schemas.microsoft.com/XML-Document-Transform"> <appSettings> <add key="umbracoDbDSN" value="server=ProdServer;database=myweb.net;user id=umbracouser;password=userpassword" xdt:Transform="SetAttributes" xdt:Locator="Match(key)" /> </appSettings> <system.net> <mailSettings xdt:Transform="Replace"> <smtp from="email@example.com"> <network defaultCredentials="false" host="smtp.yourisp.com" port="25"/> </smtp> </mailSettings> </system.net> <system.web> <customErrors mode="RemoteOnly" xdt:Transform="Replace" /> </system.web> </configuration>
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:
- 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.
- 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.