Html to Pdf Converter for .NET - HTML Rendering Engines

The following sample shows how to use the Select.Pdf Html To Pdf converter to convert a URL to PDF while selecting the rendering engine.

                  // instantiate a html to pdf converter object
HtmlToPdf converter = new HtmlToPdf();

// set converter rendering engine
converter.Options.RenderingEngine = RenderingEngine.WebKit;
// or: RenderingEngine.WebKitRestricted
// or: RenderingEngine.Blink
// or: RenderingEngine.Chromium

// create a new pdf document converting an url
PdfDocument doc = converter.ConvertUrl(url);

// save pdf document
doc.Save(Response, false, "Sample.pdf");

// close pdf document
doc.Close();

                  ' instantiate a html to pdf converter object
Dim converter As New HtmlToPdf()

' set converter rendering engine
converter.Options.RenderingEngine = RenderingEngine.WebKit
' or: RenderingEngine.WebKitRestricted
' or: RenderingEngine.Blink
' or: RenderingEngine.Chromium

' create a new pdf document converting an url
Dim doc As PdfDocument = converter.ConvertUrl(url)

' save pdf document
doc.Save(Response, False, "Sample.pdf")

' close pdf document
doc.Close()

Use the following guidance when picking an engine:

• Start with WebKit (the default). It is available on every supported target and handles most traditional web content.

• For Microsoft Azure Web Apps (or a similar restricted environment), use either WebKit Restricted or Chromium. Both run on Azure Web Apps (Basic plan or above) without additional configuration; pick Chromium when modern HTML5/CSS3 or modern JavaScript rendering is needed, WebKit Restricted otherwise.

• Switch to Blink or Chromium when the input HTML needs modern CSS3, HTML5 or modern JavaScript that the WebKit engines do not render correctly.

• Prefer Chromium over Blink when the application targets legacy .NET Framework (2.0 - 4.5) and still needs a modern engine, when the application runs on Azure Web Apps, or when the application needs to keep up with a current Chromium version. The Chromium engine ships in a separate Chromium.Windows NuGet package - see Installation for details.

• If the application may have to run on Linux, macOS or in Docker containers later, pick Chromium now - it is the same engine that powers SelectPdf.HtmlToPdf.Universal, so the pages keep rendering with the same engine after the move; the code changes it takes are listed in the migration notes. See Cross-Platform Library and Deployment to Docker.

All four engines are exposed through the same HtmlToPdf API. Switching engines is a one-line change on RenderingEngine.

This is the default rendering engine, available since the first version of SelectPdf. Unless otherwise specified, all features described in this documentation that relate to HTML to PDF conversion refer to this engine. WebKit is available for every .NET Framework and .NET Core version supported by SelectPdf.

Note: the WebKit rendering engine can only render ES5 JavaScript.

Introduced in v18.3 of SelectPdf. Also based on WebKit, with fewer features so it can run in restricted environments such as Microsoft Azure Web Apps. WebKit Restricted is available for every .NET Framework and .NET Core version supported by SelectPdf.

Note: the WebKit Restricted rendering engine can only render ES5 JavaScript.

Introduced in v19.1 of SelectPdf. Only available for SelectPdf builds that target .NET Core 2.0 or above and .NET Framework 4.6.1 or above. Blink is the rendering engine used by the Chrome browser and the Chromium project.

Blink can render the latest HTML/CSS and ES6 JavaScript. All HTML-to-PDF features available with the default WebKit engine - including automatic bookmark generation and POST data - are also supported when rendering with Blink.

High-concurrency use (since v26.3): the Blink engine supports running many conversions in parallel, within one process and across processes. Browser start-up is retried automatically with growing timeouts (see BlinkEngineLaunchTimeout and BlinkEngineLaunchMaxTries), the thread pool is tuned automatically while Blink conversions run (bounded by BlinkMaxThreadPoolWorkers), and the number of browser instances starting at the same moment is limited machine-wide so heavily loaded servers stay responsive. The machine-wide start-up limit defaults to half the processor count and can be changed with the SELECTPDF_BLINK_MAX_CONCURRENT_LAUNCHES environment variable (0 disables it).

Introduced in v26.2 of SelectPdf. The Chromium rendering engine is based on the Chromium Embedded Framework (CEF) and is distributed as a separate Chromium.Windows NuGet package that complements the main Select.HtmlToPdf package. It renders modern HTML5/CSS3 and modern JavaScript (ES2020+), and tracks a current Chromium release. The Chromium engine is also the engine that powers SelectPdf.HtmlToPdf.Universal, the free cross-platform Community Edition (see Cross-Platform Library) - so an application that standardizes on the Chromium engine today gets consistent rendering output if it later moves to Linux or Docker.

Unlike the Blink engine, the Chromium engine is available for every .NET target supported by SelectPdf, including .NET Framework 2.0 and 4.0. The Chromium engine also runs on Microsoft Azure Web Apps (Basic plan or above) without additional configuration.

Authenticated web pages can be converted with the Chromium engine by populating LoginOptions on HtmlToPdfOptions.

All SelectPdf HTML-to-PDF features - including automatic bookmark generation and POST data - are fully supported with the Chromium engine.

For installation and deployment details see Chromium Engine.

Reference

Other Resources