New to Telerik Reporting? Download free 30-day trial

.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 for .NET Core projects. The NuGets are available in the Telerik NuGet feed. Additionally, thе assemblies are available in the Telerik Reporting installation directory \Bin\netstandard2.0\ and \Bin\netcoreapp3.1\ folders. The assemblies target .NET Standard 2.0 and the desktop viewers target .NET Core 3.1, which ensures compatibility with a greater variety of frameworks and applications. The NuGet packages resolve the external dependencies to provide better dependency management and code portability.


  • ASP.NET Core 2.1 or newer for web projects

  • .NET Core 3.1 or newer for desktop projects

The following NuGet packages are required. When using our NuGet packages, the required dependencies are resolved automatically. 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.7.302-beta

Implemented Features and Limitations

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 should be installed (see below). Most of the processing and rendering features that work on Windows using .NET Framework 4 or higher, are also supported 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. Our recommendation is to convert such reports to .trdx/.trdp definitions with the Standalone Report Designer 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 (HTML archive), XPS (XML Paper Specification) and XLS (Microsoft Excel 97 - 2003).

  • HTML, PDF and OpenXML-based renderings are supported on Linux/macOS. Due to graphics library incompatibilities, in some cases, Graph-based items in the OpenXML renderings are 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.

  • The supported Data Source components are:

  • JSON-based reporting configuration. 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:

"telerikReporting": {
  "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.

If you need to use Telerik Reporting in a Windows container, you need to target a Windows base image that includes GDI support. This is also the approach recommended by the Microsoft, see Container Base Images - Choosing a base image help article for additional reference.


Telerik Reporting ships with a ready-made .NET Core examples that demonstrate how to show the sample reports in an ASP.NET Core, WinForms Core and WPF Core application. The ASP.NET Core demo 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.

An example project is available in the Telerik Reporting installation directory \Examples\CSharp\Asp.NetCoreDemo subfolder.

See Also

In this article