How to use CustomErrors in ASP.NET MVC 2

First, let’s see how our Web.config file will look like and after that I will show you how to create the pages.

<customErrors mode="On" defaultRedirect="~/Error">
  <error statusCode="404" redirect="~/Error/NotFound"/>
  <error statusCode="403" redirect="~/Error/AccessDenied"/>
</customErrors>

I’m going to show the steps to make it work for those three types of errors and also explain you about the HandleError attribute and how it handles the information specified in the customErrors. I’m also putting here the code I wrote in order to handle the AccessDenied error.

Error Page

When we are talking about the Error Page, one thing that you should understand is that without the HandleError Attribute, if an error occurs the .NET will just redirect the user to the page you specified in your Web.Config. So, if you have the “defaultRedirect” property pointing to something like “~/GenericError.aspx”, the GenericError.aspx page under the root folder of your project will be shown without any information about the Error. It could be a static HTML page that only tells the user “Hey, you’ve got an Error”.

Now, if you what you want is to show the user some information about the error, like the description or even the stackTrace but with the page looking like your default theme, then you can use the HandleError Attribute. By applying it to a Controller or a method the behavior of the customErrors changes a little bit. Instead of just pointing to some page, the exception handling will render a View, more specifically, a view called Error (if you don’t specify any other name to the Attribute) it doesn’t matter what name you’ve told the “defaultRedirect” to take you to. Along with that, it will send a HandleErrorInfo model containing the Controller name where the exception occurred, the Action name and the exception itself, so you can get the stackTrace and the description of the error.

Although it might seem obvious for some what the HandleError attribute does I’ve seen it’s a common issue people setting their customErrors to show something like GenericError.aspx and using the HandleError attribute. Or even, setting the defaultRedirect property to “Error” and expecting the Index method within the ErrorController to receive a HandleErrorInfo parameter. Remember, when using the HandleError attribute, the “Error“ View will be rendered internally, without even getting into the ErrorController.

Common mistake

Web.Config

<customErrors mode="On" defaultRedirect="Error/Ops" />

HomeController.cs

[HandleError] // using HandleError attribute
public class HomeController : Controller
{
    public ActionResult Index()
    {
		return View();
    }
}

ErrorController.cs

public class ErrorController : Controller
{
    public ActionResult Ops()
    {
        //
		// Wrong! It won't get here because
		// the HandleError will handle the error.
		return View();
    }
}

The right way

I’m going to demonstrate now how you can make it work with a page that shows some information about the error. With this example, even though someone forget using the HandleError attribute, a friendly page still shows up but without the error info (it’s better than not showing anything). It could be improved, off course, but that it’s another point.

Web.config

<customErrors mode="On" defaultRedirect="Error" />

Error.aspx

<%@ Page Language="C#" MasterPageFile="~/Views/Shared/Site.Master" Inherits="System.Web.Mvc.ViewPage<System.Web.Mvc.HandleErrorInfo>" %>

<asp:Content ID="errorTitle" ContentPlaceHolderID="TitleContent" runat="server">
    Error
</asp:Content>

<asp:Content ID="errorContent" ContentPlaceHolderID="MainContent" runat="server">       

    <h2>
        Sorry, an error occurred while processing your request.
    </h2>

	<% if (Model.Exception != null ) { %>
		<p>
		  Controller: <%= Model.ControllerName %>
		</p>
		<p>
		  Action: <%= Model.ActionName %>
		</p>
		<p>
		  Message: <%= Model.Exception.Message%>
		</p>
		<p>
		  Stack Trace: <%= Model.Exception.StackTrace%>
		</p>
	<% } %>
</asp:Content>

Place that page inside your Views folder. It can be either your Shared or Error folder. The name must be Error.aspx.

That’s it! Only the aspx file and the setting inside the Web.config.

Only if you want that whether the Controller have or not the HandleError attribute, your custom error page will still be shown, then you can add an action method into your ErrorController:

ErrorController.cs

public class ErrorController : Controller
{
    public ActionResult Index()
    {
		return View("Error");
    }
}

Now whether the page is being redirected to the defaultRedirect or rendered by the HandleError, the page will always be called.

To force an error, let’s create a code that throws an exception inside the Index of the HomeController:

int a = 0;
int b = 0;
int result = a / b;

That will throw the DivideByZeroException, see the friendly page in action:

CustomErrros Error Handling

 

404 NotFound Page

For the Not Found page we don’t have much to tell the user, so there is not much to do. It’s only the redirect to a page and, the information we can show is the wrong path. That information already comes as a query string.

Just to centralize the error handling and make it more organized, let’s put our NotFound within our ErrorController. So, add your the following method to the ErrorController:

public ActionResult NotFound(string aspxerrorpath)
{
	ViewData["error_path"] = aspxerrorpath;

	return View();
}

and the aspx page code:

NotFound.aspx

<%@ Page Language="C#" MasterPageFile="~/Views/Shared/Site.Master" Inherits="System.Web.Mvc.ViewPage" %>

<asp:Content ID="errorTitle" ContentPlaceHolderID="TitleContent" runat="server">
    Not Found
</asp:Content>

<asp:Content ID="errorContent" ContentPlaceHolderID="MainContent" runat="server">
    <h2>
        Sorry, the page <%: ViewData["error_path"] %> does not exist.
    </h2>    
</asp:Content>

and add the following line for the Not Found error into your customErrors section:

<customErrors mode="On" defaultRedirect="Error">
  <error statusCode="404" redirect="Error/NotFound"/>
</customErrors>

See the result:CustomError Page Not Found

 

403 AccessDenied

Most of the times when someone doesn’t have access to a page it’s only a login issue. But there are also times that a user has logged in but they are allowed to see something or perform some task, maybe because the lack of sufficient privileges. I’m going to show here how to handle those type of errors and the way I do that is by creating an ActionFilter attribute that you can put on a class or a method.

I’m going to hide some code for clarity:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Configuration;
using System.Web.Configuration;

namespace ErrorHandling.Controllers
{
    public class AuthorizationAttribute : ActionFilterAttribute, IExceptionFilter
    {
        public string Action { get; set; }
        
        public override void OnActionExecuting(ActionExecutingContext filterContext)
        {
            //
            // check permissions

            if (accessDenied)
            {
                throw new System.Web.HttpException((int)System.Net.HttpStatusCode.Forbidden,
                        "You are now allowed to see this page.");
            }

            base.OnActionExecuting(filterContext);
        }

        #region IExceptionFilter Members

        // this method is almost a clone of HandleErrorAttribute from MVC
        // it's just changed so that we take the error message to the page set in the <customErrors>
        public virtual void OnException(ExceptionContext filterContext)
        {
            if (filterContext == null)
            {
                throw new ArgumentNullException("filterContext");
            }
            if (filterContext.IsChildAction)
            {
                return;
            }

            // If custom errors are disabled, we need to let the normal ASP.NET exception handler
            // execute so that the user can see useful debugging information.
            if (filterContext.ExceptionHandled || !filterContext.HttpContext.IsCustomErrorEnabled)
                return;

            Exception exception = filterContext.Exception;

            // If this is not an HTTP 403 (for example, if somebody throws an HTTP 500 from an action method),
            // ignore it.
            if (new HttpException(null, exception).GetHttpCode() != 403)
            {
                return;
            }

            // try to get the customError page for the 403 code
            string customErrorPage = GetCustomError("403");

            // if there isn't a redirect to a 403 error page then get out
            if (customErrorPage == null)
                return;

            filterContext.Result = new RedirectResult(String.Concat(customErrorPage, "?action=", this.Action));
            filterContext.ExceptionHandled = true;
            filterContext.HttpContext.Response.TrySkipIisCustomErrors = true;            
        }

        #endregion

