Configuration

Product version:

EPiServer CMS 6.0

Document version:

1.0

Document last saved:

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

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:

Name

Description

web.config

The main configuration file for the application. Contains configuration for the ASP.NET API and some parts of the EPiServer CMS API.

episerver.config

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 adresses leads to a particular EPiServer CMS site. See the episerverFramework.config section in this document.

connectionStrings.config

Contains a list of database connection strings.

You have the option to define several different strings to connect to several different databases.
Note: Having a separate connctionStrings.config is simply something that EPiServer CMS does by default. There is no hard requirement for having it as a separate file, as this is simply controlled by the default ASP.NET configuration settings in web.config

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:

Name

Description

episerverLog.config

Contains the log4net settings for the application, please see the log4net homepage for full information on configuration options.

fileSummary.config

 An XForm defining the meta data properties attached to files that are uploaded to EPiServer CMS

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.

<episerver>
  <sites>
    <site siteId="MySite" description="Short description of the site">

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:

Name

Description

siteDisplayName

The name of the site.

categoryId

Defines ID for the root Category.

pageRootId

ID of the root page.

pageStartId

ID of the page that serves as the start page for the site.

pageWastebasketId

ID of the Recycle Bin.

uiUrl

Defines where the UI files are located.

utilUrl

Path to util directory under application.

siteUrl

Gets or sets the site URL. It must be a Web URL, and include the path to the site root. It is only to be used

 to generate direct references to the site in external locations. For references from a page, use root-relative

URLs and ResolveUrl etc as appropriate.

pageFolderVirtualPathProvider Name of the VirtualPathProvider that is responsible for handling of page folders.

 

Name

Description

licenseFilePath:

This property contains a path to a license file and is added automaticalled when generating a license using the EPiServer Automatic License Management, see the Admin manual for further information. Alternativley it is possible to download a license placing it in the root of the application.

 

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

Name

Description

disableVersionDeletion:

Traceable versions is a new option in EPiServer CMS 6 that disables deletion of page and file versions. Set to true and it will not be possible to delete old page versions.

enableEvents: Set to false to disable the EPiServer Events System. See the Event Management System Specification tech note for more information about this setting. Default value (if the tag does not exist) is true.
enableRemoteEvents: Set to true to enable remote events in the EPiServer Events System. See the Event Management System Specification tech note for more information about this setting. Default value (if the tag does not exist) is false.
enableScheduler: Set to false to disable the EPiServer CMS connection with the scheduler. Default value (if the tag does not exist) is true.
errorMailHandler: Set the relative adress to the page that should handle the posts from the handled error page.
globalErrorHandling: Set whether to use EPiServer CMS error handling. ( RemoteOnly, On, Off )
globalErrorMail: E-mail address that error messages should be sent to.
httpCacheExpiration: Change this value to set the number of seconds a page should be cached, this value will be set in the http request policy. It will activate both client side caching and server caching (outputcache). Policy will only apply to anonymous users and when http request method is GET. The cache will automatically be updated when changes are made to a page in EPiServer CMS. Recommended setting is 1 hour.
httpCacheability

Value to set the HttpCacheability enumeration for the cach.

httpCacheVaryByCustom: The custom values the browser should vary by.
httpCacheVaryByParams: The parameters to the page (i.e. querystring) that the cache should vary by.
indexingDelayAfterPublish: Delay time between publish and indexing.
indexingTextRegExp: The regular expression to index words in pages.
logServiceUrl: URL to the log service.
mirroringFileWriteRetryDelay Delay time between retrying to transmit mirror files 
mirroringHtmlTextEncoding: Sets which encoding should be used when mirroring to HTML.
mirroringRetries: Number of retries when a mirroring job fails.
mirroringRetryDelay: Time until next retry.
pageCacheSlidingExpiration: Page cache interval for local database, set to 0 to disable
pageOfficeStartId: Defines from where the Office plug-in should display the site tree.
pageUseBrowserLanguagePreferences: Used preferred languages from browser as GUI language.
pageValidateTemplate: Sets if the current template has to match the page type template (true|false).
remoteCacheListenerShortNames: A comma-separated list of remote sites that will receive cache notification when a change is made on this installation. Only enter the short name, the definition of URL etc. is made in Admin mode under Remove sites. Useful for Web farms scenarios, and when other data is shared.
remotePageCacheSlidingExpiration: Page cache interval for remote sites, set to 0 to disable.
remoteWebServiceCulture: Set the CurrentThread.CurrentCulture if handling pages remote.
stringCompressionThreshold: Set to the number of characters when compression should be activated.
sgmlParserDecodeCharEntities Defines whether SgmlParser should decode character entitities (like " ") or not.
stringDelayedLoadThreshold: The number of characters when delayed loading should be activated for large strings in properties deriving from Long String.
subscriptionHandler: Defines which class should handle e-mail.
uiDefaultPanelTab: The index of the EditPanel tab that is to be shown by default when clicking a page in the Edit mode pagetree.
uiEditorColors: Defines what colors should be available for the editors.
uiEditorCssPaths: A comma-separated list of relative file paths that define which CSS file(s) to use when rendering the Editor.
uiEditorHeight: Defines the width of the Editor in Edit mode.
uiEditorUnformattingPersistedTags: A pipe-separated list of tags that should not be preserved in "Remove format" action in the Editor.
uiEditorValueOptions: Setting for use of DIV tags or P tags.
uiEditorWidth: Defines the width of the Editor in Edit mode.
uiImageTransparencyReplacement: The color that should replace the transparent color in a picture compression.
uiKeepUserLoggedOn: Sets if the current window's authenticated user must reauthenticate after session timeout.
uiMaxVersions: The maximum number of page versions that EPiServer CMS will retain.
uiOptimizeTreeForSpeed: Set to true if page tree controls should not evaluate if tree nodes have children.
uiSafeHtmlTags: Set which tags should not be encoded, Example format is: b,i,u,br.
uiShowGlobalizationUserInterface: Defines if the globalization user interface should be used.
uiTheme: Application visual layout theme name.
uiVersionMerging: Gets or sets if information on a page should be merged if it has been published while being edited.
urlRewriteExtension: Defines an extension that is mapped to ASP.NET for the URL.
urlRebaseKind Defines the type of rebasing to do for links when using Friendly URLs. 
operationCompatibility Gets or sets the operation compatibility. by default the value is None. The operationCompatibility attribute can have None, Save, Delete or Full value None: There is no Compatibility at all Save: The save operation on Data factory Component can treat as old version of Data Factory Delete: The Delete operation on Data factory Component can treat as old version of Data Factory Full: Both Save and Delete operation on Data Factory component treat as old version

Workflow Settings

Name

Description

workflowDelayedLoading

States if workflow definitions and instance metadata should be loaded at application initialization (false) or at first request of workflow data (true). Default is false.

 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