Migrating to SelectPdf.Universal

Remove the Select.Pdf package references (including the Chromium and Blink companion packages and Select.Pdf.Extras), any direct reference to Select.Pdf.dll, and the engine files a project carries by hand (Select.Html.dep, Select.Tools.dep, the engine folders and any build step that copies them). Then install SelectPdf.Universal and the native package for each platform the application runs on:

dotnet add package SelectPdf.Universal
# the native package: win-x64, win-x86, linux-x64, linux-arm64 or osx-arm64
dotnet add package SelectPdf.Universal.Native.win-x64

The managed package is AnyCPU; there is no separate x64 build. Pick the native package that matches the architecture of the process that converts (win-x86 for a 32-bit Windows process). The complete list of previous packages, download archives and leftover files is in the "Previous SelectPdf library" section of Installation.

.NET Framework 2.0 to 4.5 are not supported; an application on one of them has to move to .NET Framework 4.6.1 or later, or to .NET.

Every public type lives in SelectPdf.Universal, and the drawing primitives in SelectPdf.Universal.Drawing. Replace the imports, and any fully qualified name:

Because the namespaces differ, a project can reference Select.Pdf and SelectPdf.Universal side by side while it is ported one file at a time. The free Community Edition (SelectPdf.HtmlToPdf.Universal) uses the same SelectPdf.Universal namespace, so switching between the two editions needs no code change.

SelectPdf.Universal does not use System.Drawing, which is Windows-only on current .NET. Every member that took or returned one of its types now uses a type of the library:

Before, with Select.Pdf:

using System.Drawing;
using SelectPdf;

PdfDocument doc = new PdfDocument();
PdfPage page = doc.AddPage();
PdfFont font = doc.AddFont(new Font("Arial", 12));
page.Add(new PdfTextElement(0, 0, "Hello", font, Color.DarkBlue));
PdfRectangleElement box = new PdfRectangleElement(new RectangleF(0, 30, 200, 20));
box.BackColor = Color.LightGray;
page.Add(box);
page.Add(new PdfImageElement(0, 60, Image.FromFile("logo.png")));

HtmlToImage imgConverter = new HtmlToImage();
Image pageImage = imgConverter.ConvertUrl("https://selectpdf.com");
pageImage.Save("page.png");

Imports System.Drawing
Imports SelectPdf

Dim doc As New PdfDocument()
Dim page As PdfPage = doc.AddPage()
Dim font As PdfFont = doc.AddFont(New Font("Arial", 12))
page.Add(New PdfTextElement(0, 0, "Hello", font, Color.DarkBlue))
Dim box As New PdfRectangleElement(New RectangleF(0, 30, 200, 20))
box.BackColor = Color.LightGray
page.Add(box)
page.Add(New PdfImageElement(0, 60, Image.FromFile("logo.png")))

Dim imgConverter As New HtmlToImage()
Dim pageImage As Image = imgConverter.ConvertUrl("https://selectpdf.com")
pageImage.Save("page.png")

After, with SelectPdf.Universal:

using System.IO;
using SelectPdf.Universal;
using SelectPdf.Universal.Drawing;

PdfDocument doc = new PdfDocument();
PdfPage page = doc.AddPage();
// Liberation Sans ships with the library; "Arial" works where it is installed
PdfFont font = PdfFont.CreateFromSystemFont("Liberation Sans", 12);
page.Add(new PdfTextElement(0, 0, "Hello", font, new PdfColor(0, 0, 139)));
PdfRectangleElement box = new PdfRectangleElement(new RectangleF(0, 30, 200, 20));
box.BackColor = new PdfColor(211, 211, 211);
page.Add(box);
page.Add(new PdfImageElement(0, 60, "logo.png"));

HtmlToImage imgConverter = new HtmlToImage();
byte[] png = imgConverter.ConvertUrl("https://selectpdf.com");
File.WriteAllBytes("page.png", png);

Imports System.IO
Imports SelectPdf.Universal
Imports SelectPdf.Universal.Drawing

Dim doc As New PdfDocument()
Dim page As PdfPage = doc.AddPage()
' Liberation Sans ships with the library; "Arial" works where it is installed
Dim font As PdfFont = PdfFont.CreateFromSystemFont("Liberation Sans", 12)
page.Add(New PdfTextElement(0, 0, "Hello", font, New PdfColor(0, 0, 139)))
Dim box As New PdfRectangleElement(New RectangleF(0, 30, 200, 20))
box.BackColor = New PdfColor(211, 211, 211)
page.Add(box)
page.Add(New PdfImageElement(0, 60, "logo.png"))

Dim imgConverter As New HtmlToImage()
Dim png As Byte() = imgConverter.ConvertUrl("https://selectpdf.com")
File.WriteAllBytes("page.png", png)

SelectPdf.Universal renders HTML with one engine, Chromium. RenderingEngine is kept so existing code compiles, but its only value is RenderingEngine.Chromium: assignments of WebKit, WebKitRestricted or Blink have to be removed. Select.Pdf used WebKit by default, so an application that never set the engine was rendering with WebKit and will see the output change: a current browser layout, different page breaks and page counts, and full support for modern CSS and JavaScript. Review the documents the application produces, and control pagination from the page's CSS (break-before, break-after, break-inside: avoid) - see Page Breaks and Chromium Engine.

Settings that belonged to the other engines are gone:

Three settings have new names. The old names still compile, marked obsolete, and forward to the new ones, so the change can be made at any time:

