dpiAware Element Overview
Telerik Reporting uses the machine DPI settings to determine the physical sizes of report items, images, calculate text sizes and draw the graphic primitives. That's why it is vital to obtain the correct DPI settings of the machine which renders and shows the report in any of the viewers. If the machine's DPI settings are set higher than the default value of 96, it is recommended to make the application DPI-aware, either through an application manifest or by setting the <dpiAware> configuration element, as shown below.
General Information
Usually, the DPI awareness is set on the application level through a manifest file, but in some cases such manifest cannot be applied. That is why the reporting engine provides the option to explicitly set the DPI awareness flag prior to rendering the report.
The <dpiAware> section has only one attribute: dpiAwareness. Its value corresponds with the Windows API PROCESS_DPI_AWARENESS enumeration and can be one of the following:
PROCESS_DPI_UNAWARE = 0PROCESS_SYSTEM_DPI_AWARE = 1PROCESS_PER_MONITOR_DPI_AWARE = 2
The default value of the dpiAwareness attribute is PROCESS_DPI_UNAWARE_NOT_SET. The current process's DPI awareness is set using the native Windows API function SetProcessDpiAwareness. It is important to note that once the process' DPI awareness is set, every next function call will fail with E_ACCESSDENIED result.
This API function is available on
Windows Vista and lateroperating systems. If Telerik Reporting is used on a machine with older OS, the DPI awareness would not be set and report rendering might produce unexpected results.
Example
The following snippet demonstrates how to set the current application's DPI awareness to PROCESS_SYSTEM_DPI_AWARE.
XML-based configuration file:
<Telerik.Reporting>
...
<dpiAware dpiAwareness="PROCESS_SYSTEM_DPI_AWARE"></dpiAware>
</Telerik.Reporting>
JSON-based configuration file:
"telerikReporting": {
"dpiAware": {
"dpiAwareness": "PROCESS_SYSTEM_DPI_AWARE"
}
}
DPI Awareness in Report Viewers
The following list explains how the DPI awareness is respected in applications that use Telerik Reporting:
Windows Forms Report Viewer
The Windows Forms applications are not DPI-aware by default. The recommended approach for declaring an application as DPI-aware is adding a dpiAware element to its application manifest, as shown in the article Windows Forms Application Overview.
WPF Report Viewer
The WPF Report Viewer must be used in a WPF application and they are system DPI-aware by default, thus no additional settings need to be applied. In case you want to change the awareness to per monitor, please check the article Developing a Per-Monitor DPI-Aware WPF Application.
HTML5-based Report Viewers
The HTML5-based report viewers use the Telerik Reporting REST Service, which is an application executed in a web server (usually IIS) domain. Instead of applying a custom manifest, the recommended approach is to add the <dpiAware> section to the application's web.config/appSettings.json and set the dpiAwareness attribute to PROCESS_SYSTEM_DPI_AWARE.