.NET Framework support

Version 6.2.0 ยท 2025-02-06

In this article

This article describes what we do to support .NET Framework/Standard, .NET 6, and .NET 8.
It is not necessary to read this if you just want to use PDFsharp.

Platform support

Starting with PDFsharp 6.1 we retrofit the support for .NET Framework. When we started development of PDFsharp 6, we intentionally abandoned .NET Framework, because we wanted to use new C# and framework features to make the PDFsharp Project available on every .NET platform. We also wanted to enhance the source code. So e.g. we introduced the use of nullable reference types. During development we noticed that substantially new framework features like Memory or Span cannot be used without massive code refactoring. After finishing PDFsharp 6, we found that mostly all code can work not only with .NET 6 but also with .NET Standard 2.0. Most language features we use, like raw string literals or nullable reference types, are just compiler features and will work fine with .NET Framework. So, we considered that the support for .NET Framework is a huge benefit for legacy .NET projects. In PDFsharp 6.1 we use conditional compilation for all new syntax features that need runtime support like range operator and provide new NuGet packages for .NET Standard 2.0 and .NET Framework 4.6.2.
With PDFsharp 6.2.0, we added .NET 8 to the list. Support for .NET 6 will be eventually removed after support for .NET 6 has ended.

How it works

So, we reviewed and edited the source again and multi-targeted PDFsharp to .NET 6, .NET Framework 4.6.2, or .NET Standard 2.0 respectively. This has the great benefit that older .NET Framework projects still can use the latest PDFsharp 6 improvements.

With all this e.g. PDFsharp Library has two dimensions of builds. One is the target .NET or .NET Framework/Standard, the other is Core, GDI+, or WPF build. The first shares the same functionality on different target frameworks, the second has additional functionality for GDI+ and WPF builds. E.g. PDFsharp-wpf is based on <TargetFrameworks>net6.0-windows;net8.0-windows;net462</TargetFrameworks>. In contrast to PDFsharp all versions of the library can only be used under Windows because also .NET builds are based on Windows Presentation Foundation here.

Technical notes

To achieve .NET backward compatibility to .NET Framework we did the following.

PDFsharp uses only new C# features that are high level language features which are provided by the compiler and need no runtime support. For example, primary constructors, raw string literals, improved pattern matching, init only-setters, etc. Features like records cannot be used, because they need runtime support that is not available with .NET Framework 4.6.2.

Some nullability attributes like [MaybeNull] that do not exist in .NET Framework are simply added by introducing dummy attribute classes. This leads to some nullability warnings with the .NET Standard 2.0 build and therefore we set the warning level to 0 for these build. This is safe because the checks are done in the .NET 6 builds.

The index (^) and the range (..) operators which make code much more readable need the Index and Range classes. We added the original source code of this classes for the .NET Framework/Standard build.

Also, some non-existing run-time helpers like GetSubArray are simply provided in the source code.

All framework support classes we added to PDFsharp are internal. So users of PDFsharp NuGet packages do not silently get e.g. the range operator in their projects.

Minor issue

2024-06-20

We recently found a minor issue. Because of the target framework name net6.0-windows we wrongly added net472-windows instead of net472 to the <TargetFrameworks> entries in the project files. It works without any problem and therefore reached the 6.1 release build. This has no impact on the released NuGet packages because the correct framework name comes from the nuspec files. You can use the NuGet packages safely. We will fix this in upcoming 6.2.0 preview 1.