CefEnginePath and CefEngineTemporaryFilesPath were renamed without an obsolete alias (see Step 4). A few method parameters were renamed as well (PdfDocument.RemovePage and the PdfPageCollection methods); this only matters to calls that use named arguments.

Fonts are where a Windows-only library and a cross-platform one differ most, because the fonts installed on a Linux server or in a container are not the fonts of a Windows desktop.

Porting font code

How installed fonts are found on each platform

• A font requested by family name (PdfSystemFont, PdfFont.CreateFromSystemFont) is looked up among the fonts installed on the machine the application runs on - the Windows font folder, the font directories of a Linux distribution, the macOS system fonts - by exact family name. A family that is not installed is an error (PdfDocumentException), never a silent substitution with another face. Arial, Times New Roman, Verdana or Segoe UI are installed on Windows, but usually not on Linux servers or in containers.

• The library carries three font families of its own, embedded in the assembly: Liberation Sans, Liberation Serif and Liberation Mono, each with bold and italic faces. They have the same character widths as Arial, Times New Roman and Courier New, so text laid out with them takes the same space. They are available on every platform, including a container with no fonts installed, and are always listed by PdfSystemFonts.InstalledFamilies. Code that must produce the same document on Windows, Linux and macOS should ask for these names instead of the Windows ones.

• The 14 standard PDF fonts (Helvetica, Times, Courier, Symbol, ZapfDingbats and their styles) and the standard CJK fonts are not embedded: the PDF reader supplies them, so they work the same on every platform.

• For an application running on Windows, nothing changes: the installed fonts are available as before.

Fonts in HTML conversion

• Chromium uses the fonts installed on the machine and the web fonts a page loads (@font-face, Google Fonts), and embeds every font the page uses, as a subset. Web fonts render the same everywhere; a page that relies on a font by name (font-family: Arial) renders with that font only where it is installed, and with another face elsewhere.

• On Linux, the library configures Chromium so that the generic families (sans-serif, serif, monospace) fall back to the bundled Liberation fonts when the system has nothing better. Text therefore renders even in a container with no fonts at all; a system that has fonts installed keeps its own. To reproduce a Windows layout exactly on Linux, install the fonts the pages use, or load them as web fonts.

• Windows containers based on Windows Server Core need the core Windows font families installed; see Deployment with Docker.

Fonts in documents with a standard

• PDF/A and PDF/X require every font to be embedded. A standard font used in such a document is drawn with the bundled face that has the same metrics, and embedded: Helvetica with Liberation Sans, Times with Liberation Serif, Courier with Liberation Mono. Symbol and ZapfDingbats have no bundled equivalent and are refused.

• The standard CJK fonts are never embedded, so they cannot be used in PDF/A or PDF/X documents: load a CJK TrueType or OpenType font with PdfFont.CreateFromFile instead.

• PdfDocument.ConvertToPdfA embeds the fonts a loaded document uses but does not carry, resolving each by name on the machine and falling back to the bundled family closest to it.

Other differences

• Text drawn with a standard CJK font appears about one line lower than in Select.Pdf, which painted CJK text one line above the requested position while reporting a rectangle below it. SelectPdf.Universal paints the text at the requested position, and the rectangle it reports matches. Latin text and TrueType fonts are placed as before.

• Size, IsUnderline and IsStrikeout can be changed on every kind of font after it is created, as in Select.Pdf.

• In the Word to PDF converter, a font a document names but the machine lacks is replaced by the closest bundled Liberation family.

Unchanged: the 28-point default page margins, JPEG compression (on, level 10), stream compression (Normal), the navigation timeout (60 seconds), WebGlEnabled (false), the default permissions, the evaluation watermark text and the 5-page limit of the Community Edition.

• The native package deploys the engine files next to the application at build and publish time; there is nothing to copy by hand and no build step to add.

• On Linux, the native package brings the libraries the Chromium engine needs, so no system packages have to be installed; glibc 2.30 or later is required (Debian 11, Ubuntu 20.04, RHEL 9 and later). See Deployment, Deployment with Docker and Microsoft Azure.

• An application published for several platforms references one native package per platform; they install side by side.

• Asynchronous conversion with cancellation: ConvertUrlAsync, ConvertHtmlStringAsync, PdfCanvas.AddAsync - Asynchronous Conversion.

• Word to PDF: WordToPdf, PdfWordElement, PdfWordSection - Getting Started.

• Redaction that removes content from the file - Pdf Redaction.

• Signature validation, AES-GCM encryption and unencrypted metadata - Digital Signatures, Advanced Security.

• PDF/A-4, PDF/A-4e, PDF/A-4f, PDF/UA-1 and PDF/UA-2 - Accessible PDF and PDF/A; ZUGFeRD / Factur-X invoices - Electronic Invoices.

• HtmlToImageElement, fonts from memory and system font discovery, PdfDocument.Append from a file or a stream, and position overloads (x, y, width, height) on link, annotation and signature elements.

1. Replace the packages, remove the old engine files and build steps (Step 1).

2. Replace SelectPdf with SelectPdf.Universal in imports and qualified names (Step 2).

3. Replace System.Drawing types (Step 3) and font code (Fonts).

4. Remove engine selection and the removed settings; rename CefEnginePath (Step 4).

5. Optionally rename MinPageLoadTime, MaxPageLoadTime and VisibleWebElementId (Step 5).

6. Replace PdfMergeManager and any use of printing or the Extras add-on (Step 6).

7. Review the behaviour table - in particular engine hosting, the HTTP cache in multi-user services, and the encryption default.

8. Compare the documents the application produces, especially if it rendered with WebKit, and test on every platform it deploys to.

Other Resources