Click or drag to resize
Pdf Library for .NET

Deployment

SelectPdf runs on Windows (x64, x86), Linux (x64, arm64) and macOS (Apple Silicon). A deployment consists of the managed library plus the native engines for the target platform:

  • SelectPdf.Universal.dll - the managed library (from the SelectPdf.Universal package).

  • The Chromium (CEF) engine folder (Chromium-CEF-154.0.28) used by the HTML-to-PDF / HTML-to-image converters.

  • The native PDF tool (SelectPdf.Tools.dep on Windows, SelectPdf.Tools on Linux and macOS) used by the PDF-to-text and PDF-to-image converters.

These native engines are supplied by the matching SelectPdf.Universal.Native.<rid> package (win-x64, win-x86, linux-x64, linux-arm64 or osx-arm64). When the project references that package, MSBuild places the engine files in the application output directory automatically at build time, so a standard publish operation picks them up. See Chromium Engine and Installation for details.

The Chromium engine renders headless / off-screen - no display server (X server / Xvfb) is required on Linux. The native PDF tool is statically linked. The Linux native package also bundles the Chromium shared-library closure the engine needs, so even a minimal Linux server or container image requires no additional system packages - see Deployment with Docker.

On macOS the engines link only macOS system frameworks, so there is no dependency closure to install and nothing to add beyond your application and the .NET runtime. The engine folder has the same shape as on the other platforms - one executable plus its files in a single directory, with no application bundle involved. macOS support requires macOS 13 (Ventura) or newer on Apple Silicon; see the note on Intel Macs in Installation.

Important note  Important

On Linux and macOS, the engine binaries must be executable. When a deployment is unzipped from a Windows-produced archive (which loses the executable bit), SelectPdf restores it automatically before launching the engine.

Deployment to a Shared Hosting Environment

SelectPdf starts processes of its own: the Chromium engine runs its renderer and helper processes (and, with OutOfProcess, an engine process per conversion), and the PDF to text and PDF to image converters run a native PDF tool. If you deploy to a shared hosting environment, confirm with your hosting company that starting processes and file access to the application output directory are permitted. If they are not, consider a dedicated or virtual server.

Cloud deployments

SelectPdf runs on Microsoft Azure (App Service, Functions, Container Apps), Amazon Web Services (Lambda, Elastic Beanstalk) and Google Cloud (Cloud Run), on Windows and on Linux. See Cloud Deployments for the supported platforms and a step-by-step page for each of them.

Fonts on Linux

A Linux server or container image often has no fonts, and the fonts built into the library cover Latin, Greek and Cyrillic text only. Reference the SelectPdf.Universal.Fonts package to render every language, and put your own fonts in a fonts folder of the application. See Fonts and Languages.

Deployment with Docker

SelectPdf runs in Docker containers - Linux and Windows - with no extra installation steps in the image: no system packages, no display server, and no special docker run flags. See Deployment with Docker for base-image guidance, example Dockerfiles and the ready-to-run Docker samples.

Native Debug Symbols

SelectPdf uses SkiaSharp for images and fonts. SkiaSharp 3.119.2 and later include the debug symbols of their native Windows libraries as runtime files - libSkiaSharp.pdb, about 85 MB for each Windows architecture, and libHarfBuzzSharp.pdb - so NuGet copies them into the runtimes folder of the application, about 300 MB in total. This applies to Linux deployments too when the application is published without a runtime identifier, because such a publish carries the files of every platform. The application never uses them (see SkiaSharp issue 3519).

The SelectPdf.Universal package leaves these two files out of the build and publish output of the application, and out of its .deps.json file. To keep them, for example to analyse a crash dump of the native SkiaSharp library, set the SelectPdfKeepNativeSymbols property in the application project:

XML
Copy
<PropertyGroup>
  <SelectPdfKeepNativeSymbols>true</SelectPdfKeepNativeSymbols>
</PropertyGroup>
Note  Note

Deleting the files after a build or publish is not a safe alternative: they stay listed in the application's .deps.json, and an ASP.NET Core application hosted in IIS has been reported to fail to start because of the missing files.

See Also