Using FlexCel with .NET Core and .NET 5 or newer
.NET Core is the next iteration of the .NET framework, and the latest release dropped the "Core" part, to become ".NET5". In this document, we will refer to ".NET5" and newer versions of the framework as ".NET Core" too, since they have the same root. FlexCel comes with full support for .NET Core. Being cross-platform, you can use FlexCel for .NET Core instead of the individual versions of FlexCel for iOS, FlexCel for Windows Universal, etc.
Selecting the graphics engine
By default FlexCel for .NET Core uses the Native OS graphics framework when available, or SkiaSharp otherwise. But you can change the behavior by changing the property FlexCelConfig.GraphicFramework
When deciding to use Native or SkiaSharp frameworks, you need to consider the following points. When using SkiaSharp:
- Your app will have a dependency with the SKIA dll in SkiaSharp. This will make your application larger.
- The rendered files will be a little different from the files generated using the OS.
- For Android this is quite similar since the native graphics engine in Android is SKIA, but still, you won't be using the engine bundled with android. You will use the one in the SKIA dll from SkiaSharp.
- For iOS and macOS, it is probably better to use the iOS/macOS FlexCel dlls directly, since they use CoreGraphics which is a very capable framework and there is no need to use SKIA.
- For Windows, it is hard to say. The current implementation of FlexCel using System.Graphics (which uses GDI+) has better support for some things, like right to left languages, or EMF/WMF images. But on the other side, GDI+ is not officially supported in a server even when it works. So the choice is yours.
- For Universal Windows Apps, it is probably better to use SKIA, even if it will make your applications larger. The graphics stack in UWA lacks a lot of functionality, and the SKIA implementation is more complete.
- Your application won't be fully managed since it will call the native skia dll. This might have security implications.
- Your application will work the same everywhere since it will use the exact graphics framework everywhere. The native components might have tiny differences in how they render the text or graphics depending on the underlying graphics engine.
- Linux support can be problematic due to all the different distributions. See Installing in Linux
- The native graphics engine of the OS will likely be always up to date, while if you ship SKIA with your app, it won't get updates until you update your app. As you can see, it is not a clear winner between using SKIA or the native framework in each platform. SKIA has the advantage of producing the same results anywhere, but the native engines might be more complete and you don't have to ship the SKIA framework with your application.
You can choose what you prefer.
Migrating from .NET 4 to .NET 5 or newer
While it is just a version number of difference, .NET 4 is based in the old .NET framework, and .NET 5 is based in .NET Core. This means that to move to .NET 5 from .NET 4, you need to use the NuGet package with .NET 5. By default, FlexCel will keep using the native OS graphic engines. But if you decide to use SkiaSharp, it can have some unexpected consequences in your app. Especially if you were using WMF/EMF images, which the SKIA framework can't render. So, if you want to keep your application running as similar as possible as the way it worked in .NET 4, the most important thing is to keep FlexCelConfig.GraphicFramework using the native framework. That should make the migration to .NET 5 seamless. But there is another big change in .NET 5 which affected the FlexCel codebase, and it might make sense to review that it doesn't affect yours. This is the fact that .NET moved from using NLS in Windows to use ICU (see https://docs.microsoft.com/en-us/dotnet/standard/globalization-localization/globalization-icu ) This change can lead to subtle bugs, like this one: https://github.com/dotnet/runtime/issues/43736 In our particular case, our main issue is that now this code:
static void Main(string[] args)
{
int cmp = String.Compare("\u0007", "\u0008", StringComparison.CurrentCultureIgnoreCase);
Console.WriteLine(cmp);
}
returns 0, when in .NET 4 it would return -1. Now, all "invisible" characters are considered the same when comparing strings using linguistic order.
Installing in Linux
To run in Linux, with SKIA, you need to provide a native libSkiaSharp.so that works in your Linux distribution. For most usual cases, you just need to add a nuget dependency to https://www.nuget.org/packages/SkiaSharp.NativeAssets.Linux.NoDependencies/ to your project. See also https://github.com/mono/SkiaSharp/issues/312
If your distribution isn't supported, then you need to manually compile Skia. The instructions to do so are here: https://github.com/mono/SkiaSharp/wiki/Building-on-Linux
Installing in a Docker container
Besides the section Installing in Linux above, make sure to read Running Flex