Configuration in EPiServer CMS 5 R1

Product version:

EPiServer CMS 5 R1

Document version:

1.0

Document creation date:

28-06-2007

Document last saved:

12-09-2007

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. This text points out what has changed and how to use these changes in code as well as in configuration files.  

Table of Contents

Web.Config

In previous versions of EPiServer, the EPiServer-specific settings were located under the AppSettings block in the Web.Config file. These have been removed. Instead of using the AppSettings collection with brackets and a string (where you could type virtually anything, meaning there was no guaranteed result until you actually tried it) EPiServer CMS settings are now accessed through the use of a configuration class. All settings are typed members of this class, which gives the added 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 applicationId="/LM/W3SVC/1/ROOT" 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.

If you do not know the application ID, enter any incorrect value and navigate to your site. You should get an error message informing you that the site could not be found - for example:  

The site element with applicationId "/LM/w3svc/1/ROOT/EPiServerSample" could not be found in the configuration file.

The message also contains the complete path to your site.

Within the <sites> collection there is a <site> element for each site that uses this configuration file (enterprise). Find a node named site, where the instance ID is the ID of your specific site. If you do not know the ID, you can use the free tool Metabase explorer to find it (Metabase Explorer at Download.com). Navigate to the section "/LM/W3SVC/". Listed under this section you will find all your sites and their corresponding IDs, see the following image.

 

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.

Connection Strings

In EPiServer CMS 5, you have the option to define several different strings to connect to several different databases. The strings have been moved from Web.Config to a new file called Connectionstrings.config.

Enterprise Configuration

According to the old model, each site inherited some basic settings from a base site. If a site had specific needs of configuration, you had to override the settings for that site. This lead to a messy system where it was difficult to get a good overview of how each site worked.
Therefore, inheritance has been removed. Each site now has its own <site> element and consequently a separate <siteSettings> element. Every required attribute needs to be set for every site. This leads to a more intuitive administration and gives a better overview of how each site is actually configured.

List of Web.config 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.

Available Settings

Name

Description

enableEvents: Set to false to disable the EPiServer Events System. See the EPiServer CMS Event Management System Specification technote 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 EPiServer CMS Event Management System Specification technote for more information about this setting. Default value (if the tag does not exist) is false.
enableScheduler: Set to false to disable EPiServer's connection with the scheduler. Default value (if the tag does not exist) is true.
eventSubscriberUrl: Defines the event subscriber URL for the site in the EPiServer Events System. It must be a Windows Communucation Foundation URL. This setting is required if enableRemoteEvents is set to true. See the EPiServer CMS Event Management System Specification technote for more information about this setting.
globalErrorHandling: Set whether to use EPiServer's 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. Recommended setting is 1 hour
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.
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
pageFolderVirtualPathProvider: Name of the VirtualPathProvider that is responsible for handling of page folders.
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 CurrentCulture if handling pages remote.
siteShortName: The site name that is used when communicating with other EPiServer sites.
stringCompressionThreshold: Set to the number of characters when compression should be activated.
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 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.

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.