Web.config Settings
|
Product version: |
EPiServer 4.62 |
|
Document version: |
1.0 |
|
Document creation date: |
07-06-2006 |
|
Document last saved: |
26-10-2007 |
Purpose
Web.config is the configuration file for ASP.NET Web applications and each application has one web.config file that keeps the configurations required. This document describes the main settings in the web.config file.
Introduction
web.config is the configuration file for ASP.NET Web applications and each application has one web.config file that stores the configurations required. The web.config file is written in XML with specific tags having specific meanings.
EPiServer's web.config file is situated in the Web site's root folder.
A number of important settings are stored in the configuration file. Here are some of the most frequently used configurations that are stored inside web.config.
- Database connections
- Session States
- Error Handling
- Security
Document Scope
This document should be read by those who are already familiar with the general functionality of web.config files, but who wish to find out more about the settings in EPiServer's web.config file.
Changes in web.config in 4.62
The following issues affecting web.config apply when upgrading EPiServer sites before EPiServer 4.60 to 4.62. These issues do not apply when upgrading from EPiServer 4.60 or 4.61 to 4.62.
Friendly URL
When upgrading a Web site to EPiServer 4.62, the friendly URL functionality will not function correctly until the following has been added to web.config.
<httpModules>
<add
name="FriendlyUrl"
type="EPiServer.Util.FriendlyUrlModule, EPiServer" />
</httpModules>
Add the following code to the header section of all the templates used in the site, normally located in /templates/units/header.ascx.
<%@ Register TagPrefix="EPiServer" Namespace="EPiServer.WebControls" Assembly="EPiServer" %>
...
<episerver:FriendlyUrlRegistration runat="Server" />
ASP.NET Development Server
The built-in Web server in .NET 2.0 (ASP.NET development server) does not support friendly URL in the default configuration. In order for this to work, you must have an extension that is mapped to ASP.NET for the URL. For example:
<add key="EPsFriendlyUrlExtension" value=".aspx" />
Portal
In order to register the EPiServerPersonalizationProvider you need to add the sections marked in bold below to web.config. This will also give WebAdmins, WebEditors and Administrators permissions to enter shared personalization scope.
<configuration>
…
<connectionStrings>
<add name="EPiServerDB" connectionString="Data Source=SERVERNAME;Database=DATABASE;User Id=USER;Password=PWD;Network Library=DBMSSOCN;" providerName="System.Data.SqlClient" />
</connectionStrings>
…
<system.web>
…
<webParts>
<personalization defaultProvider="EPiServerPersonalizationProvider">
<providers>
<add name="EPiServerPersonalizationProvider" type="EPiServer.WebParts.Core.EPiServerPersonalizationProvider" connectionStringName="EPiServerDB" />
</providers>
<authorization>
<allow verbs="enterSharedScope" roles="WebAdmins, WebEditors, Administrators" />
</authorization>
</personalization>
</webParts>
…
</system.web>
…
</configuration>
In the connection string configuration exchange DATABASE, USER and PWD to the values required for logging in to your database.
The web.config additions above define a connection string that preferably points to the EPiServer database. In order to use your EPiServer database for WebPart personalization you need to update its scheme. Use the following command (available under \%windir% \Microsoft.NET\Framework\v2.0.50727) to update the database scheme.
aspnet_regsql.exe /S SERVER /d DATABASE -E -A mc
Sample templates can be imported from the
<EPiServerSample dir>\Util\Setup\Portal Templates.ep4.
Delayed Loading of Strings
The delayed loading function is not activated by default, i.e. the previous behavior of loading all strings is still active. To activate delayed loading, add the following text to web.config:
<!--
The number of characters when delayed loading should be activated for large
strings in properties deriving from Long String.
A lower value will decrease memory usage but may increase database usage, the
optimial value depends on the amount of content.
Setting this value to 0 will disable delayed loading of strings.
Setting this value to 1 will effectively always use delayed loading.
-->
<add key="EPnStringDelayedLoadThreshold" value="100" />
For further information about the delayed loading functionality, see the following chapter.
Unified File System
From EPiServer 4.60, the following registration in web.config is required for virtual unified file system handlers, i.e. those handled by EPiServer. Registration is done automatically at installation and upgrade. This module is responsible, for example, for making sure that "Documents/MyDocument.doc" is mapped to a file in versioned file system. It should be placed after SpiderSupport, which was previously reponsible for this functionality.
<httpModules>
<add name="SpiderSupport" type="EPiServer.Util.SpiderSupport, EPiServer" />
<add name="UnifiedFileSystem" type="EPiServer.FileSystem.UnifiedFileSystemModule, EPiServer" />
Simple Address
From EPiServer CMS 4.60, the simple address functionality is managed by a separate module and is no longer part of SpiderSupport. In order for simple address to function as in EPiServer CMS versions prior to 4.60, add the following registration to web.config. Registration is done automatically at installation and upgrade.
<httpModules>
<add name="SpiderSupport" type="EPiServer.Util.SpiderSupport, EPiServer" />
<add name="UnifiedFileSystem" type="EPiServer.FileSystem.UnifiedFileSystemModule, EPiServer" />
<add name="ExternalUrl" type="EPiServer.Util.ExternalUrlModule, EPiServer" />
Registering WSRP Portlets
Information about how to register the WSRP producers that are included in the sample site so that they can be consumed can be found in the technical note, "WSRP Configuration".
<location> Element
The <location> element determines the access rights to permit visitors access to different pages of information.
EPiServer CMS uses two main groups by default: WebEditors and WebAdmins. You can also name the Administrators and Everyone groups as default groups. These four groups have different roles and functions on the Web site.
|
Group |
Function |
|---|---|
|
Everyone |
Anonymous visitors to the Web site. All visitors of a public Web site are essentially anonymous. This means that the system cannot identify the visitor. With an intranet, it is possible to link the intranet and login in Windows to allow visitors to be identified. In this case, no visitor is essentially anonymous. |
|
WebEditors |
Web site editors. You can access Edit mode by writing /edit after the address then log into the EPiServer CMS. Web site editors do not have access to Admin mode by default. |
|
WebAdmins |
Web site administrators. You can access Admin mode by writing /admin after the address then log into the EPiServer CMS. Web site administrators also have access to Edit mode by default. |
|
Administrators |
Web site super administrators. To be able to change system settings in EPiServer CMS, you must be a member of this group. |
If you do not want to use the default groups available in EPiServer CMS for accessing Edit and Admin modes, change the settings in web.config.
Change the settings for <location path="admin"> for Admin mode, <location path="edit"> for Edit mode. Change the names of the groups in <allow roles>, using a comma to separate the groups.
<location path="admin">
<system.web>
<globalization requestEncoding="utf-8" responseEncoding="utf-8" />
<authorization>
<allow roles="WebAdmins, Administrators" />
<deny users="*" />
</authorization>
</system.web>
</location>
<location path="edit">
<system.web>
<globalization requestEncoding="utf-8" responseEncoding="utf-8" />
<authorization>
<allow roles="WebAdmins, WebEditors, Administrators" />
<deny users="*" />
</authorization>
</system.web>
</location>
<location path="WebServices">
<system.web>
<authorization>
<allow roles="WebServices,Administrators" />
<deny users="*" />
</authorization>
</system.web>
</location>
<location path="util">
<system.web>
<globalization requestEncoding="utf-8" responseEncoding="utf-8" />
</system.web>
</location>
<appSettings> Element
The <appSettings> element of web.config is where settings needed by an application to perform work, e.g. connection strings, server names, and file paths, are stored. The items inside appSettings are items that need to be configurable depending upon the environment.
Note All items in the <appSettings> element for a site can also be edited in EPiServer CMS Manager.
Database Settings
|
Setting |
Description |
|---|---|
|
EPnCategoryID |
Category ID of the root category. |
|
EPsConnection |
The database connection string. |
|
EPnRootID |
ID of the root folder. |
|
EPnStartPage |
ID of the Web page that serves as the start page for the site. |
|
EPnWastebasketID |
ID of the Recycle Bin. |
General EPiServer CMS Settings
|
Setting |
Description |
|---|---|
|
EPsBackupDevice |
Name of the backup device used to backup the EPiServer CMS database. |
|
EPsCacheListeners |
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 is done in Admin mode under Remote sites. Useful for Web farm scenarios when data is shared. |
|
EPnCachePolicyTimeout |
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 only applies 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 3600 = 1 hour |
|
EPsCacheVaryByCustom |
The custom value that the browser should vary by. It is only possible to set one custom value. |
|
EPsCacheVaryByParams |
The parameters to the page (i.e. querystring) that the cache should vary by. |
|
EPsDefaultLanguageBranch |
Default language that most of your Web site visitors will understand. Used in globalization. See the globalization technical note for further information. |
|
EPnDefaultToolbar |
Defines the type of EPiServer CMS toolbar that should be default for the Web site. Users can change the setting for their own account. Default is set to "0", which is the extended toolbar. Set to "1" for the limited toolbar. |
|
EPfDisableScheduler |
Set to true to disable EPiServer's connection with the scheduler. Default value (if the tag does not exist) is false. |
|
EPsEditControlVersion |
Version number of the ActiveX editor. |
|
EPsEditCSS |
URL of file(s) to be included as style sheet when using the inline editor. Defined either relative to EpsRootDir or as a complete url. For example: value="/styles/editor.css" value="/styles/editor.css,/styles/custom.css" value="http://www.mysite.com/styles/mycss.css" |
|
EPsEditorColorList |
Define your own colors so that they are available from the color drop-down list in the Editor. This function is useful, for example, if you only want the colors from your graphical profile to be available from the Editor. For example value="Scarlet=FF0000,Lime=00FF00,Royal=0000FF" |
|
EPnEditorHeight |
Height of Editor, in pixels. |
|
EPnEditorValueOptions |
This bitmapped setting is mainly for support purposes and contains the following settings: • FullHtmlSource = 1– If this flag is set, the full HTML source will be returned from the Editor rather than just the code between the <BODY> tags. • ParagraphIsDiv = 2 – By default, the Editor inserts <P> tags as paragraph separators when the user presses ENTER. By settings this flag, <DIV> tags are used instead. • PasteModeNonIE5 = 4 – By default, the Editor uses IE5-comptaible paste mode, which means that text from, for example, Microsoft Word pasted into the Editor will use CSS classes to define the formatting behavior. By setting this flag, more specific formatting style definitions are used., resulting in more accurate representation of the original formatting, but will also cause an excessive amount of formatting information. • InsertDialogIsUnicode = 8 – If this flag is set, parameters passed to the insert dialog will be UTF8-endoded. • UseOldLinkTool = 16 – Set this flag to use the pre-EPiServer 4.50 Link Tool. |
|
EPnEditorWidth |
Width of Editor, in pixels. |
|
EPfEnableAlternateFiles |
Set this to true to enable alternate files. For example, to execute your own version of "admin/default.aspx", save your version of the file as "admin_/default.aspx" (note the underscore) and change this setting to true. This setting is disabled by default, because of possible performance issues. It will cause an extra file system hit per Web request. |
|
EPfEnableClearTextPasswords |
Set to false to automatically set passwords to hashed versions. This setting enables backward compatibility. |
|
EPfEnableFriendlyUrl |
Set to true to activate the friendly URL functionality. Controlled by Manage Web Addresses in Admin mode. |
|
EPfEnableGlobalizationSupport |
Set to true to enable support of globalized Web sites. |
|
EPfEPiServer3Compability |
Set to true if EPiServer CMS should forward cache events and system settings to an EPiServer CMS 3 environment. |
|
EPsErrorHandling |
Set whether you want to use EPiServer CMS error handling. • On – Use the EPiServer CMS built-in error handling to hide Exceptions that have not been handled by the EPiServer CMS implementation, i.e. displays "The page could not be loaded…" • Off – Do not use the EPiServer CMS error handling. • RemoteOnly – Use the built-in error handling if the request comes from another machine. If the browser is run directly on the EPiServer CMS machine (e.g. to http://localhost), the error message will be displayed in full. |
|
EPsFriendlyUrlExtension |
The built-in Web server in .NET 2.0 (ASP.NET development server) does not support friendly URL in the default configuration. In order for this to work, you must have an extension that is mapped to ASP.NET for the URL. |
|
EPfHtmlEditor |
Set to true if you want to activate the Editor that was shipped with EPiServer CMS 4.20. Set to false to use the ActiveX Editor. This setting enables backward compatibility. |
|
EPsHostUrl |
Uniform Resource Locator (URL) for the site. For example value="http://userHH1". |
|
EPsLanguage |
EPiServer CMS language settings. |
|
EPnLocale |
This setting is used as a backup if the value set in EPsLanguage is not defined in Edit Languages in Admin mode. The locale ID follows Windows standard. |
|
EPsLocalSite |
This is used when communicating with other systems. Set to a unique short name without spacing. For example, if host name is http://www.episerver.com, the site name could be "episervercom". |
|
EPsMirroringHtmlEncoding |
The name of the encoding to use when writing files created by HTML mirroring. If missing or invalid encoding, UTF-16 is used. |
|
EPnPageCacheTimeout |
The page cache interval (in hours) for the local database. Set to "0" to disable. |
|
EPnQueryTimeout |
Timeout for queries to the database, in seconds. Default is set to 30 seconds. |
|
EPnRemotePageCacheTimeout |
The page cache intervals (in hours) for remote sites. Set to "0" to disable. |
|
EPnRequiredPasswordLength |
Required password length, in characters. Passwords should not be stored as clear-text by default. |
|
EPsSiteName |
The name of the Web site. For example value="TestSite". |
|
EPsSmtpPassword |
Default SMTP password that is used by all built-in e-mail functions. |
|
EPsSmtpServer |
Default SMTP server that is used by all built-in e-mail functions. |
|
EPnSmtpServerPort |
Default SMTP server port that is used by all built-in e-mail functions. |
|
EPsSmtpUser |
Default SMTP user that is used by all built-in e-mail functions. |
|
EPnStringCompressionThreshold |
Set to the number of characters when compression should be activated. Set to 100 (characters), so that strings longer than 100 characters will be candidates for compression, and then monitor CPU and memory usage. Adjust as necessary. Setting this value to 0 will disable compression. |
|
The number of characters when delayed loading should be activated for large strings in properties deriving from Long String. A lower value will decrease memory usage but may increase database usage, the optimial value depends on the amount of content. Setting this value to 0 will disable delayed loading of strings. Setting this value to 1 will effectively always use delayed loading. | |
|
EPsSubscriptionHandler |
Class that is responsible for subscriptions. This value is fetched from System Settings in Admin mode. |
|
EPnUserCacheTimeout |
Timeout limit, in minutes, to keep the user's principal information. |
|
EPnVersionCount |
The maximum number of versions that EPiServer will retain. |
LDAP Configuration Parameters
|
Setting |
Description |
|---|---|
|
EPnLdapAuthenticationType |
A numeric value to select the authentication type. Possible values are: 128 = Simple authentication, i.e. clear text. Add 131072 to force communication over SSL. |
|
EPfLdapAuthenticateWithBind |
If your LDAP server does not support the ldap_compare command to check passwords, set to True to use a second Bind to provide the authentication service. ldap_compare is a much faster operation than performing a bind, so you should set this parameter to False if possible. |
|
EPsLdapDomain |
The domain of the account that you want to use to access information from your Active Directory (AD). For instance MyDomain. If you are using simple authentication, this should be left blank. |
|
EPsLdapPassword |
Password for EPsLdapUser. |
|
EPsLdapRootContext |
If you want to limit the scope of group searches, set this parameter to the desired starting point. For AD sites, you must set this parameter to the root (or somewhere below the root). Otherwise searches will be performed against schema data. For the AD domain company.com, the root context should be "dc=company,dc=com". |
|
EPsLdapServer |
Host name of LDAP server or the name of the AD domain. If you are using an AD domain, it is highly recommended to use the domain name to take advantage of failover functions, etc. For example "ldap.microsoft.com" or "192.168.12.23". |
|
EPsLdapServerType |
Set this parameter to AD if you use AuthenticationMode = Windows. This will enable check of LDAP group membership event for Windows accounts. Note This does not work in pre- EPiServer 4.21 versions. |
|
EPsLdapUser |
The user name of the account that you want to use to access information from your AD, for instance MyUser. (If you are using simple authentication this should be MyDomain\MyUser.) This account should have read/browse access to the entire tree. Note The role "Account Operators" should have sufficient access rights in the AD. |
Extranet Settings
These settings are used if you have an extranet environment.
|
Setting |
Description | |
|---|---|---|
|
EPsActivationEmailBody |
Text in the body of activation e-mails. | |
|
EPsActivationEmailSubject |
Subject of activation e-mails. | |
|
EPfAutoActivateUser |
Set to true if manual activation is not required for extranets users. | |
|
EPnDefaultGroup |
Group that extranet users become a member of after extranet account registration. | |
|
EPfEnableFreeRegistring |
Set to true to enable free registration for extranet users. | |
|
EPnMaxFailedLogonAttempts |
Maximum number of failed logon attempts that an extranet user can have before being locked out. Set value="0" to set an unlimited amount of attempts. | |
|
EPfPasswordRequireAlpha |
Set to true if the extranet password must include letters. | |
|
EPfPasswordRequireNumber |
Set to true if the extranet password must include numbers. | |
|
EPfPasswordRequireSymbol |
Set to true if the extranet password requires symbols. | |
|
EPsRegistryEmailBody |
Text in the body of registration e-mails. | |
|
EPsRegistryEmailFrom |
E-mail address from which extranet registrations are sent. | |
|
EPsRegistryEmailSubject |
Subject of registration e-mails. | |
|
EPsRegistryEmailTo |
E-mail address to which extranet registrations are sent. | |
Security Settings
These settings are used to configure the security of an EPiServer CMS site.
