Wednesday, 6 August 2014

Create Custom Error Page in Sitecore

Hello Sitecore Techies!
How's your Sitecore Journey going on? Hope you are passing through many milestones in your journey. So let's share this journey with each other.

Have you come across a scenario in your project where you have seen .NET run-time error page (typical yellow .NET error page) and you don't want to show such error page to end user?  If so then you are thinking absolutely right and this post may help you.

So now question is what is simplest way to implement custom error page in Sitecore?

We need to keep one thing in our mind to solve this - "error can happen at anytime and anywhere in the project", so where should you can write code to handle error?

There are two places where you can handle this error:
1) Application_Error event in Global.asax
2) Page_Error event in your Layout page

If you have multiple projects under your Sitecore solution and you want to implement custom error page for one of your project then it should be advisable to write code under Page_Error event in Layout page of your project. Every Sitecore project has at-least one layout page (e.g. .aspx page) which will be executed on every page request. So you can write code in this layout file (e.g. .aspx page)

I had exact above scenario so I went with second approach (e.g. Page_Error), if you have only single project and then you can go with fist approach (e.g. Application_Error).

Step-1: Handle Page_Error event in your Sitecore Layout page.
// page-level exception handler
        public void Page_Error(object sender, EventArgs e)
            // retrieve the last exception
            Exception exception = HttpContext.Current.Server.GetLastError();

            // handle only exceptions based on CustomExceptionBase
            // if this exception is based on CustomExceptionBase
            if (exception != null)
                // log and clear the exception
                Sitecore.Diagnostics.Log.Error(exception.ToString(), this);
                // Pass the error on to the Generic Error page                

Please note that instead of hard-coding page name as error-page.aspx, you can make it configurable either from web.config or providing general link field at Sitecore Home Root item.

Step-2: Create error-page in Sitecore which will have rich-text field where you can configure your custom error page. Also add any rendering (e.g. Sublayout) on this page which will pull configured error message from rich-text field and render on this error-page.

No more .NET error page now! User will see your custom user-friendly error page.

Isn't it simple? Yes - it is simple and effective solution. If you are seasoned programmer, you will always show custom error page to user rather than showing .NET error page.
Thanks to Sitecore Guru - John West who has given this idea in his Professional Sitecore Development Book!

So have you implemented your Sitecore custom error page?
Have a happy Sitecore Journey!