An Expected Error Has Occurred


There is not a single sole on this planet which has used SharePoint that has not seen the error message “An Unexpected Error has occurred”. Bold statement, and obviously I don’t have the research to back it up but you must admit its an error allot of folks see from time to time if you spend any time on a SharePoint site – hopefully that will change soon.

With SharePoint 2010 you can now set your own custom error pages. This has been a much asked for feature from allot of my customers and has the potential to offer a much  better user experience. In fact, one which you may choose to vary depending on the role of the user. For example, you may want to provide a very generic error for anonymous users and a much more detailed error of the user happens to be the site collection owner or farm admin.

Its not only the error pages that got all the love here, in fact you can customize the Access Denied, Confirmation, Login, Request Access, Sign-out, and Web Deleted pages. The SPWebApplication.SPCustomPage enumerator is used to pass the page which you wish to override into a call to UpdateMappedPage() along with the path to the custom page. So once set, this page will be used anytime a request is made for the corresponding page. Since this method is part of the SPWebApplication you will note a custom pages are scoped to the web application.

What is really happening here is SharePoint’s Virtual Path Provider (VPP) does a check each time it’s asked to resolve a path to a file and if the current Web Application has a custom page configured it will be served rather than the original error page. This means URLs and code references to these pages will not need to be updated to paths to your custom files because the VPP handles the redirection.

If you choose to remove a custom page you make the same call into UpdateMappedpage passing NULL for the page path and the corresponding enum value for the page you wish to disconnect.

I would highly recommend anyone who deploys an Internet facing SharePoint site override at the very least the error page for at least three reasons:

1) Own your messaging to the anonymous user, don’t let SharePoint send messages to your users. What is the point of giving them an error they most likely cannot understand, don’t care too, and most likely could not take any corrective action to fix.

2) Currently there is a bug that will hopefully get fixed before SharePoint 2010  hits RTM which allows anyone to place an error message on the error page, for example on your SharePoint site append this string to your URL:  _layouts/error.aspx?ErrorText=ErrorBaby!

3) There is an opportunity to offer a better user experience, the custom error page might collect additional information and send that along to those interested, you may choose to collect additional information from the user by asking for feedback, or you may offer additional details if the user is privileged enough, based on his or her role to understand what may be going on with the server.

Here is some example code to get you started – this is a custom feature receiver which you might use to hook a custom error page.

  [Guid("bf07336a-76d7-4324-8908-74e2771bba49")]
   public class CustomPageMappingsFeatureEventReceiver : SPFeatureReceiver
   {
       const string CustomErrorPage = "/_layouts/CustomPageMappings/Error.aspx";
       
       public override void FeatureActivated(SPFeatureReceiverProperties properties)
       {
           SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
           if (webApp != null)
           {
               if (!webApp.UpdateMappedPage(SPWebApplication.SPCustomPage.Error, CustomErrorPage))
               {
                   throw new ApplicationException("Cannot create the new error page mapping.");
               }
               webApp.Update(true);
           }
       }
       
       public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
       {
           SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
           if (webApp != null)
           {
               if (!webApp.UpdateMappedPage(SPWebApplication.SPCustomPage.Error, null))
               {
                   throw new ApplicationException("Cannot reset the default error page mapping.");
               }
               webApp.Update(true);
           }
       }
   }

One thought on “An Expected Error Has Occurred

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s