Handle Server-Side Errors in the Document Viewer in ASP.NET Core Application

May 13, 2025
3 minutes to read

This document describes how to handle server-side errors in End-User Report Designer and Document Viewer. It also explains how to display detailed error information instead of a generic “Internal Server Error” message.

View Example: How to handle server-side errors in ASP.NET Core reporting controls

You can create a descendant from the WebDocumentViewerExceptionHandler class and override its methods to process all or specific errors. This class implements the IWebDocumentViewerExceptionHandler interface.

Handle Unknown Exceptions

The Document Viewer and End-User Report Designer displays the “Internal Server Error” message in a browser for all exceptions except FaultException and DocumentCreationException. For instance, such unknown exceptions occur when you try to open a broken report layout or a file that does not exist.

You can override the GetUnknownExceptionMessage method to return a custom text or the Exception.Message property’s value as shown in the following example.

csharp

using System;
using System.IO;
using DevExpress.XtraReports.Web.WebDocumentViewer;

public class CustomWebDocumentViewerExceptionHandler : WebDocumentViewerExceptionHandler {
    public override string GetUnknownExceptionMessage(Exception ex) {
        if (ex is FileNotFoundException) {
#if DEBUG
            return ex.Message;
#else
            return "File is not found.";
#endif
            }
        return $"{ex.GetType().Name} occurred. See the log file for more details.";
        }
    }
}

Handle FaultException

The Document Viewer shows the Exception.Message property’s value when FaultException occurs (for instance, when you pass an invalid URL to a report storage).

Use the GetFaultExceptionMessage method to return a custom message for these exceptions as demonstrated below.

csharp

using System;
using DevExpress.XtraReports.Web.ClientControls;
#if NETFRAMEWORK
using System.ServiceModel;
# endif
using DevExpress.XtraReports.Web.WebDocumentViewer;

public class CustomWebDocumentViewerExceptionHandler : WebDocumentViewerExceptionHandler {
    public override string GetFaultExceptionMessage(FaultException faultException) {
        return $"FaultException occurred: {faultException.Message}.";
    }
}

Handle DocumentCreationException

The Document Viewer displays the Exception.Message property’s value for DocumentCreationException. This exception can occur when a report document is being generated (for instance, an error arises in the BeforePrint or AfterPrint event).

You can override the GetDocumentCreationExceptionMessage method to return a custom text as shown below.

csharp

using DevExpress.XtraReports.Web.WebDocumentViewer;

public class CustomWebDocumentViewerExceptionHandler : WebDocumentViewerExceptionHandler {
    public override string GetDocumentCreationExceptionMessage(DocumentCreationException ex) {
        return "An exception occurred while document creation.";
    }
}

Handle All Exceptions

Use the GetExceptionMessage method to handle all server-side errors independently from their types.

The code snippet below demonstrates how to override this method and return a custom text for all exceptions.

csharp

using System;
using System.IO;
using DevExpress.XtraReports.Web.WebDocumentViewer;

public class CustomWebDocumentViewerExceptionHandler : WebDocumentViewerExceptionHandler {
    public override string GetExceptionMessage(Exception ex) {
        return $"{ex.GetType().Name} occurred. See the log file for more details.";
    }
}

Register Exception Handler

To register the implemented exception handler, use the ServiceCollectionServiceExtensions class in the application startup file.

csharp

using Microsoft.Extensions.DependencyInjection;
using DevExpress.XtraReports.Web.WebDocumentViewer;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<IWebDocumentViewerExceptionHandler, CustomWebDocumentViewerExceptionHandler>();

var app = builder.Build();