Setting up the Web Report Designer in .NET applications
This article shows how to integrate our Web Report Designer in .NET 6+
applications.
The quickest way to add the web report designer to a web project is with the Telerik Web Report Designer item template in Visual Studio. The item template is compatible with projects targetting .NET 6+
. The item template adds a page with the Web Report Designer and, if needed, enables the Web Report Designer REST Service. To start the item template wizard, in Visual Studio Solution Explorer
, select the target project. On the Project menu, click Add
-> New Item
. In the Add New Item search box enter "Telerik Web Report Designer" and select the item template which corresponds to your project type.
For full control, instead of using the item template, you can manually configure the REST service and add the web report designer as elaborated in the rest of this article.
Prerequisites
- Create a sample ASP.NET Core Project targeting .NET 6 or higher. It may be an empty Web project or a Web API project.
-
Add the required dependencies:
Telerik.WebReportDesigner.Services
Telerik.Reporting.Services.AspNetCore
Telerik.Reporting.JsonSerialization
Telerik.Reporting
When you use NuGet packages, you may add only the Telerik.WebReportDesigner.Services
package as it depends on the rest of the required Telerik Reporting assemblies, so they will be added automatically. Their dependencies will also be resolved automatically. For more information, see How to add the Telerik private NuGet feed to Visual Studio.
If you don't use NuGet packages, along with the above assemblies, you need to add all their dependencies manually to the project.
If you need to enable users to export reports in Office OpenXML document formats (XLSX, DOCX, and PPTX), you must install the DocumentFormat.OpenXML and
the Telerik.Reporting.OpenXmlRendering
NuGet packages. For more information about the required package versions, see Deploying Open XML.
Add Required Settings in the Startup.cs
file
Some of the Visual Studio template projects, like the .NET 6 Web API project, have the required settings already added by default. In the empty .NET Web projects, you may need to add manually the settings.
-
The
ConfigureServices
method inside theStartup.cs
in the project should be modified in order to enable the Web Report Designer Service functionality. Make sure the application is configured for WebAPI controllers and call theAddNewtonsoftJson
to place the NewtonsoftJson serialization:services.AddControllers().AddNewtonsoftJson();
-
Make sure the endpoints configuration inside the
Configure
method of theStartup.cs
are configured for API controllers by adding the following line in the lambda expression argument:app.UseEndpoints(endpoints => { endpoints.MapControllers(); //... });
-
Assure that the app configuration inside the
Configure
method of theStartup.cs
can serve static files:app.UseStaticFiles();
Add Configuration Settings in the Startup.cs file
The report generation engine can retrieve Sql Connection Strings and specific Report Generation Engine Settings that provide flexibility for the deployed application. It utilizes the IConfiguration interface for this purpose.
The ASP.NET Core applications use a key-value JSON-based file named by default appSettings.json
. The default ReportingEngineConfiguration:
ReportingEngineConfiguration = sp.GetService<IConfiguration>()
will be initialized from appSettings.json
or appsettings.{EnvironmentName}.json
.
To activate JSON file configuration with a different name, for example, reportingAppSettings.json
, call the AddJsonFile extension method on an instance of ConfigurationBuilder. Here are the exact steps to follow:
-
Add a new
ResolveSpecificReportingConfiguration
class as a separate file or in theStartup.cs
filestatic IConfiguration ResolveSpecificReportingConfiguration(IWebHostEnvironment environment) { var reportingConfigFileName = System.IO.Path.Combine(environment.ContentRootPath, "reportingAppSettings.json"); return new ConfigurationBuilder() .AddJsonFile(reportingConfigFileName, true) .Build(); }
-
Add the required services in the
ConfigureServices
methodpublic void ConfigureServices(IServiceCollection services) { services.AddControllers().AddNewtonsoftJson(); services.TryAddSingleton<IReportServiceConfiguration>(sp => new ReportServiceConfiguration { ReportingEngineConfiguration = ResolveSpecificReportingConfiguration(sp.GetService<IWebHostEnvironment>()), HostAppId = "ReportingCoreApp", Storage = new FileStorage(), ReportSourceResolver = new TypeReportSourceResolver().AddFallbackResolver (new UriReportSourceResolver(Path.Combine(sp.GetService<IWebHostEnvironment>().WebRootPath, "Reports"))) }); services.TryAddSingleton<IReportDesignerServiceConfiguration>(sp => new ReportDesignerServiceConfiguration { DefinitionStorage = new FileDefinitionStorage(Path.Combine(sp.GetService<IWebHostEnvironment>().WebRootPath, "Reports"), new[] { "Resources", "Shared Data Sources" }), ResourceStorage = new ResourceStorage(Path.Combine(sp.GetService<IWebHostEnvironment>().WebRootPath, "Reports", "Resources")), SharedDataSourceStorage = new FileSharedDataSourceStorage(Path.Combine(sp.GetService<IWebHostEnvironment>().WebRootPath, "Reports", "Shared Data Sources")), SettingsStorage = new FileSettingsStorage(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), "Telerik Reporting")) }); }
Setting up the Report Designer REST service:
The REST service works as a backend and is responsible for storage operations like creating, opening, or saving report definitions. The following steps describe how to configure it:
- Make sure that a key-value JSON-based file is available in your project and add the required configuration settings in it, for example, the
ConnectionStrings
. - Implement a Report Designer controller. Right-click on the
Controllers
folder and add a new item: Add > New item... > Web API Controller Class item. Name it ReportDesignerController. This will be our Telerik Web Report Designer REST service in the project. -
Inherit the
ReportDesignerControllerBase
type and inject the required configuration settings in the constructor. Along with theReportServiceConfiguration
there is another configuration instance namedReportDesignerServiceConfiguration
, which will initialize the definition storage. This is the class responsible for opening, saving, etc. the report definitions. This is how a basic implementation of the controller should look like:namespace CSharp.AspNetCoreDemo.Controllers { using Microsoft.AspNetCore.Mvc; using Telerik.Reporting.Services; using Telerik.WebReportDesigner.Services; using Telerik.WebReportDesigner.Services.Controllers; [Route("api/reportdesigner")] public class ReportDesignerController : ReportDesignerControllerBase { public ReportDesignerController(IReportDesignerServiceConfiguration reportDesignerServiceConfiguration, IReportServiceConfiguration reportServiceConfiguration) : base(reportDesignerServiceConfiguration, reportServiceConfiguration) { } } }
-
To ensure the service operates, run the application and navigate to URL
{applicationRoot}/api/reportdesigner/cultureContext
. It should return a JSON representing the separators determined by the current culture, for example:{"decimalSeparator":".","listSeparator":","}
Adding the Web Report Designer:
-
Add TRDP or TRDX report definitions in the dedicated folder, specified in the DefinitionStorage and
UriReportSourceResolver
of the services configurations. In the sample code, this isPath.Combine(sp.GetService<IWebHostEnvironment>().WebRootPath, "Reports")
and corresponds to the folder Reports in the wwwroot folder. Add the latter to the main application folder if it doesn't exist. You may add to the Reports folder one of our demo reports that can be found by default in {Telerik Reporting installation path}\Report Designer\Examples.
-
Add a new HTML Page for the Web Report Designer by right-clicking on wwwroot and Add > New Item... > HTML Page. Name the file
index.html
. Add the required references to load the font, jQuery, Telerik Kendo UI libraries, telerikReportViewer, and webReportDesigner scripts listed in the example below. Finally, add the initialization of the telerik_WebReportDesigner widget. Note that the Web Report Designer container has a minimum width of 1200px. The complete report viewer page should look like this:<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Telerik Web Report Designer</title> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <link href="https://fonts.googleapis.com/css?family=Roboto:400,500&display=swap" rel="stylesheet"> </head> <body> <div id="webReportDesigner"> loading... </div> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script> <script src="https://kendo.cdn.telerik.com/2022.3.913/js/kendo.all.min.js"></script> <script src="/api/reportdesigner/resources/js/telerikReportViewer/"></script> <script src="/api/reportdesigner/designerresources/js/webReportDesigner/"></script> <script type="text/javascript"> $(document).ready(function () { $("#webReportDesigner").telerik_WebReportDesigner({ toolboxArea: { layout: "list" //Change to "grid" to display the contents of the Components area in a flow grid layout. }, serviceUrl: "/api/reportdesigner", report: "Barcodes Report.trdp" }).data("telerik_WebDesigner"); }); </script> </body> </html>
To set up the
index.html
as a startup page check Make index.html as startup file in ASP.NET Core. Then, change the launchUrl to index.html inlaunchSettings.json
.- Finally, run the project to preview the web designer.
Examples
You may find the complete example setup of the Web Report Designer in the Html5IntegrationDemo project for the corresponding target framework deployed with the installation of the product. The default installation folder is C:\Program Files (x86)\Progress\Telerik Reporting 2024 Q3\Examples\CSharp
.