Chromium Rendering Engine (CEF)

Install the managed SelectPdf.HtmlToPdf.Universal package and the SelectPdf.Universal.Native.<rid> package matching your deployment runtime identifier. The Native package deploys the Chromium runtime (engine folder Chromium-CEF-154.0.28) into the application output folder automatically at build time.

SelectPdf.Universal.Native.win-x64

Chromium engine for 64-bit Windows.

SelectPdf.Universal.Native.win-x86

Chromium engine for 32-bit Windows.

SelectPdf.Universal.Native.linux-x64

Chromium engine for 64-bit Linux (x64).

SelectPdf.Universal.Native.linux-arm64

Chromium engine for 64-bit Linux (ARM64 / aarch64).

SelectPdf.Universal.Native.osx-arm64

Chromium engine for macOS on Apple Silicon (ARM64), macOS 13 (Ventura) or newer.

Note

Choose the native package that matches the architecture of the application's process: the engine then runs inside the application (see Engine Hosting below). With a package of another architecture, for example a 32-bit process with the win-x64 package, conversions still work, in a separate engine process. The Linux packages carry the Chromium system libraries the engine needs, so a minimal server or container image needs no additional packages; see Deployment.

Chromium is the default engine, so this step is optional. If you set it explicitly, assign RenderingEngine to RenderingEngine.Chromium (the only value):

HtmlToPdf converter = new HtmlToPdf();

// Chromium is the default; setting it explicitly is optional
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// standard conversion options can still be used
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;
converter.Options.MarginTop = 20;
converter.Options.MarginBottom = 20;

PdfDocument doc = converter.ConvertUrl("https://selectpdf.com");

try
{
    doc.Save("ChromiumSample.pdf");
}
finally
{
    doc.Close();
}

Dim converter As New HtmlToPdf()

' Chromium is the default; setting it explicitly is optional
converter.Options.RenderingEngine = RenderingEngine.Chromium

' standard conversion options can still be used
converter.Options.PdfPageSize = PdfPageSize.A4
converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait
converter.Options.MarginTop = 20
converter.Options.MarginBottom = 20

Dim doc As PdfDocument = converter.ConvertUrl("https://selectpdf.com")

Try
    doc.Save("ChromiumSample.pdf")
Finally
    doc.Close()
End Try

The path to the engine folder can be overridden with ChromiumEnginePath when the runtime is deployed to a non-default location.

The engine can convert pages behind an HTML login form by populating LoginOptions on the converter options before conversion. LoginOptions takes the login page URL, the CSS selectors of the username, password and submit button fields, the credentials to type in, and optional delays before typing and after submitting.

HtmlToPdf converter = new HtmlToPdf();

converter.Options.LoginOptions = new LoginOptions
{
    LoginPage = "https://example.com/login",
    UsernameFieldSelector = "#username",
    PasswordFieldSelector = "#password",
    SubmitButtonSelector = "#submit",
    Username = "user@example.com",
    Password = "secret",
    DelayBefore = 100,
    DelayAfter = 500
};

PdfDocument doc = converter.ConvertUrl("https://example.com/protected");

try
{
    doc.Save("ProtectedPage.pdf");
}
finally
{
    doc.Close();
}

Dim converter As New HtmlToPdf()

converter.Options.LoginOptions = New LoginOptions() With {
    .LoginPage = "https://example.com/login",
    .UsernameFieldSelector = "#username",
    .PasswordFieldSelector = "#password",
    .SubmitButtonSelector = "#submit",
    .Username = "user@example.com",
    .Password = "secret",
    .DelayBefore = 100,
    .DelayAfter = 500
}

Dim doc As PdfDocument = converter.ConvertUrl("https://example.com/protected")

Try
    doc.Save("ProtectedPage.pdf")
Finally
    doc.Close()
End Try

The engine can run in two ways, selected for the whole application by ChromiumEngineHostMode:

InProcess

