Handling exceptions in SharePoint environment is quite straightforward; it’s a out-of-the-box feature. Any unhandled exception is caught by the SharePoint environment and a pretty “Sorry, something went wrong” screen is shown.
That’s all great! Things can get a bit tougher if exceptions occur outside the SharePoint context. How can this happen? In my case, it can happen when custom code is being loaded through an HttpContext, and some DLL might fail to load. In this case, there is no SharePoint context to catch the uncaught exception, thus it remains as an unhandled exception. By default, unhandled exceptions generate the Yellow Screen of Death.
That’s not something we should be displaying, right? Of course not! First and foremost, we’re showing the actual code to the public! That’s never good. Even if we manage to turn off the details in such exceptions, it’s still terrible practice to show such screen to public.
Alright then, let’s use some custom page to show our error! This is where it gets a bit trickier. Sadly enough, we cannot safely and reliably meddle with the Global.asax file, to globally catch errors and handle them nicely. We need to thing of something else.
Whilst I was trying to tackle this issue, my obvious guess was to amend the web.config – more specifically the customError section. My first attempt at solving this was by creating a simple custom error page, putting it in my IIS folder and configuring IIS to load this page in the customError section. My web.config looked something like this:
<customErrors defaultRedirect="errorPage.html" mode="On" />
After trying that out, I was still stuck with the same Yellow Screen of Death. What was happening? It so happens that when an error is thrown, indeed a redirect to my custom page happens. But when this page tries to load, it attempts to re-load all my HttpModules and this failing and throwing a new exception all over again. This means that this approach could never work.
In order to solve this, I had to do some additional steps. The solution to this issue is to create a new Site in IIS, that is designed specifically to handle such erroneous cases. Let’s go through the steps in order to carry this out.
These steps assume that you are in possession of a functional SharePoint on-premise solution.
1) Create a friendly error page to display to the user when something goes wrong
In order to keep this as simple as possible, we’re just going to display a header that something went wrong, no fancy images or CSS. You could be a bit more creative if you want but for the sake of this blog, it’s fine.
<html> <body> <h1>Sorry, something went wrong</h1> </body> </html>
2) Create a new IIS Site to host our newly created HTML
This site will simply be used to host the newly created HTML. We can opt to create this site either on the same Application Pool or a new one; it does not really matter in this case. I’ll just follow the default configuration provided by IIS.
3) Map your newly created IIS site to a subdomain.
Since we still need to use the same external port, we need to make sure that our newly created IIS site is accessible from outside. We need to create bindings in IIS to make sure that this is OK. If you’re running HTTPS (please do), you’ll need a wildcard certificate and IIS 7.5 or higher.
4) Assign permissions to Everyone on the newly created Site.
Creating the site is not enough, we need to allow Everyone to access the site. We’ll use one of the out of the box special identities provided; the “Everyone” identity. Therefore anyone will be able to access it.
5) Configure the customErrors tag in your SharePoint site to point to the newly created Site
All we need now is to point the customErrors tag to thew newly created site.
<customErrors defaultRedirect="https://error.mysharepointsite.com" mode="On" />
All done! Keep in mind that this page is used in very special circumstances: when exceptions occur and the SharePoint context has not kicked in. All other typical exceptions are to be handled by the default out of the box SharePoint behavior.
Albert Herd 