Custom Error Page Improvements in Sitefinity v12

Written By Janae Allen

The release of Sitefinity v12.2 brought some great new features, including performance updates, form rule modifications, enhanced out-of-the-box designers for custom widgets, and more. Check out the official release notes at https://www.progress.com/sitefinity-cms/release-notes/sitefinity-cms-12-2-7200-(official-release)

In this blog post, though, I am going to cover the improvements to Custom Error Pages within Sitefinity.  Custom error pages are important for your site because they present your users with a more user-friendly, professional screen if an error happens to occur on your site, rather than the default errors screens.  There are many types of errors which that can occur on a website, and each error type returns a specific HTTP status code to the browser.  Sitefinity gives you an easy way to implement custom error pages for one, some, or all status codes, — thus providing a better user experience when errors occur.  And what's better, Sitefinity sends along the error status code to the browser rather changing the status code to 200 (which is the code used for when everything is A-OK).  The end user doesn't actually see the status code, but these codes are important as they help the owner or administrator determine whether the URL the user is visiting is valid and okay. 

Out with the old… 

Historically, if we wanted custom error pages in a Sitefinity site we were building, we would do the following: 

  1. Update the <customErrors> section in the web.config to turn on custom error pages. But during development we wouldn’t want custom error pages because we would want to see the details of the error occurring. So, we need to set up web.config transforms to make sure that the custom errors will show up on the production site. 

  2. The <customErrors> section allows you to specify different error pages for different HTTP status codes, so we would list here the various status codes we handle along with the URL to the associated custom error page

  3. Additionally, since the <customErrors> section doesn't handle 404 (resource not found) errors for extensionless URLs, we would define that in the <httpErrors> section of the web.config.

  4. We would then need to create widgets to force Sitefinity to return the correct status code,  place these widgets on the corresponding error pages, and then override the FeatherActionInvoker to pass along the correct status code. There are several articles provided by Sitefinity that can help you do this if you have not yet upgraded to version 12.2. This is a good place to start:https://www.progress.com/documentation/sitefinity-cms/change-the-response-status-of-the-custom-error-page-of-mvc-pages-mvc

In with the new… 

Starting with version 12.2, Sitefinity provides a way of setting up custom error pages. No more messing with multiple status codes in the web.config, creating custom widgets, or overriding the FeatherActionInvoker! 

It’s as simple as logging in to Sitefinity, navigating to Administration -> Settings -> Advanced -> Pages -> Custom Errors, then and Enabling Custom Errors. You can create new error types and map them to HTTP Status codes all from the Sitefinity backend. 

Sitefinity provides some great documentation including step-by-step instructions about: 

  • How to enable custom error pages 

  • Mapping the status codes to error pages 

  • This Documentation also includes a list of the supported status (error) codes 

  • Creating error pages 

  • Information about how to define different error pages for different areas of your site - to help give a more personalized user experience! 

  • Handling custom error pages and multiple languages 

  • Setting up the default error page to show for any specifically unhandled status code

Since Sitefinity is handling the custom error page definition, it is best practice to still include the <customErrors> and  <httpErrors> sections in the web.config, but only have it handle the 500 status code. This is to handle any errors which that occur before Sitefinity is able tocan capture them - for example, a bad database connection string which prevents Sitefinity from running at all. 

As a web developer, I am really excited Sitefinity has implemented this in version 12.2. It makes my life easier by speeding up development while also ensuring thje users who end up browsing the site I build will see nice, custom error pages.  

Resources