Error Handling

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 80%
  • 6.0
  • Enterprise
  • Community
  • Planned

Overview

Global Error Page
As a developer you may often run into unhandled exceptions. An unhandled exception is an Exception that is thrown by execution but is never caught by the program, which results in a nasty Exception Stack. This could be avoided by catching the exception in a try-catch statement, but it is not always appropriate to catch every possible exception. Sometimes the exception is the result of the client making a mistake rather than something that occurred where it is thrown, therefore the client should be informed of the exception.

In Sense/Net these exceptions are captured by the Global Error Handler. The Portal returns with a Custom Error Page according to the error code configuration where the types of exceptions and their HTTP (sub)status codes are set. In case of missing configuration the Portal returns with the Global Error Page with the unhandled exception in detail.

Details

Global Error Page

The Global Error Page is meant to be giving information about the unhandled exception thrown by application execution. Two different Global Error Page are distinguished. The /Root/System/errormessages/<site_name || Default>/Global.html is shown when the concerned site is accessed through localhost and /Root/System/errormessages/<site_name || Default>/UserGlobal.html otherwise. In the first case more details are provided about the exception helping developers examine the source of the problem. The detailed error page is also known as the "Error page for Developers" and the other as the "Error page for End Users". The template of both error pages can be given and customized for each site running on the Portal. To do so put the right files under /Root/System/errormessages/<site_name>.

Error page for End Users

Error page for end users

This page can be placed in the following places:

  • /Root/System/ErrorMessages/<site_name>/UserGlobal.html
  • /Root/System/ErrorMessages/Default/UserGlobal.html - if there is no specified error page for your site
  • UserErrorPage.html - put it inside the root websites folder if there is no specified error page for your site and default page is missing

Error page for developers

Error page for developers

This page can be placed in the following places:

  • /Root/System/ErrorMessages/<site_name>/Global.html
  • /Root/System/ErrorMessages/Default/Global.html - if there is no specified error page for your site
  • ErrorPage.html - put it inside the root websites folder if there is no specified error page for your site and default page is missing

Customizing Global Error Pages

These error pages are simple HTML pages, containing inline css, and template strings. You can embed the following keywords in your template HTML file which will be replaced by the corresponding properties of the exception. The keywords are case-sensitive and culture-insensitive.

Template String Name Details
{exceptionType} Type of the exception instance
{exceptionMessage} Message of the exception instance
{exceptionToString} Result of ToString() method of the exception instance
{exceptionSource} Source of the exception instance
{exceptionStackTrace} Stack trace of the exception instance

Example:

<div class="sn-exception-detailsbox">
  <div class="sn-exception-details">
    <div class="sn-exception-title">
        An unexpected error occurred, please report the following technical details to your system             
    </div>           
    <div class="sn-exception-type">
        <span class="sn-exception-msgtitle">Exception type:</span><span>&nbsp;{exceptionType}</span>
        <div class="triangle"></div>
    </div>
    <div class="sn-exception-msg">
        <span class="sn-exception-msgtitle">Exception message:</span><p><big>{exceptionMessage}</big></p>
    </div>
  </div>
</div>

Custom Error Page

IIS can return a custom error message whenever an HTTP error occurs. Custom error messages can provide friendlier or more informative feedback than default error messages.

In Sense/Net these pages can be any content but usually they contain a Portlet Page with some templatized HTML in it. By default, the page template which is used to display errors (sn-layout-error) contains a hidden Status code Portlet for setting the correct status code for the rendered page. It is important to use it if you don't want your error pages to be indexed by search engines like Google or Bing. If you use custom Page Template then don't forget about it. It's needed to know that the mentioned Status code Portlet sets the given code no matter your site is running locally on your computer or it is published to a public domain.

In the configuration file under the section httpErrors the HTTP status codes and their custom error pages are given. Use the following syntax to specify new rules:

