Back to Devexpress

ReportingConfigurationBuilder.UseAsyncEngine() Method

xtrareports-devexpress-dot-aspnetcore-dot-reporting-dot-reportingconfigurationbuilder.md

latest15.0 KB
Original Source

ReportingConfigurationBuilder.UseAsyncEngine() Method

Allows you to use asynchronous interfaces and methods.

Namespace : DevExpress.AspNetCore.Reporting

Assembly : DevExpress.AspNetCore.Reporting.v25.2.dll

NuGet Package : DevExpress.AspNetCore.Reporting

Declaration

csharp
public ReportingConfigurationBuilder UseAsyncEngine()
vb
Public Function UseAsyncEngine As ReportingConfigurationBuilder

Returns

TypeDescription
ReportingConfigurationBuilder

A ReportingConfigurationBuilder that can be used to further configure reporting services.

|

Remarks

The UseAsyncEngine method turns on asynchronous mode for the Web Document Viewer. It allows the application to access threads from the thread pool while reporting components load, save, or export reports.

Important

In asynchronous mode, you should use asynchronous interfaces and methods with the “Async” postfix instead of their counterparts.

Asynchronous mode does not guarantee that all services will call their asynchronous method implementations. If in your application you call the “synchronous” method counterpart, it may cancel asynchronous process execution, and subsequently reporting services start calling their synchronous method implementations.

To switch to asynchronous mode, call the UseAsyncEngine method at application startup:

csharp
using DevExpress.AspNetCore.Reporting;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureReportingServices(configurator => {
    configurator.UseAsyncEngine();
});

var app = builder.Build();

If you bind a reporting control to a report model (the WebDocumentViewerModel instance), the reporting engine uses asynchronous API calls. You should generate a report model in the controller and pass the model to the Document Viewer:

csharp
using System.Collections.Generic;
using System.ComponentModel.Design;
using System.IO;
using System.Threading.Tasks;
using DevExpress.AspNetCore.Reporting.WebDocumentViewer;
using DevExpress.DataAccess.Sql;
using DevExpress.XtraReports.Services;
using DevExpress.XtraReports.Web.ReportDesigner.Services;
using DevExpress.XtraReports.Web.WebDocumentViewer;
using Microsoft.AspNetCore.Mvc;

namespace ReportingAppAsyncServices.Controllers {
    public class HomeController : Controller
    {
        public IActionResult Index()
        {
            return View();
        }

        public async Task<IActionResult> Designer([FromServices] IReportDesignerModelBuilder reportDesignerModelBuilder, [FromQuery] string reportName = "RootReport")
        {
            var dataSources = new Dictionary<string, object>
            {
                ["Northwind"] = GetNorthwindSqlDataSource()
            };
            var designerModel = await reportDesignerModelBuilder
                .DataSources(dataSources)
                .Report(reportName)
                .BuildModelAsync();
            return View(designerModel);
        }

        public async Task<IActionResult> Viewer([FromServices] IWebDocumentViewerClientSideModelGenerator modelGenerator, [FromQuery] string reportName = "RootReport")
        {
            var viewerModel = await modelGenerator.GetModelAsync(reportName, WebDocumentViewerController.DefaultUri);
            return View(viewerModel);
        }
        public async Task<IActionResult> ExportToPdf([FromServices] IReportProviderAsync reportProviderAsync, [FromQuery] string reportName = "RootReport")
        {
            var report = await reportProviderAsync.GetReportAsync(reportName, null);
            var reportServiceContainer = (IServiceContainer)report;
            reportServiceContainer.RemoveService(typeof(IReportProviderAsync));
            reportServiceContainer.AddService(typeof(IReportProviderAsync), reportProviderAsync);
            using (var stream = new MemoryStream()) {
                await report.CreateDocumentAsync();
                await report.ExportToPdfAsync(stream);
                return File(stream.ToArray(), System.Net.Mime.MediaTypeNames.Application.Pdf);
            }
        }

        SqlDataSource GetNorthwindSqlDataSource()
        {
            // Create a SQL data source with the specified connection string.
            SqlDataSource ds = new SqlDataSource("NWindConnectionString");
            // Create a SQL query to access the Products data table.
            SelectQuery query = SelectQueryFluentBuilder.AddTable("Products").SelectAllColumnsFromTable().Build("Products");
            ds.Queries.Add(query);
            ds.RebuildResultSchema();
            return ds;
        }
    }
}

If a reporting control is bound to a report instance or a string (report name), the reporting engine does not use asynchronous methods and interfaces.

View Example: How to Use the Asynchronous Engine for Web Reporting

Asynchronous API

The following table lists interfaces and methods with their asynchronous counterparts:

Report Provider

A report provider creates or retrieves a report object based on the report identifier (report URL). When you implement a custom IReportProviderAsync service, use asynchronous methods. Note that in asynchronous mode, blocking requests use the IReportProvider service instead of the IReportProviderAsync service.

InterfaceAsync Counterpart
IReportProviderIReportProviderAsync

Web Report Storage (ReportStorageWebExtension class)

If your application includes a web report storage, and you wish to use the asynchronous engine, implement the async equivalents of the ReportStorageWebExtension methods. Note that in asynchronous mode, blocking requests use methods without the Async postfix.

MethodAsync Counterpart
GetDataGetDataAsync
noneAfterGetDataAsync
GetUrlsGetUrlsAsync
SetDataSetDataAsync
SetNewDataSetNewDataAsync

Report Model

Use async methods in controller actions to create a report model and pass it to the client.

MethodAsync Counterpart
WebDocumentViewerClientSideModelGenerator.GetModelWebDocumentViewerClientSideModelGenerator.GetModelAsync
ReportDesignerClientSideModelGenerator.GetModelReportDesignerClientSideModelGenerator.GetModelAsync

Report

MethodAsync Counterpart
CreateDocumentCreateDocumentAsync
ExportToCsvExportToCsvAsync
ExportToDocxExportToDocxAsync
ExportToHtmlExportToHtmlAsync
ExportToImageExportToImageAsync
ExportToMailExportToMailAsync
ExportToMhtExportToMhtAsync
ExportToPdfExportToPdfAsync
ExportToRtfExportToRtfAsync
ExportToTextExportToTextAsync
ExportToXlsExportToXlsAsync
ExportToXlsxExportToXlsxAsync
PrintPrintAsync

JSON Web Token Authentication

InterfaceAsync Counterpart
IWebDocumentViewerExportResultUriGeneratorIWebDocumentViewerExportResultUriGeneratorAsync

Report Wizard Customization Service

MethodAsync Counterpart
CustomizeReportTypeListCustomizeReportTypeListAsync
TryCreateCustomReportTryCreateCustomReportAsync
CustomizeReportOnFinishCustomizeReportOnFinishAsync

The following code snippets (auto-collected from DevExpress Examples) contain references to the UseAsyncEngine() method.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

reporting-asp-net-core-drill-through/CS/Startup.cs#L33

csharp
});
    configurator.UseAsyncEngine();
});

reporting-asp-net-core-azure-blob-storage/CS/Program.cs#L30

csharp
});
    configurator.UseAsyncEngine();
});

reporting-asp-net-core-set-print-job-name-in-printer-queue/CS/dxExampleWebDocViewerChangeJobPrintName/Startup.cs#L54

csharp
});
    configurator.UseAsyncEngine();
});

reporting-asp-net-core-content-security-policy/CS/CSPExample/Startup.cs#L39

csharp
});
    configurator.UseAsyncEngine();
});

See Also

ReportingConfigurationBuilder Class

ReportingConfigurationBuilder Members

DevExpress.AspNetCore.Reporting Namespace