This article describes the configuration scheme used by EPiServer CMS.

Configuration hierarchy

Like all ASP.NET Web Applications, EPiServer CMS stores configuration settings in a file called web.config located in the root directory of the application. ASP.NET uses functionality called configuration inheritance, this means that the web.config in your project only contains changes and additions to the configuration found in the machine.config file which is the base configuration for all applications on your machine.

The web.config file is separated into smaller parts called sections. Each section contains settings for a specific part of the application, usually based on namespaces - e.g. the settings used by the classes in the System.Web namespace are stored within the <system.web> section in web.config. At the top of web.config you can find a list of section definitions, these definitions tells ASP.NET what sections are used by this application in addition to the sections inhertied from machine.config. A definition also tells ASP.NET what class to use when creating an object representation of the section. Below is an example of a definition. 

   <section name="episerver.dataStore" type="EPiServer.Data.Configuration.EPiServerDataStoreSection, EPiServer.Data" />

Looking at the list of section definitions you can see that the EPiServer CMS API has several sections in which settings are stored. If you scroll further down in the web.config file you will find the actual instances of the sections where values are assigned to the section properties. 

   <episerver.dataStore>
      <dataStore defaultProvider="EPiServerSQLServerDataStoreProvider">
         <providers>
            ...

Most of EPiServer CMS's sections are stored normally within web.config but if you have a look at the <episerver>, <episerver.framework> and <connectionStrings> sections you will see that they look a bit different. These three sections have been moved out to separate configuration files - the name of the file used by a section can be found in the configSourve attibute. 

   <episerver configSource="episerver.config" />

The main reason for using this approach is because we want to automatically write back information to those sections without causing the application to restart. Normally any change to the web.config file will cause a restart of the application (or applications, if several applications use the same web.config file), but when a section is given a separate configuration file you can specify if a change in that file should trigger a restart or not. If we scroll back up to the section definition for the <episerver> section you can see that we have disabled automatic restart for this section by setting the restartOnExternalChanges attribute to false. 

   <section name="episerver" ... restartOnExternalChanges="false" />

Configuration files overview

Since some sections have been moved out of the web.config file there are now more files to keep track of. The basic configuration files containing the ASP.NET and EPiServer CMS API:s are as follows:

There are two further configuraton files located in the application's root folder. These two configuration files are separate and not related to the files listed above or each other.