<remove statusCode="404" subStatusCode="-1" />
<error statusCode="404" subStatusCode="-1" path="/Error_Pages/My_Error_404" responseMode="ExecuteURL" />
<remove statusCode="403" subStatusCode="2"/>
<error statusCode="403" subStatusCode="2" path="/Error_Pages/My_Error_403_2" responseMode="ExecuteURL" />

More about httpErrors element: MSDN - httpError Element

Note that you cannot customize the following HTTP errors: 400, 403.9, 411, 414, 500, 500.11, 500.14, 500.15, 501, 503, and 505.

How to create your own error pages?

In the following example you'll be shown an easy way to create a simple page for displaying a user-friendly HTTP 403.2 page.

  1. Create a Page somewhere under the corresponding site (e.g.: /Root/Sites/Your_Site/Error_Pages/) and use sn-layout-error as Page template
  2. Place a Single content Portlet into the Wide Column
  3. Add a new WebContentDemo content into the portlet by choosing New content from the action list.
  4. Customize the content: type "403.2 Read Access Forbidden" into Display Name and put "You don't have permission to read that" into Subtitle. Filling out Body giving more details or options is also recommended. After you're done click on Done Editing to save the changes.
  5. Set Status code to 403 and Sub status code to 2 in the hidden Status code Portlet inside the page template.
  6. Place the error configuration row into the Web.Config by using the syntax above.
Custom error page

NTLM authentication and HTTP 401

In case of Windows authentication the first request to a web server is rejected by returning HTTP 401 status code. This means that you need to authenticate yourself by sending negotiate authentication headers in the second request. After successful authentication no more 401 code will be sent.

Creating a Custom Error Page for HTTP 401 should be avoided when using NTLM authentication. It's because the NTLM authentication process stops when the browser recieves a custom error page with HTTP 401 set. We also highly recommend not to override any 401.x error page.

Bypassing custom error pages

As a Sense/Net developer it may not be suitable for you to get a nicely customized page whenever an error occurs. Use the following lines of code to return the desired status code without an error page:

HttpContext.Current.Response.TrySkipIisCustomErrors = true;
HttpContext.Current.Response.StatusCode = 404; // or whatever you'd like to
HttpContext.Current.Response.End();

This can be useful when you're working with WebDav or using the Office Protocol.

Exception handling rules

In the Web.Config file under the Configuration section you find ExceptionStatusCodes subsection. Here you can specify which HTTP status and substatus codes belong to which type of exception. As the key you can set the full name of the exception (for instance: System.Security.SecurityException) or you can set an Exception-family as well (for example: System.Exception.SystemException). In the second case all the exceptions belong to SystemException will be handled. As the value you can set the three digit HTTP status code or, in case of using IIS, use the XXX.X format to specify substatus codes as well.

Here is an example:

 
<configuration>
  <ExceptionStatusCodes>
    <add key="System.Security.SecurityException" value="403"/>
    <add key="System.Security.Policy.PolicyException" value="403.1"/>
    <add key="System.Security.AccessControl.PrivilegeNotHeldException" value="403.2"/>
    <add key="System.UnauthorizedAccessException" value="403.3"/>
    <add key="System.Security.HostProtectionException" value="403.8"/>
    <add key="System.Runtime.Remoting.RemotingTimeoutException" value="403.9"/>
    <add key="System.NotSupportedException" value="404"/>
  </ExceptionStatusCodes>
</configuration>

Exception inheritance

If an exception is thrown and it has no HTTP status code definition then the Portal checks its parent exception type if it has a definition until it reaches System.Exception. If there is no definition for any exception it shows the Global Error Page. Otherwise, you are redirected to the corresponding Error Page.

Application Offline

Normally the last thing you want is for your web application to be offline but if you're going to make major changes to your application then it's likely that you don't want users using it in the process.

If you place a file named app_offline.htm in the root of a web application directory, ASP.NET 2.0 will shut-down the application, unload the application domain from the server, and stop processing any new incoming requests for that application.

Example

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>Application Offline</title>
</head>
<body>
    <p>Ooops! Our website is currently down but we'll be back soon!</p>
</html>

Related links

References