Configuration

Introduction

The structure of EPiServer CMS-specific settings in the Web.config file as well as the way site settings are dealt with programmatically have gone through some major changes. Major configuration sections have been moved into seperate configuration files. This text points out what has changed and how to use these changes in code as well as in configuration files.    

Table of Contents

• Configuration Hierarchy
• Config Files
• Setttings Information
  » Required Settings 
  » Available Settings 
  » Workflow Settings

Configuration Hierarchy

Like all ASP.NET Web Applications EPiServer CMS stores configuration settings in a web.config file 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 faultProvider="EPiServerSQLServerDataStoreProvider">
      <providers>
         ...


Config Files

Much 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 differ from other sections. These three sections now exist in three separate configuration files - the name of the file used by a section can be found in the configSource 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 ... restartOnExternalChanges="false" />

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 sections 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:

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

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

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

EPiServerFramework.config file

The new EPiServerFramework is delivered with EPiServer CMS 6. This file contains mapping between host header name and site and default language. This information was previously located configuration/episerver/sites/site/siteHosts tag in the web config.

Note that EPiServer framework automatically updates this EPiServerFramework.config file with machine specific information. Some further information on EPiServer framework configuration in this file see the Initialization technical note.

List of Settings

Required Settings:

Available Settings - refer also Settings Properties in the EPiServer CMS SDK .

Workflow Settings

 For further information about configuration options regarding workflow system, see the Developer's Guide / Workflows / Developing Workflows section in the online EPiServer CMS SDK.

Virtual Path Providers

For information regarding Virtual Path Providers configuration see the technical note Virtual Path Providers in EPiServer CMS 6.

Virtual Role Providers

For information regarding Virtual Roles configuration see the technical note Authentication and Authorization in EPiServer CMS 6.

Enterprise Configuration

Each site has its own <site> element and consequently a separate <siteSettings> element. Every required attribute needs to be set for every site giving an overview of how each site is configured. For information regarding Enterprise solutions see the tech note Configuring EPiServer CMS Enterprise. For information regarding Mirroring see the tech note EPiServer CMS Mirroring 2.0.

episerver.shell

Add custom modules in this section for the menu system and to add gadgets to the Dashboard.

episerver.datastore

This is used for the episerver datastore.

Other Configuration Documents

Active Directory
Enterprise
Image Service
Live Monitor
Quick Publishing
Subscription
Tiny MCE