ActiveReports.NET 17 Section Report Breaking Changes

During work on AR11/12 we found that Microsoft would be releasing a new framework (.NET Core) without support for System.Drawing GDI+ functions (reintroduced later and finally limited to Windows only since .NET 7). There are workarounds to recompile Mono libraries (with libgdiplus native dependency) and similar, but these workarounds are limited or not fully functional. Supporting the new framework brings a lot of advantages (new web platforms from MS, cheap Linux Azure, etc.), and we already have our own managed libraries, such as GrapeCity Documents for PDF and GrapeCity Documents for Imaging.

So we decided to switch ActiveReports to use our own fully managed rendering. Fully managed rendering (in comparison to libgdiplus, Pango, or Skia) has a lot of advantages. All functions are under our control, WYSIWYG between PDF/image, missed external dependencies, simplified deployment, etc., and small performance degradation (about 10-20% in full report rendering).

ActiveReports provides a set of components for different report types: “Page/RDL” (our extensions of MS RDL) and “Section” (the only report type before AR7). “Page/RDL” reports were designed to avoid types from System.Drawing in the public API, so moving to new rendering was relatively simple (some preparation work in AR13 and almost done in AR14). “Section” reports have a different architecture, so moving to new rendering was done in a few steps in AR15/AR16/AR17. The main breaking changes were in AR15 (introduction of compatibility mode, extraction of WinForms dependencies) and AR17 (extraction of GDI/GDI+ dependencies, cleaning of public API).

We always try to avoid breaking changes when possible, but in cases like this where they are necessary, it is important to clearly document them so our customers can easily solve any potential issues when migrating. To understand the changes let's discuss how Section reports work at a high level:

• SectionReport (code-based or *.rpx file) is just a template for future processing.

• SectionReport template filled with data creates SectionDocument (or the user can create the document manually through API). SectionDocument is our internal binary paginated vector image (internally it is a set of commands to render lines, images, text, etc).

• SectionDocument image can be “rendered” in viewers or exports. Some exports required more work to export the image (for example – building an Excel grid first).

What was changed in AR15/AR16/AR17:

• Public API of SectionReport (main changes):

  • Introduced CompatibilityMode property.

  • Replaced System.Drawing.Image with our classes.

  • Replaced System.Drawing.Font with our classes.

  • Replaced System.Drawing.Printing.PrintDocument with our classes.

• Public API of SectionDocument (main changes):

  • Introduced CompatibilityMode property.

  • Extracted GDI/GDI+ dependencies to separate assemblies.

  • New managed rendering (in addition to GDI/GDI+ based).

• Exports/viewers changes (main changes):

  • Introduced new WYSIWYG WinForms/WPF previews and PDF/TIFF exports for cross-platform rendering.

  • Changed all ASP.NET previews to render the SectionDocument image as SVG by default (becomes almost WYSIWYG with WinForms/WPF preview for cross-platform rendering). So preview in legacy GDI/GDI+ rendering can look wrong (Must manually change to “HTML” rendering format, but this format has a lot of limitations).

• Other changes:

  • Some changes in public Excel API.

  • Some changes in charts API for code-based “Section“ reports.

This can primarily affect:

• Code-based “Section” reports. The main changes should be around charts and custom controls. We suggest trying the AR migration tool first.

• Scripts. Some scripts can stop working because of differences in the API:

  • No WinForms dependencies for custom control. Required to specify dependencies manually.

  • Slightly different API to work with fonts. May require some changes.

  • Slightly different API to work with images. May require some changes.

• Printer. Some code to specify printer-related settings may require updating.

• SpreadBuilder Excel API. The new API required some external work to measure strings (required for the auto-height function) and specify fonts and images.

• Way to specify settings, especially PDF settings.

• Way to render line breaks. Cross-platform compatibility mode uses Unicode line-breaking algorithm by default. Switching to the old algorithm can be done through config files.

• Limited support for EMF/WMF image formats in cross-platform rendering

If you cannot perform some operations: please contact our support, maybe it is planned already (like SVG support for cross-platform rendering instead of EMF/WMF in the next major version). The best way to reach our support for issues like this is through our web ticket system where our Technical Engagement Engineers can help you out and can easily forward potential issues to our development team.

For more detailed information on individual breaking changes in AR 17 and in previous versions, please check out the ActiveReports .NET Breaking Changes documentation page.

Ready to See it in Action? Download ActiveReports.NET Today!