        public string GetCustomError(string statusCode)
        {
            CustomErrorsSection customErrorsSection = ConfigurationManager.GetSection("system.web/customErrors") as CustomErrorsSection;

            if (customErrorsSection != null)
            {
                CustomError customErrorPage = customErrorsSection.Errors[statusCode];

                if (customErrorPage != null)
                    return customErrorPage.Redirect;
            }
            return null;
        }        
    }
}

What that code does is throw an 403 Exception if the user rights are not enough, then we implement the IExceptionFilter, so we can handle the error on our own way with the OnException method. Notice we are reading the customErrors section looking for the page that is set for the 403 code and redirecting the user to that page.

With that AuthorizationAttribute you can decorate any class or method that you want to be checked when a user access it, like so:

[AuthorizationAttribute]
[HandleError]
public class HomeController : Controller

Let’s create our page inside the Views folder (again, it can be the Shared or the Errors folder) to tell the user about the error:

AccessDenied.aspx

<%@ Page Language="C#" MasterPageFile="~/Views/Shared/Site.Master" Inherits="System.Web.Mvc.ViewPage" %>

<asp:Content ID="errorTitle" ContentPlaceHolderID="TitleContent" runat="server">
    Access Denied
</asp:Content>

<asp:Content ID="errorContent" ContentPlaceHolderID="MainContent" runat="server">
    <h2>
        Sorry, you do not have access to the action <%: ViewData["action"] %>.
    </h2>    
</asp:Content>

Add one more action method to our ErrorController:

public ActionResult AccessDenied(string action)
{
	ViewData["action"] = action;

	return View();
}

In this example, I’m passing in a parameter called “action” to the AccessDenied method, but it could be anything you want and can contain any information you want.

And finally, completing our Web.Config, we now add the treatment for the 403 error code:

<customErrors mode="On" defaultRedirect="Error">
  <error statusCode="404" redirect="Error/NotFound"/>
  <error statusCode="403" redirect="Error/AccessDenied"/>
</customErrors>

Here is how our ErrorController end up like:

namespace ErrorHandling.Controllers
{
    public class ErrorController : Controller
    {
        public ActionResult Index()
        {
            return View("Error");
        }

        public ActionResult NotFound(string aspxerrorpath)
        {
            ViewData["error_path"] = aspxerrorpath;

            return View();
        }

        public ActionResult AccessDenied(string action)
        {
            ViewData["action"] = action;

            return View();
        }
    }
}

With this structure the errors are very organized and all the things related to it are together.

Firing errors with any header status code

I spent a long time trying to get it right, so I thought it would be a good idea to post this here.

Yesterday I was creating a way to validate if the user has access to some page depending on their restrictions  that comes from a security system of the company.

Great. I created a new error page to show when the user access is denied and added it in the customErros within the Web.config.

Here is how the customErros end up like:

<customErrors mode="On" defaultRedirect="GenericError.aspx">
  <error statusCode="403" redirect="Unauthorized.aspx"/>
  <error statusCode="404" redirect="NotFound.aspx"/>      
</customErrors>

As this project is being developed using MVC I decided to implement it using the ActionFilter attributes. Here is the code:

public class CustomAuthorization : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext filterContext)
    {        
        try
        {
            // check the user
        }
        catch
        {
            // set the header but doesn't show the unauthorized page.
            // can be used to Ajax though
            //filterContext.HttpContext.Response.StatusCode = (int)System.Net.HttpStatusCode.Forbidden;
            
            // redirects to GenericError
            //throw new UnauthorizedAccessException();

            // this works as excpected!
            throw new System.Web.HttpException((int)System.Net.HttpStatusCode.Forbidden, "You do not have access to that page.");
        }
        base.OnActionExecuting(filterContext);
    }
}

The last statement works the way I wanted. It fires the exception setting the header status code to 403 and redirects to my page Unathorized.aspx

I’m sure I’ve already used that HttpException before, but just to make sure I won’t forget it again, now I wrote it down.