Configuration

Introduction

This document provides an introduction to configuration in EPiServer, and describes the configuration files and their structure in the EPiServer platform, incuding the different files and elements used for storing configuration settings and the hierarchy within them.

General configuration files

When installing the EPiServer platform with CMS and Commerce, you will get a set of configuration files in the wwwroot folder of both the CMS and Commerce Manager websites. These configuration files are used for general configuration of websites, database connections and log features.

Web.config is the main configuration file for the website application. Contains configuration for the ASP.NET API and the EPiServer CMS API. Commerce also has a web.config file for the backend Commerce Manager site.
episerverLog.config contains settings for logging with log4net used by both CMS and Commerce.

Note: Previous releases of EPiServer CMS used the configSource attibute to extract the episerver and the episerver.framework sections into separate files called episerver.config and episerverFramework.config.

You may also find the following configuration files in an EPiServer installation:

module.config is a configuration file installed with the CMS sample templates, as an example of how you can make it easier to deploy new modules to your solution.
Web.Debug and Web.Release are configuration transformation files created by Visual Studio to make it easier to deploy solutions requiring configuration changes.

In addition to these general configuration files, there are other feature-specific configuration files available in the solution folder structures for CMS and Commerce.

Configuration hierarchy

Like all ASP.NET web applications, EPiServer CMS stores configuration settings in the web.config located in the root directory of the application. ASP.NET uses functionality called configuration inheritance, this means that the file 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. For example, 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>
       ...

Accessing configuration settings programmatically

EPiServer CMS settings can be accessed through the use of a configuration class. All settings are typed members of this class, which gives the benefit of being able to see all settings through IntelliSense. Access to the CMS application settings goes through the static object EPiServer.Configuration.Settings.Instance. There is no need to instantiate this class since it is a global static available throughout all of the application.

Configuration syntax

The configuration files are in XML format and are divided into sections containing configurations for various system parts. This document describes the typographical conventions for the descriptions of configuring elements and attributes. Each subelement is described in two different ways: a pseudo XML structure showing the hierarchy and including all attributes and a set of tables describing each element’s attributes in more detail.

Pseudo XML Structure

(Obsolete elements and attributes) written within parentheses.
The type of the attribute value is listed as the value, in other words stringAttribute="string".
Elements and attributes are listed in alphabetical order.
Element collections are indicated by "..." at the same level as the repeatable element.

Example:

XML

<someElement>
    <optionalCollectionElement>
      <add optionalAttribute="valueType"
       requiredAttribute="valueType" />
       ...
   </optionalCollectionElement>
   <optionalElement (obsoleteAttribute="valueType")
       optionalAttribute="valueType"
       requiredAttribute="valueType" />
                <requiredElement (obsoleteAttribute="valueType")
       optionalAttribute="valueType"
       requiredAttribute="valueType" />
 </someElement>

Attribute Tables

More detailed descriptions of attributes are displayed in table format, one table for each element.

Attributes are listed with name, default value and description.
Attributes are listed in alphabetical order.
An empty Default Value column indicates that there is no default value.