How to handle Report Load and Error Events in Blazor App

This tutorial explains how to handle report loading and error‑related events in the Bold Reports^® Web Report Viewer within a Blazor application. The video demonstrates how developers can track successful report loading and manage errors that occur during report processing or rendering.

Setup

Add the following code to the BoldReportViewerOptions.cs file. This defines the ReportViewerEvents and CallBacks for linking event names to handler methods.

namespace BlazorReportingTools.Data
{
    public static class ReportViewerEvents
    {
        public const string ReportLoaded = "reportLoaded";
        public const string ReportError  = "reportError";
        public const string ShowError    = "showError";
    }

    public class BoldReportViewerOptions
    {
        public string ReportName { get; set; } = string.Empty;
        public string ServiceURL { get; set; } = string.Empty;
        public Dictionary<string, string> CallBacks { get; set; } = new();
    }
}

In the Pages folder, add the following code to the index.razor file. This configures the report viewer settings and uses JavaScript interop to allow the viewer to trigger event callbacks within the Blazor page.

@page "/"
@implements IAsyncDisposable
@inject IJSRuntime JSRuntime

<div id="report-viewer"></div>

@code {
    private BoldReportViewerOptions viewerOptions = new();
    private DotNetObjectReference<Index>? dotNetReference;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            viewerOptions.ReportName = "sales-order-detail";
            viewerOptions.ServiceURL = "/api/BoldReportsAPI";
            viewerOptions.CallBacks = new Dictionary<string, string>
            {
                [ReportViewerEvents.ReportLoaded] = nameof(Index.OnReportLoaded),
                [ReportViewerEvents.ReportError]  = nameof(Index.OnReportError),
                [ReportViewerEvents.ShowError]    = nameof(Index.OnShowError)
            };

            dotNetReference = DotNetObjectReference.Create(this);
            await JSRuntime.InvokeVoidAsync("BoldReports.RenderViewer",
                dotNetReference, "report-viewer", viewerOptions);
        }
    }

    public async ValueTask DisposeAsync()
    {
        dotNetReference?.Dispose();
        await ValueTask.CompletedTask;
    }
}

Interop File

Add the following code in the wwwroot/scripts/boldreports-interop.js file.

window.BoldReports = {
    Events: {
        ReportLoaded: "reportLoaded",
        ReportError:  "reportError",
        ShowError:    "showError"
    },

    RenderViewer: function (dotNetReference, elementId, viewerOptions) {
        var callbacks = viewerOptions.CallBacks || {};
        var events = window.BoldReports.Events;

        var invoke = function (eventKey, args) {
            if (dotNetReference && callbacks[eventKey]) {
                dotNetReference.invokeMethodAsync(callbacks[eventKey], args);
            }
        };

        $("#" + elementId).boldReportViewer({
            reportPath: viewerOptions.ReportName,
            reportServiceUrl: viewerOptions.ServiceURL,

            // Notifies the Blazor component after the report is loaded.
            reportLoaded: function (args) { invoke(events.ReportLoaded, args); },

            // Notifies the Blazor component when a report error occurs.
            reportError: function (args) { invoke(events.ReportError, args); },

            // Notifies the Blazor component before the error dialog is shown.
            showError: function (args) { invoke(events.ShowError, args); }
        });
    }
};

Event Handlers

Add the following event handler methods in the index.razor file in the Pages folder. The [JSInvokable] attribute allows the interop file to call each method when the viewer fires the corresponding event. The args parameter carries the event details passed from the viewer.

Report Loaded

Fires when the report is loaded successfully. This event can be used to perform actions once the report is rendered and ready for user interaction.

[JSInvokable]
public Task OnReportLoaded(string args)
{
    return ShowToastAsync("Report loaded successfully.");
}

Report Error

Fires when an error occurs during report processing or rendering. This event allows you to capture error details and perform custom actions such as logging or displaying messages.

[JSInvokable]
public Task OnReportError(string args)
{
    return ShowToastAsync("A report error occurred.");
}

Show Error

Fires when the user clicks a failed report item in the rendered report, before displaying the error details dialog. This event allows you to customize or cancel the default error dialog behavior.

[JSInvokable]
public Task OnShowError(string args)
{
    return ShowToastAsync("Showing the error details dialog…");
}

Implementation Workflow

Report Load Tracking

Use the report Loaded event to determine when a report has been successfully rendered.

Error Handling

Use the report Error and show Error events to capture failures and control how error information is presented to users.

To get more details about Report Load and Error Events in Blazor applications, you can check this video: