One of the important steps of any website is setting it up to fail Nicely. Sitecore has done a lot of this for us with their error pages, but that may not be the look you want your visitors to see! And what if Sitecore isn’t able to help at all? Not so pretty with ASP.NET error pages…
But do not fear! With the configuration files Sitecore makes available, this is a snap to set up and fix.***
***You Will need to change the web.config file, so please back it up before making any changes suggested here!
The first and hardest step – make your error/not found pages that you want your visitors to see – these can be html pages, aspx pages, or even an existing page within Sitecore.
Usually Sitecore will handle your errors nicely, but if .NET explodes you will need to display something to the user that will Not fail, so I’d VERY STRONGLY recommend an html page for errors and not aspx pages: if there’s an error in the error page, you’re back to square one.
Upload these files to your Website directory or a subfolder within it – for our example we have saved the files in Website/ErrorPages/.
Now for the magic: In the website folder is a folder called App_Config and inside that is the Include folder. This folder automagically updates the web.config with new settings – it doesn’t require anything to be restarted and immediately takes effect. Also – using these files instead of modifying the web.config directly means you can make web.config type changes in packages without completely destroying the site.
There should be a file in that directory called: SitecoreSettings.config.example
This is what we will be changing into SitecoreSettings.config and adding our custom ‘not found’ page details.
Currently the file looks like this, along with some comments describing the use of the file at the top:
<!-- REQUIRE LOCK BEFORE EDITING
If true, the user must have a lock on a document before
he can edit it, otherwise it is always ready for editing
<setting name="RequireLockBeforeEditing" value="false"/>
We are going to erase this, and put in the following:
The above basically tells the web.config file to update the specified settings with our new and improved values.
You can choose other files to use or have different files for each – and these special pages do not stop any logging from happening on the server – they simply give a better experience for your users when your site is having some trouble.
ItemNotFoundUrl and LinkItemNotFoundUrl will come up when a visitor tries to access an item that doesn’t exist or hasn’t been published (it doesn’t exist yet on the web database). This replaces the default value of: /sitecore/service/notfound.aspx with our own /ErrorPages/404.html
You’ll notice that the default is pulling from /sitecore/service ß if you have blocked this directory or don’t have it available, you will need to make the changes above so that users see Some kind of page instead of a browser default.
LayoutNotFoundUrl will come up when the user tries to visit an item that does exist, but no layouts have been assigned to the item so Sitecore doesn’t know what to display for the user. This replaces /sitecore/service/nolayout.aspx in the default web.config file.
ErrorPage should come up whenever there is a generic error within Sitecore – the default setting we are overwriting is: /sitecore/service/error.aspx
Save your new file without the .example extension and you should now see your custom error pages whenever you try to access missing items!
The next step is the change to the web.config for handling errors when sitecore can’t handle them for us – save a backup of your web.config and then open it up in an editor.
Here is what we are looking for:
<!-- CUSTOM ERROR MESSAGES
Set customError mode values to control the display of user-friendly
error messages to users instead of error details (including a stack trace):
"On" Always display custom (friendly) messages
"Off" Always display detailed ASP.NET error information.
"RemoteOnly" Display custom (friendly) messages only to users not running
on the local Web server. This setting is recommended for security purposes, so
that you do not display application detail information to remote clients.
<customErrors mode="On" />
Search for customErrors to find it quickly. It may also have one of the above settings, RemoteOnly or Off. I would recommend On or RemoteOnly if you won’t have visitors accessing the site locally.
We want to change the setting to also include a redirect to our new Error page:
<customErrors mode="RemoteOnly" defaultRedirect="/ErrorPage.htm"/>
Now, if anything serious should happen, your users will not end up seeing an ASP.NET error page telling them it is broken and will instead get to see a page of your choice! This should Not point to a page you have in Sitecore since it will not work in the case of ASP.NET failing.
Crossposted from Sitecore Adventures!