 | |
Installation | |
SelectPdf is installed exclusively through NuGet. There are no assemblies to download and no engine companion packages to pick from - the HTML rendering engine and the native PDF tool ship as per-platform NuGet packages that sit next to the managed library.
Installation using NuGet Packages
A typical installation is two steps:
Install the managed library package (SelectPdf.Universal).
Install the native engine package that matches your deployment platform (runtime identifier), for example SelectPdf.Universal.Native.win-x64.
1. Managed library package
- SelectPdf.Universal
The full SelectPdf library. A single AnyCPU package that targets .NET Standard 2.0, .NET 8.0 and .NET 10.0 - usable from .NET Framework 4.6.1+, .NET Core 2.0+ / .NET Standard 2.0, and .NET 5 through .NET 10. The assembly is SelectPdf.Universal.dll and its public types live in the SelectPdf.Universal namespace (with SelectPdf.Universal.Drawing for the drawing primitives).
2. Native engine packages (install the one that matches your deployment runtime identifier)
The Chromium (CEF) HTML rendering engine and the native PDF tool used by the PDF-to-text and PDF-to-image converters are platform specific. Install exactly the Native package(s) matching the runtime identifier(s) you deploy to. The managed library is AnyCPU. Choose the Native package that matches the architecture of the process that converts - win-x64, linux-x64, linux-arm64 or osx-arm64 for a 64-bit process, win-x86 for a 32-bit Windows process: the Chromium engine then runs inside the application. With a package of another architecture conversions run in a separate engine process; see Chromium Engine.
- SelectPdf.Universal.Native.win-x64
Native engines for 64-bit Windows.
https://www.nuget.org/packages/SelectPdf.Universal.Native.win-x64/
- SelectPdf.Universal.Native.win-x86
Native engines for 32-bit Windows.
https://www.nuget.org/packages/SelectPdf.Universal.Native.win-x86/
- SelectPdf.Universal.Native.linux-x64
Native engines for 64-bit Linux (x64).
https://www.nuget.org/packages/SelectPdf.Universal.Native.linux-x64/
- SelectPdf.Universal.Native.linux-arm64
Native engines for 64-bit Linux (ARM64 / aarch64).
https://www.nuget.org/packages/SelectPdf.Universal.Native.linux-arm64/
- SelectPdf.Universal.Native.osx-arm64
Native engines for macOS on Apple Silicon (ARM64). Requires macOS 13 (Ventura) or newer.
https://www.nuget.org/packages/SelectPdf.Universal.Native.osx-arm64/
3. Fonts package (optional, for Linux)
Linux servers and container images often have no fonts. SelectPdf.Universal.Fonts adds Noto fonts for every script, so pages in any language render there; it copies nothing for Windows builds. See Fonts and Languages.
https://www.nuget.org/packages/SelectPdf.Universal.Fonts/
All PDF features - HTML-to-PDF conversion, from-scratch document creation, graphic elements, fonts, encryption, bookmarks, viewer preferences, PDF/A, form filling, PDF compression, digital signatures, portfolios, page resize, PDF-to-text and PDF-to-image - are in-box in the SelectPdf.Universal package. The only other package is the optional SelectPdf.Universal.Fonts, fonts for every language on Linux - see Fonts and Languages.
There is only one HTML rendering engine (Chromium / CEF), bundled in the Native package. There are no engine companion packages to choose. See Chromium Engine.
To deploy to more than one platform side by side (for example a build published for Windows, Linux and macOS), install every matching Native package; each targets its own runtime identifier and they can coexist.
On macOS only Apple Silicon (ARM64) is supported by the Native package. On an Intel Mac the managed features still work, but HTML-to-PDF, PDF-to-text and PDF-to-image are unavailable because no osx-x64 engine package is produced.
The Previous SelectPdf Library (Select.Pdf)
Before SelectPdf.Universal, the SelectPdf library shipped as Select.Pdf: a Windows-only library for .NET Framework and .NET, distributed as NuGet packages and as downloadable archives. SelectPdf.Universal is a separate product line with its own package ids, assembly names and namespace. NuGet does not treat it as an update of Select.Pdf, so an existing project keeps the previous library until its references are replaced. To move a project, remove the pieces listed below, install the packages described above, and follow Migrating to SelectPdf.Universal for the code changes.
Previous NuGet packages and their replacements
Previous package | What it contained | Replace with |
|---|---|---|
Select.Pdf, Select.Pdf.x64 | The library for .NET Framework 2.0 and 4.0 (Select.Pdf.dll) with its WebKit HTML engine (Select.Html.dep) and its PDF tool (Select.Tools.dep), in a 32-bit and a 64-bit build. | SelectPdf.Universal plus one SelectPdf.Universal.Native.<rid> package. .NET Framework is supported from version 4.6.1, through the .NET Standard 2.0 build; .NET Framework 2.0 to 4.5 are not. |
Select.Pdf.NetCore, Select.Pdf.NetCore.x64 | The same library for .NET Framework 4.6.1 and later, .NET Core and .NET (.NET Standard 2.0), on Windows only. | SelectPdf.Universal plus one SelectPdf.Universal.Native.<rid> package. |
Select.Pdf.Chromium.Windows, Select.Pdf.Chromium.Windows.x64, Select.Pdf.NetCore.Chromium.Windows, Select.Pdf.NetCore.Chromium.Windows.x64 | The engine folder (Chromium-CEF-<version>) of the Chromium rendering engine. | Nothing separate: the Chromium engine is in the SelectPdf.Universal.Native.<rid> package. |
Select.Pdf.NetCore.Blink, Select.Pdf.NetCore.Blink.x64 | A Chrome build (Chromium-<version> folder) for the Blink rendering engine. | Nothing: SelectPdf.Universal has one rendering engine, Chromium. The Blink, WebKit and WebKit Restricted engines are not available. |
Select.Pdf.Extras, Select.Pdf.Extras.x64 | An add-on with an alternative forms manager and compressor (Select.Pdf.Extras.dll). | No add-on: form filling (PdfFormManager) and compression are part of SelectPdf.Universal. Code written against the add-on's own classes has to be rewritten. |
Previous download archives
The library was also offered as zip archives from the SelectPdf website: SelectPdf-Assemblies-v<version>.zip (the assemblies for each .NET Framework version, the documentation and the samples), SelectPdf-Samples-v<version>.zip, SelectPdf-Chromium-Windows[-x64]-v<version>.zip (the Chromium engine folder) and SelectPdf-BlinkBinaries[-x64]-v<version>.zip (the Blink engine folder). A project set up from an archive references the DLL directly and carries its engine files by hand. SelectPdf.Universal has no archive distribution: it is installed through NuGet only.
What to remove from a project that used the previous library
The package references listed in the table above, and Newtonsoft.Json if it was added only for SelectPdf.
Direct references to Select.Pdf.dll, Select.HtmlToPdf.dll or Select.Pdf.Extras.dll, usually with a hint path into the Assemblies folder of an archive.
The engine files deployed next to the application, whether they were added to the project as content or copied by hand: Select.Html.dep, Select.Tools.dep, the Chromium engine folder (Chromium-CEF-<version>) and the Blink engine folder (Chromium-<version>). Clean the output folders as well, where copies can remain after the references are gone.
Build steps that copied the engine files: projects that use packages.config often carry an AfterBuild target (named CopyChromiumFiles in the SelectPdf samples) that copies the Chromium folder into the output. The new native packages deploy their files themselves.
On machines where Select.Pdf or Select.HtmlToPdf was installed in the Global Assembly Cache, remove it from the GAC once no application uses it.
The new assemblies are named SelectPdf.Universal.dll and SelectPdf.HtmlToPdf.Universal.dll, and the engine files are the Chromium-CEF-154.0.28 folder and SelectPdf.Tools.dep (SelectPdf.Tools on Linux and macOS). SelectPdf.Universal loads nothing from the previous library, so leftover files do not affect it, but they add to the size of every deployment.
License keys
SelectPdf.Universal reads its license key from LicenseKey, in the same format as the previous library. A key issued for version 26 or later is accepted; a key for an earlier major version is refused as not valid for this version, as the previous library refuses it too. See Licensing.
See Also