The engine is loaded into the application once and kept ready between conversions. This is the default when the in-process host library (SelectPdf.Cef.Host.dll, .so or .dylib) is beside the engine, as it is in every current native package. It removes the time spent starting and closing a browser for every conversion, so short pages convert several times faster.

OutOfProcess

Every conversion starts a short-lived engine process of its own. Nothing is shared between conversions, and a crash or a hang inside the browser cannot affect the application. This is the default when the host library is not beside the engine.

Set the mode during start-up, before the first conversion: the value in force at the first conversion is used for the life of the process. The environment variable SELECTPDF_CHROMIUM_ENGINE_HOST (inprocess or outofprocess) changes the default without a code change; an explicit assignment overrides it.

// at application start-up, before the first conversion:
// run every conversion in its own engine process
GlobalProperties.ChromiumEngineHostMode = ChromiumEngineHostMode.OutOfProcess;

' at application start-up, before the first conversion:
' run every conversion in its own engine process
GlobalProperties.ChromiumEngineHostMode = ChromiumEngineHostMode.OutOfProcess

What running the engine inside the application means:

• Up to MaximumConcurrentConversions conversions (8 by default) run at the same time, each in a browser of its own with its own cookies and storage. Further conversions wait and are served in the order they arrived. The same limit applies out of process.

• The HTTP cache is kept from one conversion to the next by default, which makes pages that share resources faster to convert. Set HttpCache to Clear when conversions run on behalf of different users whose responses must stay separate (see Security Recommendations). Cookies and site storage are cleared after every conversion in every mode.

• Settings that apply to the whole browser - WebGlEnabled, the proxy, insecure content and local file access - are fixed by the first conversion.

• The engine runs inside the application only when the native package matches the architecture of the application's process: win-x64, linux-x64, linux-arm64 or osx-arm64 for a 64-bit process, win-x86 for a 32-bit Windows process (a Windows App Service worker is 32-bit by default). Otherwise conversions run out of process automatically, and assigning ChromiumEngineHostMode.InProcess throws.

• The browser's threads run in the application's process, and its renderer and helper processes stay alive until the application exits.

One conversion can run in its own engine process whatever the mode is, with ForceOutOfProcess: use it for a page you do not trust, one likely to crash or hang the browser, or one that needs a browser-wide setting other than the one the first conversion fixed. It costs the start of an engine process.

HtmlToPdf converter = new HtmlToPdf();

// run this conversion in a separate engine process
converter.Options.ForceOutOfProcess = true;

PdfDocument doc = converter.ConvertUrl("https://selectpdf.com");
doc.Save("Isolated.pdf");
doc.Close();

Dim converter As New HtmlToPdf()

' run this conversion in a separate engine process
converter.Options.ForceOutOfProcess = True

Dim doc As PdfDocument = converter.ConvertUrl("https://selectpdf.com")
doc.Save("Isolated.pdf")
doc.Close()

To render WebGL content the engine has to initialize a software graphics stack for every conversion. Most documents contain no WebGL at all, so WebGlEnabled is False by default and that initialization is skipped. Set it to True for pages that draw with WebGL (map or 3D chart libraries, for example).

The time WebGL costs is fixed per conversion rather than proportional, so it is most visible on small documents: on a typical Windows host a short html page converts in roughly a quarter of the time with WebGL off. A large document saves the same amount of time, which is proportionally less of its total.

This applies to Windows. On Linux that initialization is not a measurable part of a conversion, so turning WebGL on there costs nothing noticeable.

With WebGL off, a page whose content is WebGL does not draw - the browser reports no WebGL context. Ordinary 2D canvas content is not affected and renders identically either way. When the engine runs inside the application, the value of the first conversion applies to the whole process; use ForceOutOfProcess for a conversion that needs the other value.

The property is available on HtmlToPdfOptions and on PdfHtmlSection.

The Chromium engine supports the Select.HtmlToPdf HTML-to-PDF feature set - including automatic bookmark generation and POST data.

Reference

Other Resources