Upgrade existing projects to PDFsharp 6
Version 6.1.0
In this article
This article describes changes that are or may be required when making the transition from PDFsharp 1.5 or PdfSharpCore 1.3 to the new PDFsharp and MigraDoc 6.2 version.
From PDFsharp/MigraDoc 1.5 to 6.x
There are few breaking changes in PDFsharp and MigraDoc. And not all breaking changes will occur when you migrate your project.
Breaking changes in PDFsharp
Choose the best flavor of PDFsharp to make the transition as easy as possible.
- From "PDFsharp Core" switch to "PDFsharp GDI" if your code runs under Windows only; feel free to try "PDFsharp Core" if you want to target other operating systems beside Windows with your new app, but note that some features will not be supported.
- When using "PDFsharp GDI", stick to "PDFsharp GDI".
- When using "PDFsharp WPF", stick to "PDFsharp WPF".
Notes for transitions to "PDFsharp Core 6.x": While the Core build of PDFsharp 1.5 still relied on GDI for some tasks like loading images, the new Core build of version 6.x no longer depends on GDI and runs on other platforms besides Windows. There are small regressions as a result:
- Supported image formats are JPG, PNG, and BMP.
- Cannot create paths from fonts.
- No fonts are loaded automatically. Set an instance of IFontResolver that can handle all the fonts your application needs.
To get started quickly, you can use GlobalFontSettings.FontResolver = new FailsafeFontResolver();. With this font resolver you will always get a Segoe font, no matter what font your application asks for. So, documents may not look proper, but code should run.
The enum XFontStyle has been renamed to XFontStyleEx. So, if you encounter this issue during compiling, a global "Search and replace" should resolve that for you.
The properties MUH and MFEH have been removed from the XGraphics class and code that assigns these properties is no longer needed and can be removed.
Some implicit conversions of the XUnit class have been marked obsolete. As they are implicit, the compiler invokes them automatically and it can be difficult to identify where they are used. To avoid the warnings, you can replace class XUnit with class XUnitPt or use the Point property to avoid the implicit conversion. Note that the warning is just a warning and can safely be ignored at the moment. With one of the future versions, this implicit conversion will be removed and you will get error messages instead of warnings. But you can still address these warnings once your app is running and all other issues are resolved.
Breaking changes in MigraDoc
The DefaultPageSetup of MigraDoc should never be modified. The new version of MigraDoc throws an exception when you attempt to modify it.
Only change the PageSetup of a section. You can assign a Clone() of the DefaultPageSetup to the PageSetup.
This can be useful if you want to initialize the values for margins etc.
But often it is enough to assign the values you want to set to the PageSetup instead of setting them for the DefaultPageSetup.
Breaking changes between .NET Framework and .NET
These changes are not related to PDFsharp and MigraDoc, but if you make two migrations at the same time, here are some useful hints.
Issues that may show up when you move from .NET Framework and PDFsharp 1.5 to .NET and PDFsharp 6.x at the same time.
Old PDFsharp samples use this simple code to open the PDF file in a PDF viewer:
Process.Start(filename);
With .NET you have to add UseShellExecute = true to get the old behavior under Windows:
Process.Start(new ProcessStartInfo(filename) { UseShellExecute = true });
From PdfSharpCore 1.3 to PDFsharp 6.x
PdfSharpCore is a port of an older PDFsharp version. PdfSharpCore project site
All name spaces have been changed from "PdfSharp" to "PdfSharpCore". So, when moving from the port to the original, you have to change all "usings" from "PdfSharpCore" to "PdfSharp". In the best case, this can be achieved with a single global "Search and replace" in your IDE.
PdfSharpCore uses SixLabors.Fonts for font handling and SixLabors.ImageSharp for image handling. As a result, there are some differences with the APIs for fonts and images.
The XImage class of PdfSharpCore has methods that do not exist with PDFsharp because PdfSharpCore uses ImageSharp for image handling.
One of those methods is XImage FromStream(Func<Stream> stream). With PDFsharp the parameter is Stream stream without Func, so instead of specifying a delegate that will return a stream, just pass the stream directly.
The method XImage FromImageSource(ImageSource.IImageSource imageSouce) [sic] has no counterpart in PDFsharp as it is specific to the image handling implemented in PdfSharpCore.