Custom error pages for ASP.NET Web Forms and Classic ASP in IIS 7 and 8.5

I was recently doing some work on a website which has a mixture of older Classic ASP pages and ASP.NET Web Forms pages. The website is running on IIS 8.5 and .NET framework 4.x.

The website has some code that sent email notifications of any Classic ASP server errors, but nothing for .NET errors. It also has custom 404 and 500 error pages for Classic ASP but nothing for ASP.NET.

I attempted to create some custom error pages and email notification for .NET but ran into some troubles along the way.

Here's what you need to do and some of the things that can go wrong.

httpErrors element

This is under system.webServer in the web.config file and is used for non-aspx pages.

Here you can set your custom 404 page not found errors for Classic ASP and other non-aspx pages, like images or folders.

You can also set your custom error pages for 500 internal server errors.

My Classic ASP error email notification code is in the custom 500 error page (coded in Classic ASP of course). One problem I came across here was that Server.GetLastError was not reporting any error. I found that you must specify the 100 subStatusCode of the 500 error here to get the details of the error with Server.GetLastError.

Here's a sample of this section from my working web.config:

<system.webServer>
	<httpErrors errorMode="Custom">
		<remove statusCode="404" subStatusCode="-1" />
		<error statusCode="404" prefixLanguageFilePath="" path="/_Error404.aspx" responseMode="ExecuteURL" />
		<remove statusCode="500" subStatusCode="100" />
		<error statusCode="500" subStatusCode="100" prefixLanguageFilePath="" path="/_Error500.asp" responseMode="ExecuteURL" />
	</httpErrors>
</system.webServer>

Note that I use an aspx page for my custom 404 error page so I only need one for all 404 errors, but I have a asp page for my custom 500 error page so I can send email notifications.

customErrors element

This is under system.web in the web.config and is used for aspx pages.

Here's a sample from my working web.config:

<system.web>
	<customErrors mode="On" redirectMode="ResponseRewrite">
		<error statusCode="404" redirect="/_Error404.aspx" />
	</customErrors>
</system.web>

Note that I only trap for 404 errors for aspx page requests here.

Setting the redirectMode to ResponseRewrite means that the user does not get redirected to the custom error pages. However, one problem that I ran into with this setting is that my aspx custom 404 error page didn't show, I just saw an application error. The problem is that Session is not available if you use ResponseRewrite so you must not attempt to access the Session object in your custom error page.

Trapping 500 internal server errors for aspx pages

You could trap these errors also in the customErrors element but I chose to do this instead in the global.asax page.

I send my email error notification then use Server.Transfer to show the custom 500 error page, like this:

void Application_Error(object sender, EventArgs e)
{
	//error notification code here

	Server.Transfer("/_Error500.aspx");
}

Notes about custom 500 error pages

It should be obvious but your custom 500 error pages should not include any code that might cause an error itself, or at least it should be handled properly.

For this reason I generally use a very simple custom 500 error page with no database calls. I don't use my website's MasterPage as that usually has code for things like logged-in user, or shopping cart lookups that might result in errors.

If you're sending email notifications it's also a good idea to handle mail sending errors in case your mail server is down. That way the user still sees your friendly error message.

Custom 404 errors don't have this problem (except for the abovementioned Session object issue) so can be rich in content and have full functionality. In fact it's good practice to make your custom 404 error pages as helpful as possible: attempt to offer an alternate page that you think matches the user's original request; briefly explain what your website is all about; and, offer a next relevant step for the user so that hopefully they don't leave your site.