SharePoint Tips and Tricks

By default, when an HTTP error is encountered (404 page not found, 401 access denied, etc.), IIS returns the HTTP error code to the browser.  The browser (or a plug-in such as Google Toolbar) then decides exactly what gets displayed to the user.  You can alter this behavior and customize SharePoint 2010 to display your own custom error page(s) for HTTP errors that are encountered on your site.  These custom error pages can be static (ie. html) or dynamic (ie. aspx).

There are multiple options for overriding the behavior of HTTP error handling in your SharePoint implementation.  Some options include directly modifying the web.config, utilizing the IIS management console, and developing custom HTTP modules.  This post will demonstrate how to override the handling of HTTP error code 404 (page not found) and display a dynamic page located on a SharePoint publishing site.  We’ll explore using IIS to make the changes, and we’ll also look directly at the web.config (if you’re short on time, you can jump directly to editing the web.config at the end of this post).

Remember to make a backup copy of the web.config file so that the original file may be restored in the event something goes terribly wrong.  (That never happens, right?)

Launch IIS (Start -> Run -> inetmgr).  Expand Sites and click on the desired SharePoint site.  You're presented with a number of icons for managing your site...double click the Error Pages icon as shown below.

The Error Pages dialog shows the current (default) mappings of HTTP error codes to their built-in custom pages.  So, in the event a site has been configured to display custom error pages and no other changes are made, these are the pages that will be served.  These custom pages are located in the inetpub/custerr/<LANGUAGE-TAG>/ directory.  For example, there's already a file called inetpub/custerr/<LANGUAGE-TAG>/404.htm.

We could edit the 404.htm file directly if we simply wanted to add a link or make some minor cosmetic changes to the page, but let's make things a bit more interesting and assign a dynamic (.aspx) page located on our SharePoint 2010 site to be displayed when a 404 is encountered.  By executing a dynamic page, this will allow us to perform some custom logic as well as remain consistent with our current SharePoint branding.

Choose the radio button "Execute a URL on this site" and provide a URL to the dynamic page (in this case we've created a new page on our SharePoint publishing site called /Pages/404.aspx), then click OK.

After clicking OK you'll notice the Error Pages list has been modified to reflect your changes as shown below.

At this point, IIS has modified the underlying web.config to include a section called httpErrors (which is added within the system.webServer section).

<httpErrors>
    <remove statusCode="404" subStatusCode="-1" />
    <error statusCode="404" prefixLanguageFilePath="" path="/Pages/404.aspx" responseMode="ExecuteURL" />
</httpErrors>

Unfortunately, IIS didn't go quite far enough for this to work correctly in our SharePoint deployment.  A slight change to the httpErrors element setting error mode to Custom will inform IIS to use our custom page as follows:

<httpErrors errorMode="Custom" existingResponse="Auto">
    <remove statusCode="404" subStatusCode="-1" />
    <error statusCode="404" prefixLanguageFilePath="" path="/Pages/404.aspx" responseMode="ExecuteURL" />
</httpErrors>

To implement SharePoint support of a custom 404 error page, you can skip the IIS management console portion and jump directly to editing the web.config of the desired site.  Simply add the code snippet above to the system.webServer section and replace /Pages/404.aspx with your own dynamic page.