This blog post documents a breaking change in System.Drawing.Common (.NET 6/7) for our cross-platform products (v22.2 release cycle).
If you’re unfamiliar with this topic/issue, please refer to the following post published earlier this year: DevExpress Cross-Platform Products — Getting Ready for .NET 7.
Challenges, Changes and Impact on Existing Apps
In our v22.2 release cycle, we modified/refactored public and internal APIs that deal with entities from the System.Drawing namespace. The ultimate objective of this initiative is to allow you to retain all possible functionality when deploying DevExpress-powered apps to non-Windows environments (specifically, apps targeting .NET 7 and deployed to Linux and macOS). The changes affect the following products:
- DevExpress Reporting
- Office File API
- Charts and Sparkline (since they’re used in the above-mentioned products)
- DevExpress BI Dashboard (export to image/pdf)
To ensure that our cross-platform products work as expected across all supported platforms/target frameworks, we implemented our own counterparts to System.Drawing members and replaced associated properties in our source code. All DevExpress counterparts are now attributed with a "DX" prefix. As such, DXBitmap replaced Bitmap, DXGraphics replaced Graphics, DXFont replaced Font, etc. The DisplayNameAttribute has been assigned to all new public properties to help ensure that the user interface/user experience for DevExpress-powered applications remains intact.
An exception to this is our WinForms Chart library. This UI library shares the same codebase as our XRChart report control and chart rendering algorithms (for Excel/Word document generation) used in our Office File API. Since this is a WinForms component library, we chose to duplicate its public API (Font and Image to DXFont and DXImage respectively) so as not to impact WinForms users with an API change that has nothing to do with the platform. We hope that this will reduce the v22.2 migration curve for those using our WinForms Chart library.
During API testing and refactoring, we discovered that a .NET 7 breaking change affected certain enums/classes (e.g., StringAlignment, PaperKind, PrintEventArgs, ImageFormat) from System.Drawing. Said simply, Microsoft’s System.Drawing.Common assembly (for .NET 7) is now attributed for use on Windows only. Once you use any member from this assembly within an app deployed to a non-Windows environment, you’ll encounter code analysis CA1416 warnings. Unfortunately, this will break project compilation if you have enabled the TreatWarningsAsErrors switch. Our implementation had to consider such scenarios and we did our best to avoid known issues wherever possible.
For instance, we had to change the event arguments for our useful BeforePrint event from unsupported PrintEventArgs to System.ComponentModel.CancelEventArgs. We totally understand that you might have handled thousands of these events (to modify report controls' appearance or to prevent them from being printed) in your projects. To minimize the amount of manual work involved in an upgrade, we fine-tuned our DevExpress Project Converter. It should do all the replacement for you when migrating to v22.2.
The following is a complete list of known breaking changes you’ll encounter in this release:
- Reporting, Printing, and Barcode Generation API - Members changed their types and signatures
- Members that rely on System.Drawing.Common package no longer work in non-Windows environments
- Reporting, Charting, and Office File API - Custom font API changes
Please note that the XtraReport class and our internal printing classes still use some enumerations from the System.Drawing assembly (e.g., the PaperKind, StringAlignment, etc.). We plan to change this in upcoming releases. At present, we recommend that you disable the TreatWarningsAsErrors switch if you assign enumeration properties at runtime or your project includes reports stored as class instances where these properties are set. This applies to properties whose type origins from the System.Drawing assembly (e.g., the XtraReport.PaperKind property).
Our APIs are self-explanatory, but we’ve documented important classes intended for public use. Should any questions arise during your migration to .NET 7, you can locate answers in the following documentation directory: DevExpress.Drawing namespace.
While we know these changes will impact existing apps and associated implementations, we believe the long-term benefits of a platform-agnostic drawing engine will open numerous opportunities for our customers. And of course, this change also means that our products are now based on a well-respected and actively maintained assembly (SkiaSharp). As you may know, Microsoft uses this very assembly in .NET MAUI (under the Microsoft.Maui.Graphics abstraction layer) and has previously advocated for its use: Drawing with SkiaSharp.
The screenshots below were obtained from our Chart Report demo report (export to an image) and our RichEdit Overview demo (export to PDF) in an app deployed to .NET 7 & Ubuntu. While the result is not completely the same, you may notice only minor differences:
How to Use
The Skia-based drawing engine described herein is disabled and GDI+ is used by default. To enable the engine, reference the new DevExpress.Drawing.Skia assembly or NuGet package (with the same name) in your app. If the application is running within non-Windows environments (and uses the System.Drawing.Common package version 7+), internal code selects the rendering engine automatically.
Note that it is also necessary to install the required native dependencies listed in the following help topic: Office File API on Linux — Prerequisites.
You can call the DevExpress.Drawing.Internal.DXDrawingEngine.ForceSkia(); method at application startup to force enable the new Skia-based drawing engine. Note that this API is marked as internal and we may change it in the future.
CTP and Future Plans
The functionality described in this post is available as a Community Technology Preview (CTP). As its name implies, a CTP represents pre-release software and should not be used in production environments. If your organization requires the capabilities outlined in this post, please make certain to evaluate risks before usage.
You can find a list of limitations associated with our new drawing engine in the following help topics:
Should you encounter an issue not outlined above, feel free to submit a support ticket via the DevExpress Support Center. We’ll be more than happy to follow up.
To help us refine our 2023 development plans and evaluate product possibilities (including .NET MAUI and Blazor WebAssembly) please take a moment to answer the following survey questions: