This content is archived. See latest version here

Last updated: Mar 25 2013

Introduction

This document describes the structure of the EPiServer CMS configuration, and explains the different files used for storing configuration settings and the hierarchy within them, providing an introduction to configuration in EPiServer CMS and EPiServer Framework.

This document describes the general configuration files of EPiServer CMS and framework. Configuration instructions for specific areas can be found under the Configuration section of the SDK, as well as under each specific area such as Logging and Mirroring, see Configuration Descriptions below.

Refer to the Configuration Syntax section for a description of the syntax used when explaing the various configuration elements.

Configuration Files Overview

The configuration settings of EPiServer CMS and EPiServer Framework are defined in a set of configuration files which are divided into sections containing configurations for various system parts.

  • web.config is the main configuration file for the application. Contains configuration for the ASP.NET API and some parts of the EPiServer CMS API.
  • episerver.config is the main configuration file for the EPiServer CMS API. Contains the basic settings for the EPiServer CMS site (or sites in an enterprise installation).
  • episerverFramework.config contains mapping information describing which host addresses leads to a particular EPiServer CMS site.
  • connectionStrings.config contains a list of database connection strings. You have the option to define several different strings to connect to several different databases.

There are two further configuration 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.

  • episerverLog.config contains the log4net settings for the application, please see Apache.org for full information on configuration options.
  • fileSummary.config is an XForm defining the meta data properties attached to files that are uploaded to EPiServer CMS.

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>
       ...

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 configSource attribute.

XML
<episerver configSource="episerver.config" />

The reason for relocating some sections to separate configuration files is to avoid having a large web.config file.

Note that having separate configuration files for some sections is just the default setup for EPiServer CMS, there is no hard requirement for having separate files. As a result of this there are now more configuration files to keep track of. The basic configuration files containing the ASP.NET and EPiServer CMS APIs are described in the following.

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 site 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.

To locate the settings for a specific site in web.config, scroll to the <episerver> section and find the <sites> element collection.

<episerver>
  <sites>
    <site siteId="MySite" description="Short description of the site">
Note that the <site> element contains a description attribute that makes it easier to locate a specific site in web.config. The siteId attribute is used to distinguish this site when communicating between EPiServer sites, for example, in Enterprise scenarios.

If you have a Single Server License there will be only one site and one config section in your web.config file, while an Enterprise solution will contain several sites.

Configuration Descriptions

The configuration settings for different areas of EPiServer CMS and EPiServer Framework are described in more detail in the following SDK/Developer Guide documents:


Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/