ReportsV2Module - Migration from DxDocumentViewer to DxReportViewer

What Changed

In v24.1+, we migrated our Reports V2 Module from DxDocumentViewer to the native DxReportViewer component.

Reasons for Change

We replaced DxDocumentViewer from DevExpress.Blazor.Reporting.v23.2.JSBasedControls with DxReportViewer. For more information about DxReportViewer, refer to the following blog post: Reporting — New Native Report Viewer for Blazor Server.

Impact on Existing Apps

This change affects you application if you are using the Reports V2 Module.

How to Update Existing Apps

If you access DxDocumentViewer or DxDocumentViewerAdapter instances in your code, you need to refactor it and use ReportViewer or DxReportViewerAdapter classes respectively. For more information, refer to the updated help topic: How to: Access the Report Preview Control (Blazor).

Old Code

C#
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.ReportsV2.Blazor;
// ...
public class AccessReportViewerController : ViewController<DetailView> {
    public AccessReportViewerController() {
        TargetViewId = ReportsBlazorModuleV2.ReportViewerDetailViewName;
    }
    protected override void OnActivated() {
        base.OnActivated();
        View.CustomizeViewItemControl<ReportViewerViewItem>(this, CustomizeReportViewerViewItem);
    }
    private void CustomizeReportViewerViewItem(ReportViewerViewItem reportViewerViewItem) {
        string reportName = ((ReportViewerViewItem.DxDocumentViewerAdapter)reportViewerViewItem.Control).ComponentModel.ReportName;
        // ...
    }
}

New Code

C#
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.ReportsV2.Blazor;
using DevExpress.XtraReports;

namespace YourSolutionName.Blazor.Server.Controllers;

public class AccessReportViewerController : ViewController<DetailView> {

    public AccessReportViewerController() {
        TargetViewId = ReportsBlazorModuleV2.ReportViewerDetailViewName;
    }

    protected override void OnActivated() {
        base.OnActivated();
        View.CustomizeViewItemControl<ReportViewerViewItem>(this, CustomizeReportViewerViewItem);
    }

    private void CustomizeReportViewerViewItem(ReportViewerViewItem reportViewerViewItem) {
        //Access the Report Viewer's control.
        IReport report = reportViewerViewItem.ReportViewerModel.Report;
        // ...
    }
}

The ReportViewerModel object contains all the customization callbacks as well. You can implement any technique illustrated in the Customization - Report Viewer for Blazor (Native) help topic or the Reporting for Blazor - Email a Report from the Native Blazor Report Viewer GitHub repo. The following example adds a custom toolbar button to the report reviewer:

C#
private void CustomizeReportViewerViewItem(ReportViewerViewItem reportViewerViewItem) {
            reportViewerViewItem.ReportViewerModel.OnCustomizeToolbar = EventCallback.Factory.Create<ToolbarModel>(this, (m) => {
                var customToolbarItem = new ToolbarItem() {
                    Text = "Custom Command",
                    AdaptiveText = "Custom Command",
                    Click = (args) => {
                        Application.ShowViewStrategy.ShowMessage("Test Message", InformationType.Success);
                        return Task.CompletedTask;
                    }
                };
                m.AllItems.Add(customToolbarItem);
            });
        }

Report Localization

If you have a localization controller in your ASP.NET Core Blazor project (YourSolutionName.Blazor.Server\Controllers\ReportLocalizationController.cs), NullReferenceException (Object reference not set to an instance of an object) occurs when you access propertyEditor.DocumentViewerCallbacksModel.

To resolve the issue, check for null or remove this method:

C#
private async void CustomizeReportViewer(ReportViewerViewItem propertyEditor) {
    if(propertyEditor.DocumentViewerCallbacksModel is not null) {
        propertyEditor.DocumentViewerCallbacksModel.CustomizeLocalization = "ReportingLocalization.onCustomizeLocalization";
        await jSRuntime.InvokeVoidAsync("ReportingLocalization.setCurrentCulture", cultureInfoService.CurrentCulture.Name);
    }
}

Our new report viewer uses a standard localization approach and no longer needs additional changes in your application. However, our report designer still needs additional changes for localization. For more information, refer to Localize an XAF Application (.NET).

How to Revert to Previous Behavior

In the SolutionName.Blazor.Server/Program.cs file of your ASP.NET Core Blazor application project, set FrameworkSettings.DefaultSettingsCompatibilityMode to the previous version or set the ReportsBlazorModuleV2.ReportViewerType property value to ReportViewerType.DxDocumentViewer:

C#
public static int Main(string[] args) {
    DevExpress.ExpressApp.FrameworkSettings.DefaultSettingsCompatibilityMode = DevExpress.ExpressApp.FrameworkSettingsCompatibilityMode.v23_2;
    // or
    DevExpress.ExpressApp.ReportsV2.Blazor.ReportsBlazorModuleV2.ReportViewerType = DevExpress.ExpressApp.ReportsV2.Blazor.ReportViewerType.DxDocumentViewer;
}