How to handle custom 404 pages programmatically
Kentico provides the possibility to configure the system to display custom pages instead of standard error messages. Custom pages are convenient for site visitors because they can improve the security of the site by hiding potentially sensitive internal data (such as code in stack traces).
The <customErrors> element under the <system.web> section of the web.config file handles this functionality. However, what if you need to handle custom 404 pages within the code?
Kentico currently contains multiple undocumented methods to return custom 404 pages from the code, but none of them is actually able to return a custom 404 in a way that Kentico can display it correctly. So how can you handle custom 404 errors programmatically in a way that Kentico can display them in all possible cases?
As mentioned previously, custom error messages are currently handled by the <customErrors> element. This element has the following characteristics:
- It’s an obsolete functionality
- It’s still available in IIS7
- You can specify custom error pages for requests handled by ASP.NET
- It only handles requests within the ASP.NET application
- Static files such as HTML files or directory (“friendly”) URLs are not handled
How the Kentico system handles the following situations
Response.StatusCode = 404;
- Does not redirect, but returns the original page with a 404 code. That means, <customErrors> won't handle this case
throw HttpException("404", "Not found");
- Uses 302 redirect – however this is not SEO friendly, e.g. http://localhost/404App/WebForm1.aspx redirects to http://localhost/404App/Errors/404.aspx?aspxerrorpath=/404App/WebForm1.aspx
Another option is to use <httpErrors> which has the following characteristics:
- Introduced in IIS7
- Specifies custom error pages for requests handled by IIS
- Handles requests within the ASP.NET application
- All files and URLs are handled
How to use <httpErrors>
<httpErrors errorMode="Custom" existingResponse="Replace">
<remove statusCode="404" subStatusCode="-1" />
<error statusCode="404" path="/404App/Errors/404.aspx" responseMode="ExecuteURL"/>
</httpErrors>
Example use case for Kentico 10 and Kentico 11
Let’s say I want to display a 404 page rendered by Portal engine for only some values of query strings (e.g. custom table detail page):
- I do not want to redirect (302) to a 404 page
- I want to display a proper Kentico 404 page for this URL
I would need to:
- Leave the setting Page not found URL (under the Content section of the Settings application) empty
- Let .NET handle the 404 errors:
<httpErrors errorMode="Custom" existingResponse="Auto">
<remove statusCode="404" subStatusCode="-1" />
<error statusCode="404" path="/CMS/404.aspx" responseMode="ExecuteURL"/>
</httpErrors>
(path is a full server path including the application path, starting with a trailing slash)
- Make sure that the 404 page returns the 404 status code:
public void Page_Load(object sender, EventArgs e)
{
CMSHttpContext.Current.Response.StatusCode = 404;
}