Error Pages in Kentico Xperience
In Part I: An Introduction to ASP.NET Core StatusCodePages, we explored how the ASP.NET Core StatusCodePages Middleware can be used to provide user-friendly error pages from the Kentico Xperience Content Tree. We expanded upon this implementation in Part II: Implementing Kentico Xperience StatusCodePages Middleware to support Page Routing via a custom Request Delegate. In this conclusion to the Error Page in Kentico Xperience series, we'll explore the
BizStream/xperience-status-code-pages repository, and how the two NuGet packages
BizStream.Kentico.Xperience.AspNetCore.StatusCodePages published from it, can be used to quickly get started with StatusCodePages powered by Kentico Xperience.
Using the BizStream Kentico Xperience StatusCodePages Packages
BizStream maintains two NuGet packages that can be used for quickly spinning up StatusCodePages in an Xperience solution:
BizStream.Kentico.Xperience.Adminstration.StatusCodePages: Contains an object archive defining a
StatusCodeNode, akin to the
HttpErrorNode described in previous parts of this series, and a Module that auto-imports the included object archive, thus importing the
StatusCodeNode Page Type object into the target EMS solution.
BizStream.Kentico.Xperience.AspNetCore.StatusCodePages: Contains the StatusCodePages middleware, a default controller and view, and extension methods to use Kentico Xperience powered StatusCodePage in an ASP.NET Core MVC project.
Installing the Administration Package
To begin with Xperience StatusCodePages, the
BizStream.Kentico.Xperience.Adminstration.StatusCodePages package must be installed into the
CMSApp project, using the "Install NuGet Packages" option within Visual Studio, or using the Package Manager Console:
Upon installing the Administration NuGet package, a
CMSSiteUtils/Import/BizStream_StatusCodePages.zip file should now be visible within the Solution Explorer (if not, you may need to Show All Files in the project), this Object Archive contains the Page Types & Form Controls needed to manage Error Pages within the Pages application.
To finalize installation of the Object Archive, start a new Debug session or execute Kentico CI against the target
CMSApp. This will result in the initialization of the
StatusCodePagesModule, which will execute the registered
IStatusCodePagesImportProvider implementation to automatically import objects within the
If Kentico CI was ran, XML files for the
StatusCodeNode Page Type, among other object types, should now exist in the CI Repository folder, or if a Debug session was ran, the Event Log can be checked for errors from the
StatusCodePagesImportProvider. After successfully importing objects, as indicated by the Event Log, the
BizStream_StatusCodePages.zip file can be deleted locally and removed from the
The Administration package contains build .props/.targets files that ensure the BizStream_StatusCodePages.zip archive is included in MSBuild Publish artifacts. This ensures the file exists when promoting the CMSApp through environments when using WebDeploy / Visual Studio Publish Profiles. When installing the Adminstration package, NuGet adds references to these .props/.targets files within the CMSApp.csproj.
With the Administration package installed and initialized,
StatusCodeNodes can now be added to the Content Tree within the Pages application:
If the StatusCodeNode is not visible in the "Add Page" menu, it may need to be manually assigned to the correct Site within the "Page Types" application.
Installing the AspNetCore Package
After installing the Administration package into the CMSApp, the BizStream.Kentico.Xperience.AspNetCore.StatusCodePages must be installed into the Xperience ASP.NET Core MVCMvc project:
dotnet add package BizStream.Kentico.Xperience.AspNetCore.StatusCodePages
<PackageReference Include="BizStream.Kentico.Xperience.AspNetCore.StatusCodePages" Version="x.x.x" />
Upon installing the AspNetCore NuGet package, the Startup.cs must be updated to add required services, and to configure the middleware:
public class Startup
public void ConfigureServices( IServiceCollection services )
public void Configure( IApplicationBuilder app, IWebHostEnvironment environment )
if( environment.IsDevelopment() )
// default behavior is 'ReExecute'
Finally, the StatusCodeNode must be registered for Page Routing with Kentico. The AspNetCore package provides a default Controller & View that can be registered using the
BizStream recommends creating a
RegisterPageRoutes.cs file in the root of your MVC project. Additionally, BizStream recommends segmenting Kentico Xperience related components of the MVC site in a Razor Class Library, for example, refer to the MVC.Kentico.Xperience Class Library in
Alternatively, if you require greater control, the base RegisterPageRouteAttribute provided by the Kentico API can be used for registering the route, for example:
[assembly: RegisterPageRoute( StatusCodeNode.CLASS_NAME, typeof( ErrorController ) )]
Testing it Out
With the packages installed, and a "Not Found" page configured in the Content Tree, debugging the MVC site in a mode other than Development and navigating to an invalid path shall yield a page from the Kentico Xperience Content Tree:
Learn More on GitHub
Learn more about ASP.NET Core StatusCodePages + Kentico Xperience Middleware on GitHub at
BizStream/xperience-status-code-pages. Stay up to date on implementation details, open a PR, or just ask a question!
If you are looking for more help with your Kentico Xperience projects, feel free to reach out to BizStream directly.