HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Configure CMS

Introduces configuration in Optimizely Content Management System (CMS), and describes the configuration files and their structure in the Optimizely platform, including the different files and elements used for storing configuration settings and the hierarchy within them.

Microsoft Security Advisory CVE-2023-33170: .NET Security Feature Bypass Vulnerability## Configuration files

When you install the Optimizely platform, it places files that contain configuration data, connections, and log features in the wwwroot folder in each Optimizely Content Management System (CMS) and Optimizely Customized Commerce Manager websites. 

  • web.config – The main configuration file for the website application contains configuration for the ASP.NET API and the CMS API. Optimizely Customized Commerce also has a web.config file for the back-end Optimizely Customized Commerce Manager site.
  • episerverLog.config – Contains settings for logging with log4net used by CMS and Optimizely Customized Commerce.



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

You also may find the following configuration files in a CMS installation:

  • module.config – A configuration file installed with the CMS sample templates that shows how to deploy new modules to your solution.
  • Web.Debug and Web.Release – Configuration transformation files created by Visual Studio to deploy solutions requiring configuration changes.

You also may have feature-specific configuration files in the solution folder structures for CMS and Optimizely Customized Commerce.

Configuration hierarchy

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

The web.config file is separated into sections containing settings for a specific application part, usually based on namespaces. For example, the <system.web> section stores the settings used by the classes in the System.Web namespace. A list of section definitions at the top of web.config tells ASP.NET what sections this application uses in addition to the sections inherited from machine.config. The definitions also tell ASP.NET what class to use when you create the object representation of the section.

Access configuration settings programmatically

Access configuration settings programmatically through static instances of each configuration section class, such as EPiServer.Configuration.Settings.Instance. You should access services requiring settings through feature-specific options classes. CMS maps relevant configuration settings to the related option's value during the application's initialization. As such, these classes separate the application's configuration and determine how services consume settings. CMS registers option classes in the service container, and you can inject them into any service that requires this information. You can also modify option values during the configuration phase of the application initialization.

public void ConfigureContainer(ServiceConfigurationContext context) {
  context.Services.Configure<DataAccessOptions>(o => o.UpdateDatabaseSchema = true);

You can find more detailed information on individual options classes under the relevant feature section.

Configuration syntax

The configuration files are in XML format and divided into sections containing configurations for various system parts. This section describes the typographical conventions for the descriptions of configuring elements and attributes. Each sub-element is described in two ways: a pseudo XML structure that shows the hierarchy and includes attributes and tables that describe each element's attributes.

Pseudo XML structure

  • The type of the attribute value displays as the value, such as stringAttribute="string".
  • Elements and attributes display in alphabetical order.
  • An ellipsis (...) indicates element collections at the same level as the repeatable element.
  • Parentheses indicate (Obsolete elements and attributes).


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

Attribute tables

Descriptions of attributes display in table format; one table for each element.

  • Attributes display with name, default value, and description.
  • Attributes display in alphabetical order.
  • An empty Default Value column indicates no default value.

<requiredElement> element attributes

Name Default Value Description
(obsoleteAttribute) Description of obsoleteAttribute.
optionalAttribute This is the default value Description of optionalAttribute.
requiredAttribute Another default value Required. Description of requiredAttribute.

Configuration elements