Configuration Management and EPiServer CMS 6

This blog post is based on the experience of upgrading one EPiServer CMS 5 project and creating a new one from scratch based on a release candidate of EPiServer CMS 6 and things may change before the release.

New configuration files

Web.config contained a lot of settings for EPiServer CMS that is now split into several files. Unfortunately another 250 lines of configuration is also added increasing the burden to manage the configuration.


This file contains mapping between host header name and site and default language. This information was previously located in configuration/episerver/sites/site/siteHosts-tag.

Notice that the EpiServer framework automatically updates this file with machine specific information which makes it harder to put under version control but EPiServer will work even if the file is read-only (you get some exceptions in the log files and maybe temporary version of the files).

It is needed by all developers, staging and QA so one strategy could be to put it on version control directly or check-in a file with another name or location copy it during the post build event.


This is basically everything previously located in configuration/episerver-tag in web.config. It is connected using the configSource attribute in the same way as connectionStrings.config-file.

It contains the same information as before except that siteHosts-tag is migrated to EPiServerFramework.config-file.

In addition to the paths in configuration/episerver/virtualPath/providers/add-tag another machine specific attribute has been added on the site-tag called licenseFilePath.

This file must be put under version control but if the machine specific licenseFilePath it is present it will be hard to get it to work well.

New configuration

There are new sections in web.config and for and episerver.datastore.

You need to add you modules here if you want to add your own things to the new menu system or add gadgets to the new Dashboard.


Even if you do not use the datastore yourself EPiServer does for XForms and other features that was previously handled by the now deprecated objectstore. You need to make sure that you change the connectionStringName-attribute to match the one your site is using.

Since it is possible to have different values on connectionStringName-attribute on configuration/episerver/sites/site/siteSettings-tag in an Enterprise setup this can be problematic.

Change of configuration does not restart application

Both episerver and episerver.framework configuration section has restartOnExternalChanges attrubute set to false.

This is annoying because you have to remember to manually do a iisreset or change web.config to trigger a restart so your changes take effect.

New Site/License Information feature in Admin Mode

There is a new feature that enables you to upload, activate or request a demo license in admin mode. This feature should not be used by developers since it adds machine specific information episerver.config. If you do and check in the changes your co-developers will get a file that does not work on their computer.

My suggestion is to continue using the manual approach and add the Licence.config-file to the application root folder your self. Remeber that if you want to put your license files under version control it is possible to do that very easily because EPiServer will look for “License.config” first and then “MACHINENAMELicense.config” so just rename your license.config-file and check it in.

Location of EPiServer User Interface is changed during upgrade

Notice that all location and VPP paths for EPiServers User Interface are changed during upgrade. If you path to edit mode was /secret/edit before it will now be /secret/CMS/edit. There is no redirect so bookmarks or hard coded links in your application to edit mode may break.

Language files

Notice that you no longer can translate the whole EPiServer User Interface yourself (or override some translations) by changing xml-files in the lang folder. The new Dashboard feature (aka. Shell, Online Center) is using binary resource assemblies.