Configuration
There are several required and optional configuration for the Error Manager.
Most of the options from the Error Manager can be configured in the delivered configfile in the Include folder of the App_Config. The file contains the following configuration in the <settings> node:
| Property | Description |
|---|---|
| RequestErrors.UseServerSideRedirect | If true, the redirect to the error page will only be on server side (Server.Transfer() instead of Response.Redirect()). The user does not get a 301 redirect. True is the Error Manager's default value and recommended. |
| ErrorManager.Timeout | The timeout in milliseconds for a http request done by the Error Manager. |
| ErrorManager.MaxRedirects | Maximum of redirects the http request will follow. |
| ErrorManager.SendClientCookies | If true, all available client cookies will be send with the http request to the corresponding error page. This is required if you have some implementation on the error item which needs the client cookies. Default value is false. |
| ErrorManager.IgnoreInvalidSSLCertificates | If true, any ssl exception within the request of the error page will be ignored. Default value: false. |
| ErrorManager.UseRootPath | If true, the relative path of the error items (ItemNotFoundUrl.Item) are located under Site.RootPath. If false, the items are located under Site.StartPath (including the site's rootPath + startItem). Default value: false |
| ItemNotFoundUrl | The Sitecore default not found page. This must point the the custom 404.aspx page. |
| ItemNotFoundUrl.Static | The page to request if no valid 404 item is found in Sitecore. |
| ItemNotFoundUrl.Item | The path to the 404 item in Sitecore, relative to the site root. |
| LayoutNotFoundUrl | The Sitecore default layout not found page. This must point the the custom 500.aspx page. |
| LayoutNotFoundUrl.Static | The page to request if no valid 500 item is found in Sitecore. |
| LayoutNotFoundUrl.Item | The path to the 500item in Sitecore, relative to the site root. |
| NoAccessUrl | The Sitecore default no access page. This must point the the custom 403.aspx page. |
| NoAccessUrl.Static | The page to request if no valid 403 item is found in Sitecore. |
| NoAccessUrl.Item | The path to the 403item in Sitecore, relative to the site root. |
| NoLicenseUrl | The Sitecore default no license page. This error can not be handled through the Error Manager, because the Error Manager needs a valid license. |
There is also configured a custom pipeline processor. Please see the section Custom Item Resolver on how to use this processor.
If you have Sitecore Analytics (OMS or DMS) installed, you have to enable tracking on the error items in Sitecore. To enable this, navigate in the Content Editor to the item you've configured as error item (i.e. the notfound item), open the ribbon Analyze and click on Attributes. In the popup, activate the Failure Action you want to track.
You may need to create new actions, for more informations please see Engagement Analytics Configuration Reference, chapter How to Register an Engagement Analytics Page Event.
In a multisite environment, you may have different sites with different languages. I.e. the country site for France have the languages fr and en, while the country site for USA only have en. The Error Manager always checks for a valid item in a valid language. Because we are always in the context of a <site> configuration, we may have different valid languages. Therefore, you can extend your <site> configuration node with an attribute availableLanguages. This attribute contains a comma-separated string with language item names, which are available in the coresponding site. Your configuration for France and USA could look like the following example:
<sites>
<site name="france" patch:before="site[@name='website']"
...
availableLanguages="fr,en"
language="fr" />
<site name="usa" patch:before="site[@name='website']"
...
availableLanguages="en"
language="en" />
</sites>If you want to allow all languages and only check if a version exists, you don't need to configure this attribute. With the querystring parameter "em_force=true" you can force to ignore the "availableLanguages"-check for this request.
The MediaRequestHandler is responsible to check wheter a media is available or not. Unfortunately, the default Sitecore implementation does not consider the requested language. If you would like to check if a media is available in the requested language (and has an available language in the current site) you must configure the custom MediaRequestHandler, which is part of the Error Manager. Because this configuration is not part of the <sitecore> configuration node, you have to adapt the following changes directly in your web.config file:
Change
<system.webServer>
<handlers>
<add verb="*" path="sitecore_media.ashx" type="Sitecore.Resources.Media.MediaRequestHandler, Sitecore.Kernel" name="Sitecore.MediaRequestHandler" />
</handlers>
</system.webServer>to
<system.webServer>
<handlers>
<add verb="*" path="sitecore_media.ashx" type="Unic.SitecoreCMS.Modules.ErrorManager.Resources.Media.MediaRequestHandler, Unic.SitecoreCMS.Modules.ErrorManager" name="Sitecore.MediaRequestHandler" />
</handlers>
</system.webServer>and
<system.web>
<httpHandlers>
<add verb="*" path="sitecore_media.ashx" type="Sitecore.Resources.Media.MediaRequestHandler, Sitecore.Kernel" />
</httpHandlers>
</system.web>to
<system.web>
<httpHandlers>
<add verb="*" path="sitecore_media.ashx" type="Unic.SitecoreCMS.Modules.ErrorManager.Resources.Media.MediaRequestHandler, Unic.SitecoreCMS.Modules.ErrorManager" />
</httpHandlers>
</system.web>By default, Sitecore only handles 404 errors if an item does not exists. However, sometimes it is desired to also show a 404 error if an item does not exist in the requested language. For this purpose, the Error Manager has a custom item resolver, which needs to be configured as a pipeline processor directly after the default ItemResolver from Sitecore.
<pipelines>
<httpRequestBegin>
<processor patch:after="processor[@type='Sitecore.Pipelines.HttpRequest.ItemResolver, Sitecore.Kernel']" type="Unic.SitecoreCMS.Modules.ErrorManager.Pipelines.HttpRequest.ItemResolver, Unic.SitecoreCMS.Modules.ErrorManager" />
</httpRequestBegin>
</pipelines>The processor checks if the Context.Language is an available language (see section Available languages) and if the requested item has a valid language version. If not, it sets the Context.Item to null and therefore the Sitecore error handling will redirect to the configured ItemNotFoundUrl.
Sitecore only handles not found, access denied and layout not found errors. If you would like to handle other status codes (i.e. all 500 errors or 404 substatus codes) you have to configure the error pages in IIS (or in the web.config). The following example shows how to configure IIS in the web.config, that all 404 substatus codes are handled by the Error Manager. Please note that the path must point to the custom error page in the Error Manager.
<system.webServer>
<httpErrors errorMode="Custom">
<remove statusCode="404" subStatusCode="-1"/>
<error statusCode="404" subStatusCode="-1" responseMode="ExecuteURL" path="/sitecore modules/Web/Error Manager/404.aspx"/>
</httpErrors>
</system.webServer>You can configure all kind of error pages. Please see HTTP Errors for more informations. If you need to create new status code pages in the Error Manager, please consider section_How it works_.
You may also want to display a friendly error message, if there was an error somewhere in your code. You could make use of the method Application_Error in Global.asax (http://msdn.microsoft.com/library/24395wz3.aspx). You need to set the status code to 500 in this method. Please note that this only works, if you have configured the 500 status code with the Error Manager (see section Configure other (sub-)status codes). Please also note that this can only work if the error does not appear on the configured 500.aspx, otherwise you'll get an endless loop.