Getting Started / Download & Installation

New to Telerik Reporting? Download free 30-day trial

Available .NET Support for Operating Systems and Docker Containers

Starting with version R1 2019 (13.0.19.116) Telerik Reporting provides a set of assemblies and NuGet packages that are designed for .NET projects and enable you to use Telerik reports in .NET applications on Windows, Linux, and macOS platforms.

The NuGet packages are available in the Telerik NuGet feed. Additionally, the assemblies are available in the \Bin\netstandard2.0\, \Bin\net6.0\, and \Bin\net6.0-windows\, \Bin\net7.0\, and \Bin\net7.0-windows\ folders located in the Telerik Reporting installation directory.

The assemblies target .NET Standard 2.0 and the desktop viewers target .NET 6.0, or .NET 7.0, which ensures compatibility with a greater variety of frameworks and applications. Also, the NuGet packages resolve the external dependencies to provide better dependency management and code portability.

Requirements

  • (For web projects) ASP.NET Core 2.1 or later.
  • (For desktop projects) .NET 6.0 or later.

To use NuGet, you are required to provide the following NuGet packages. Note that when using the Telerik NuGet packages, the required dependencies are resolved automatically. Otherwise, you need to manually add them 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.8.116

Features and Limitations

On Windows, the reporting engine still relies on the GDI+ library because it provides the fastest and most convenient way to process text, which is essential to the product.

  • For Windows, .NET runtime natively resolves the GDI+ calls.
  • For Linux and macOS, you need to install the set of libraries listed below.

Most of the processing and rendering features that work on Windows and are using .NET Framework 4 or later are also supported in .NET projects with the new .NET Standard assemblies.

As a downside, the report item designers are not .NET Standard-compatible. As a result, no design-time support in Visual Studio is available and type reports are not supported. Therefore, you are recommended to convert such reports to .trdx or .trdp definitions with the Standalone Report Designer.

Also, you can use these classes as runtime-created report instances. You can use report definitions that are created in Visual Studio as report instances in .NET applications, but their code must not include any calls to CodeDOM-specific classes like ResourceManager.

Telerik Reporting supports the following 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 and macOS. Due to graphics library incompatibilities, in some cases, Graph-based items in the OpenXML renderings are incorrectly displayed.
  • Except for the obsolete Chart report item, all report items are supported.
  • The supported report definition types are TRDX, TRDP, and report classes that are created in Visual Studio without the VS designer-specific code.

  • Telerik Reporting supports the following Data Source components:

  • The JSON-based reporting configuration is also supported. For CLI projects, the JSON configuration has precedence over the current XML-based reporting configuration.

Deploying on Linux

Using SkiaSharp

Starting with R3 2023 (17.2.23.1010) we introduced SkiaSharp-based graphics engine, which is cross-platform. The active graphics engine is determined by the value of the engineName element of the processing Element which corresponds with the members of the Telerik.Drawing.Contract.GraphicsEngine enumeration.

When using SkiaSharp make sure to reference the Telerik.Drawing.SkiaSharp NuGet package or assembly.

The next libraries should also be referenced when using SkiaSharp. The snippet is relevant for Ubuntu or Debian and may differ for other Linux distributions:

sudo apt-get update
sudo apt-get install -y libfreetype6
sudo apt-get install -y libfontconfig1

Using System.Drawing(libgdiplus)

System.Drawing for .NET 7 is not supported on non-Windows platforms (Linux and MacOS) due to a breaking change introduced by Microsoft as explained in System.Drawing.Common is not supported on non-Windows platforms

When deploying to a Linux machine, make sure you have the libgdiplus library installed. The library is a Mono implementation of GDI+ API for non-Windows operating systems.

The following snippet demonstrates how to update and install the necessary libraries on Ubuntu or Debian:

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

The library libgdiplus returns as a Family Font Name the Preferred Family rather than the Family name from the font meta information. Details may be found in Font.Name returns incorrect results on Linux. The two names may be different in the general case. In such a scenario, the font should be referenced with its Family name for Windows and Preferred Family name for Linux.

In the rare case when the Preferred Family name of two fonts coincide and the Family names are different, on Linux only the second font registered as private would be respected as it will override the first one.

Common Configurations

Since the libgdiplus and SkiaSharp libraries are not perfect replacements 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 and, therefore, it is not recommended to use it.

The following JSON configuration snippet hides the Image rendering extension from the list of available rendering extensions:

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

On the Linux machine, you also need to install the fonts you use in the reports. 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.

Deploying on macOS

Currently, .NET 7 is not supported on non-Windows platforms (Linux and MacOS) due to a breaking change introduced by Microsoft as explained in System.Drawing.Common is not supported on non-Windows platforms

To use .NET on macOS:

  1. Install .NET for macOS.

  2. Install libgdiplus by using Homebrew.

    brew install mono-libgdiplus

  3. Create your .NET application or copy an existing one from a Windows machine.

  4. Add the nuget.config file with a path to your NuGet repository.
  5. Add a section in the appsettings.json file for any font fallback.

  6. Run the following command to build the project and run the application. If you run the project in the debug mode, Visual Studio Code will ask you to add the debug configuration to the launch.json file.

    dotnet build

Using Container Platforms

You can use Telerik Reporting in a Docker image if it meets the graphics engine requirements.

To use Telerik Reporting in a Windows container, target a Windows base image that includes GDI support. The same approach is recommended by Microsoft.

The Microsoft-distributed microsoft/windowsservercore images contain the GDI+ graphics library. However, their size is significantly bigger compared to the size of the .NET runtime in a Linux container. Such a container requires you to install only the libgdiplus library and its accompanying libraries.

Linux Docker Container with SkiaSharp

Starting with R3 2023 (17.2.23.1010) we introduced SkiaSharp-based graphics engine, which is cross-platform. The active graphics engine is determined by the value of the engineName element of the processing Element which corresponds with the members of the Telerik.Drawing.Contract.GraphicsEngine enumeration.

When using SkiaSharp make sure to reference the Telerik.Drawing.SkiaSharp NuGet package or assembly.

The next libraries should also be referenced when using SkiaSharp. The snippet is relevant for Ubuntu or Debian and may differ for other Linux distributions:

FROM microsoft/dotnet:7.0-runtime AS base
RUN apt-get update
RUN apt-get install -y libfreetype6
RUN apt-get install -y libfontconfig1

Linux Docker Container with System.Drawing(libgdiplus)

The following dockerfile snippet demonstrates how to achieve the desired outcome. When these three libraries are installed, Telerik Reporting will run on the produced Docker image.

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

Sample Projects

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

Sample projects are available in the subfolders with the corresponding framework names in the \Examples\CSharp subfolder of the Telerik Reporting installation directory. For example, our .NET 6 ASP.NET Core demo may be found by default in C:\Program Files (x86)\Progress\Telerik Reporting R3 2023\Examples\CSharp\.NET 6\Html5IntegrationDemo.

See Also

In this article
Related articles
Not finding the help you need? Improve this article