Using config transforms for EPiServer settings

UPDATE: I've now figured out how to apply config transforms to the <episerver> element without removing the xmlns attribute.

Managing build-specific configurations

In an earlier post on EPiServer Template Foundation I presented how we (used to) manage different configuration files for different build types in Visual Studio.

I was under the impression that build-specific configuration files was part of the ASP.NET 4 project model, but as Frederik Vig pointed out it’s actually part of MSBuild 4 and thus available for earlier ASP.NET versions, too (such as ASP.NET 3.5 in this case).

Joel Abrahamsson presented another approach for managing different configurations using Phantom, but here’s how I did it for an EPiServer project using build-type specific configuration transforms in Visual Studio 2010.

Set up additional build types (optional)

First, create any additional build types you might want to use through the Configuration Manager (build types Debug and Release are standard, but we usually have at least one more called Staging aimed at the test environment):

Add config transform files

Second, right-click the web.config file and click Add Config Transforms:

This will create additional configuration files (one for each build type):

I choose to delete web.Debug.config – the original web.config will be our debug configuration and we’ll simply define the configuration parts that differ from the debug configuration when deploying to the staging or release environments:

Transforms occur when deploying

The actual transforms occur when you publish the site or create a deployment package:

So, in order to see the final web.config for the different build types you need to publish your site and look at the resulting web.config file.

Update: We usually apply config transforms on every build. This can be done by using the TransformXml task in MSBuild. An example of this is mentioned in this post on applying config transforms to episerver.config.

Config transforms for episerver.config

It seems config transforms by default only work for web.config, not for other types of .config files (such as episerver.config).

So, I moved the entire <episerver> element from episerver.config into web.config (deleting the episerver.config file) in order to make use of config transforms for EPiServer settings, too.

To make it work I had to remove the namespace attribute from the <episerver> element in web.config…

…making it look like this:

Next I added some transformations to web.Release.config to adjust the EPiServer settings for the production environment:

<?xml version="1.0"?>

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

  <!-- Change the EPiServer connection string -->
  <connectionStrings>
    <add name="EPiServerDB"
      connectionString="Data Source=SQLPROD01;Initial Catalog=dbEPiServer;Integrated Security=False;User ID=myUserId;Password=myPassword;Connect Timeout=10"
      providerName="System.Data.SqlClient"
      xdt:Transform="SetAttributes"
      xdt:Locator="Match(name)"/>
  </connectionStrings>
  
  <!-- Remove "debug" attribute from the <compilation> tag -->
  <system.web>
    <compilation xdt:Transform="RemoveAttributes(debug)" />
  </system.web>    
 
  <episerver>
    <sites>    
        <!-- Change the site description and license file path for the production environment -->
        <site siteId="Hemso.se" 
            xdt:Locator="Match(siteId)" 
            xdt:Transform="SetAttributes"
            description="Hemso Website (Production)"
            licenseFilePath="E:\Licenses\License.config">
        
        <!-- Set the cache expiration -->
        <siteSettings httpCacheExpiration="1:0:0" xdt:Transform="SetAttributes"></siteSettings>   
      </site>
    </sites>
    
    <virtualPath>
      <providers>
        <!-- Set the physical path of the page files VPP on the production server -->
        <add name="SitePageFiles" 
             xdt:Locator="Match(name)" 
             xdt:Transform="SetAttributes"
             physicalPath="E:\Website\Production\VPP\PageFiles" />
      </providers>
    </virtualPath>
  </episerver>
  
</configuration>

What this does

The sample above does the following:

• Removes the debug attribute from the <compilation> element (so we don’t run in debug mode in the production environment)
• Sets the “EPiServerDB” connection string to production database server
• Changes the website description
• Changes the path to the EPiServer license file
• Sets the HTTP cache expiration for EPiServer
• Changes the physical path of the SitePageFiles VPP

These are just examples, there’s definitely a whole lot more that you want to differ between development and production environments.

One thing we like to change is the membership provider so that the WindowsMembershipProvider is used locally and the SqlMembershipProvider is used in the production environment.

Further reading

Further details on web.config transformations are available on the Visual Web Developer Team Blog.

Vote to extend config transform support

Config transforms are currently only available for web projects, but please vote for incorporating config transformations for all configuration files and project types.