Progress® Telerik® Reporting R1 2019

.NET Core Support

This article explains how to use reports in a .NET Core application for Windows, Linux, and macOS platforms.

Telerik Reporting provides a set of assemblies and NuGet packages designed to be used in .NET Core projects. The assemblies can be found in the \Bin\netstandard2.0\ folder of Telerik Reporting installation directory. The assemblies are built against .NET Standard 2.0 framework, which ensures compatibility with a greater variety of frameworks and applications. The external dependencies are resolved through NuGet package dependencies in order to provide better dependency management and code portability.

Requirements

Below are listed the NuGet packages that need to be included to a .NET Core application that uses Telerik Reporting. These dependencies are automatically resolved when using the Telerik.Reporting.Services.AspNetCore package. Otherwise they need to be manually added to the project.

Package name

Version

Microsoft.Extensions.Configuration 

2.1.2001 

Microsoft.Extensions.Configuration.Binder 

2.1.2001 

Microsoft.Extensions.Configuration.Json 

2.1.2001 

System.Configuration.ConfigurationManager 

4.5.2000 

System.Data.Common 

4.3.2000 

System.Data.SqlClient 

4.6.2000 

System.Drawing.Common 

4.5.2001 

System.IO.Packaging 

4.5.2000 

System.Reflection.Emit 

4.3.2000 

System.Reflection.Emit.Lightweight 

4.3.2000 

System.Runtime.Loader 

4.3.2000 

System.Security.Cryptography.Pkcs 

4.5.2001 

System.Security.Permissions 

4.5.2000 

System.Text.Encoding.CodePages 

4.5.2000 

System.Threading.AccessControl 

4.5.2000 

sqlite-net-pcl 

1.5.231 

Implemented Features and Limitations

All the major Telerik Reporting functionalities work in .NET Core CLI and web applications. On Windows, the reporting engine still relies on GDI+ library because it provides the fastest and most convenient way to process text, which is essential to the product. In Windows environment .NET Core runtime manages to resolve the GDI+ calls natively, but for Linux and macOS a set of libraries needs to be installed (see below). Almost all of the processing and rendering features that work on Windows using .NET Framework 4 or higher, will work in .NET Core projects with the new .NET Standard assemblies.

As a down-side, the report item designers are not .NET Standard-compatible, hence no design-time support in Visual Studio is available and type reports are not supported. In such scenario the reports can be converted to .trdx/.trdp definitions through the Standalone Report Designer’s Import Wizard or these classes can be used as runtime-created report instances. Report definitions, created in Visual Studio, can be used as report instances in .NET Core applications, but their code must not include any calls to CodeDOM-specific classes like ResourceManager.

Supported functionalities:

  • All rendering extensions except MHTML and XPS are supported on Windows.

  • HTML, PDF and OpenXML-based renderings are supported on Linux/macOS. Due to graphics library incompatibilities, Graph-based items in the OpenXML renderings can be incorrectly displayed.

  • All report items except the obsolete Chart item are supported.

  • The supported report definition types are TRDX, TRDP and report classes, created in Visual studio without the VS designer-specific code.

  • New JSON-based reporting configuration is introduced for both CLI and web applications. For CLI projects the JSON configuration has precedence over the current XML-based reporting configuration.

Using Telerik Reporting in Applications on Linux Platform

When deploying to a Linux machine, make sure it has installed the library libgdiplus , which is a Mono implementation of GDI+ API for non-Windows operating systems. The following snippet performs an update and installs the necessary libraries on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libc6-dev
sudo apt-get install libgdiplus

Since libgdiplus is not a perfect replacement for the Windows graphics library, the rendered reports may differ in terms of text positioning, word-wrapping and aligning. These problems mostly affect the Image rendering extension hence it is not recommended to be used. The following JSON configuration snippet will hide it from the list of the available rendering extensions:

JavaScript
"extensions": [
  { 
    "name": "IMAGE", 
    "visible": "false" 
  } 
]

The fonts used in the reports should be installed on the Linux machine, otherwise the font substitution algorithm will replace them with a system font. When rendering a PDF document, the fonts get resolved only if they are listed in the <privateFonts> configuration element.

Using Telerik Reporting in Applications on macOS Platform

  1. Install .NET Core for macOS.

  2. Install libgdiplus using Homebrew

    brew install mono-libgdiplus
  3. Create your .NET Core application (or copy an existing one from a Windows machine).

  4. Add nuget.config file with path to your NuGet repository.

  5. Add a section in appsettings.json for font fallback.

  6. Build

    dotnet build

    and run the application. When running in debug mode Visual Studio Code will ask to add debug configuration to launch.json.

Containerize Telerik Reporting

Telerik Reporting can be used in a Docker image if it meets the GDI+ requirements. The microsoft/windowsservercore images distributed by Microsoft contain the graphics library, but their size is significantly bigger compared to the size of the dotnet runtime in a Linux container. Such container only needs the libgdiplus and its accompanying libraries installed, which can be done through the following dockerfile snippet:

FROM microsoft/dotnet:2.1-runtime AS base 
RUN apt-get update \ 
    && apt-get install -y --allow-unauthenticated \ 
        libc6-dev \ 
        libgdiplus \ 
        libx11-dev \ 
    && rm -rf /var/lib/apt/lists/*

Having these three libraries installed ensures that Telerik Reporting will run on the produced Docker image.

Examples

Telerik Reporting ships with a ready-made ASP.NET Core example that demonstrates how to show the sample reports in an ASP.NET Core application. The example also shows how to inject an appsettings.json configuration file to the controller and how to initialize a WebHostBuilder so it runs under Windows and Linux.

The example can be found in the \Examples\CSharp\Asp.NetCoreDemo subfolder of the Telerik Reporting installation directory.

In this article
Not finding the help you need?