DEV Community: Florentin Badea

SelectPdf in 2026: A Cross-Platform .NET PDF Library for Windows, Linux and macOS

Florentin Badea — Fri, 16 Oct 2026 08:01:57 +0000

I'm the founder of SelectPdf. For most of its twelve years, our .NET PDF library ran on Windows only. If you needed HTML to PDF on Linux or macOS, we pointed you to our REST API. Articles written before October 2026 describe it that way, and for the library of that time they were right.

In October 2026 that changed. Version 26.4 introduced SelectPdf.Universal, a new edition of the library that runs locally on Windows, Linux and macOS. Version 26.5, released ten days later, added a remote engine that also takes it to Alpine Linux and Kubernetes. This article walks through what the library looks like now, with code.

Where it runs

SelectPdf.Universal runs on:

Windows x64 and x86
Linux x64 and ARM64
macOS on Apple Silicon
Docker containers, and through the remote engine, Alpine Linux and Kubernetes

It targets .NET 8, .NET 10 and .NET Standard 2.0, so it works on everything from .NET Framework 4.6.1 to the current .NET releases. We have verified it on Azure App Service, Azure Functions, AWS Lambda and Google Cloud Run.

Installing takes one package for the platform you deploy to:

dotnet add package SelectPdf.Universal.Linux

The others are SelectPdf.Universal.Windows, SelectPdf.Universal.Linux.Arm64 and SelectPdf.Universal.MacOS. Each one installs the library together with the rendering engine for its platform. A build that targets several platforms references SelectPdf.Universal plus one SelectPdf.Universal.Native.<rid> package per runtime instead.

On Linux, the engine package brings the libraries Chromium needs, so a Docker image needs no apt-get step:

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -f net10.0 -o /out

FROM mcr.microsoft.com/dotnet/runtime:10.0-noble
# no apt-get: the Chromium closure ships in SelectPdf.Universal.Native.linux-x64
WORKDIR /app
COPY --from=build /out ./
ENTRYPOINT ["dotnet", "/app/PdfSample.dll"]

The native packages need glibc 2.30 or later (Debian 11+, Ubuntu 20.04+, RHEL 9+). For musl-based images such as Alpine, there is the remote engine, below.

HTML to PDF

The API is the one SelectPdf users already know, in a new namespace:

using SelectPdf.Universal;

HtmlToPdf converter = new HtmlToPdf();

// A4 portrait with 20 mm margins (margins are in points: 20 mm = 57 pt)
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;
converter.Options.MarginTop = 57;
converter.Options.MarginBottom = 57;
converter.Options.MarginLeft = 57;
converter.Options.MarginRight = 57;

// a web page, by URL
PdfDocument page = converter.ConvertUrl("https://selectpdf.com");
page.Save("webpage.pdf");
page.Close();

The rendering engine is Chromium, so flexbox, grid, web fonts and current JavaScript render the way they do in the browser. There is one engine, so there is no engine to choose.

Async, with cancellation

The library has a Task-based API: ConvertUrlAsync and ConvertHtmlStringAsync on the HTML converter, async methods on the HTML to image converter, and AddAsync for HTML placed into an existing document. Each takes a CancellationToken:

using SelectPdf.Universal;

// in a web app or service: await the conversion, and give up after 30 seconds
using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(30));

HtmlToPdf converter = new HtmlToPdf();
PdfDocument doc = await converter.ConvertUrlAsync("https://selectpdf.com", timeout.Token);

byte[] pdf = doc.Save();   // the PDF as bytes, for a response or a database
doc.Close();

Up to eight conversions run in parallel by default, and the rest queue in arrival order. Version 26.5 made parallel conversions much faster.

New in 26.4: beyond HTML to PDF

Word to PDF. docx, doc, rtf, txt, WordML, HTML and Markdown files convert directly, on every platform:

using SelectPdf.Universal;

WordToPdf converter = new WordToPdf();
converter.Options.PageSetup = WordPageSetup.Document;   // each page keeps its Word size
converter.Options.Bookmarks = WordBookmarks.Headings;   // the PDF outline comes from the headings

PdfDocument doc = converter.ConvertFile("report.docx");
doc.Save("report.pdf");
doc.Close();

Redaction. Text, images and form fields are removed from the file, not just covered. You can redact by area, by exact text or by regular expression:

using System.Text.RegularExpressions;
using SelectPdf.Universal;

var redactor = new PdfRedactionManager();
redactor.Load("statement.pdf");
redactor.AddRedaction(new Regex(@"\d{4}-\d{4}-\d{4}-\d{4}"));   // card numbers
redactor.OverlayText = "REDACTED";
redactor.Redact();
redactor.Save("statement-redacted.pdf");
redactor.Close();

Signature validation, with trust and revocation checks, next to signing.

Standards. Accessible PDF/UA-1 and PDF/UA-2 output, on new, converted and loaded documents; PDF/A-4, 4e and 4f archiving; and ZUGFeRD / Factur-X electronic invoices. New documents are encrypted with AES-256 by default.

New in 26.5: the remote engine

The library can hand its conversions to an engine running in a container on another machine. Set the rendering engine and point the library at the engine's address:

using SelectPdf.Universal;

// convert in the SelectPdf engine container instead of on this machine
GlobalProperties.RenderingEngine = RenderingEngine.ChromiumRemote;
GlobalProperties.EngineEndpoint = "http://selectpdf-engine:8080";

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

HTML to PDF, HTML to image, PDF to text and PDF to image then run in the engine container, and the application needs no native package at all. That is what brings SelectPdf to Alpine Linux and other musl-based systems. The engine image is published for linux/amd64 and linux/arm64 as ghcr.io/selectpdf/engine, with a Helm chart, and the documentation has tested setups for Docker Compose, Kubernetes, Azure Container Apps, Amazon ECS and Google Cloud Run.

Also new in 26.5

Tables of contents with page numbers, built while the HTML converts. The library can add leaders and page numbers to a table of contents the page already has, write one into the page from its headings, or insert separate table of contents pages:

HtmlToPdf converter = new HtmlToPdf();
converter.Options.TableOfContents.Mode = PdfTableOfContentsMode.GeneratePages;
converter.Options.TableOfContents.HeadingSelectors = new[] { "h1", "h2" };
PdfDocument doc = converter.ConvertHtmlString(html);

Fillable PDF forms from HTML forms. With converter.Options.CreateFormFields = true, the text inputs, check boxes, radio buttons, drop-down lists and text areas of the page become PDF form fields, with their values, labels and options.

Signing with keys the library never sees. PKCS#11 tokens, smart cards and HSMs, the certificate store, or a remote signing service, with long-term validation (PAdES B-LT) and SHA-384 or SHA-512:

// the key stays on the token; the library sends it the digest to sign
var signer = new PdfPkcs11Signer("path/to/pkcs11-library", pin, "token label", "key label");
var signature = new PdfDigitalSignatureElement(50, 50, 240, 80, signer);
signature.DigestAlgorithm = PdfSignatureDigest.SHA384;
signature.EnableLtv = true;   // embed the revocation data (PAdES B-LT)
doc.Pages[0].Add(signature);
doc.Save("signed.pdf");

More archiving levels: PDF/A-1a, PDF/A-2a and PDF/A-2u. Smaller files from pages with large photos, and text search in Chinese, Japanese, Korean, Hindi, Thai and Arabic.

For projects still on wkhtmltopdf

wkhtmltopdf is no longer maintained. Four new open-source packages, SelectPdf.Compat.DinkToPdf and SelectPdf.Compat.WkHtmlToPdfDotNet, each with a .Licensed version, keep the API of the DinkToPdf and Haukcode.WkHtmlToPdfDotNet wrappers. Existing converter code builds as it is and renders with Chromium. They are MIT licensed, on GitHub.

The free Community Edition

SelectPdf.HtmlToPdf.Universal is free, with no watermark, and converts HTML to PDF on the same platforms, up to 5 pages per document. It has the same one-package installs (SelectPdf.HtmlToPdf.Windows, .Linux, .Linux.Arm64 and .MacOS) and supports the remote engine. Your code can check whether the page limit cut a document:

PdfDocument doc = converter.ConvertHtmlString(html);
if (converter.ConversionResult.PdfPageCountBeforeLimit > converter.ConversionResult.PdfPageCount)
    Console.WriteLine("the 5-page limit cut this document");

The classic library

The classic SelectPdf library for Windows is still maintained and receives selected updates; it is version 26.5 too. It remains the choice for .NET Framework 2.0 and later, and for projects that use the WebKit or Blink engines.

Moving an existing project to SelectPdf.Universal is mostly mechanical: new packages, a new namespace, and SelectPdf's own drawing types in place of System.Drawing. 82% of the classic library's public types and members carry over unchanged apart from the namespace, and the migration guide lists every change.

Licensing

One perpetual license per developer, from $499, covers both SelectPdf.Universal and the classic Windows library.

HTML to PDF in a .NET Docker container, with no apt-get

Florentin Badea — Mon, 05 Oct 2026 13:29:13 +0000

Disclosure: I work on SelectPdf, the library used in this article. It's a commercial library with a free Community Edition; both are covered at the end.

If you've ever generated PDFs from HTML in a Linux container, you probably know the drill: a headless browser needs a long list of shared libraries, so the Dockerfile grows an apt-get install line with twenty-odd packages, then fonts, then sometimes --no-sandbox or a bigger --shm-size. Every base-image update is a chance for that list to break.

This article builds a small ASP.NET Core service that converts web pages and HTML to PDF in a stock .NET runtime container, with none of that. It uses SelectPdf.Universal, which renders with Chromium and ships the engine, with everything it needs, inside a NuGet package.

What we're building

A minimal API with two endpoints:

GET /pdf?url=… returns any web page as a PDF
POST /pdf with an HTML body returns that HTML as a PDF

1. The project

Create a web project and add two packages: the library, and the native engine for the platform the container runs on.

dotnet new web -n PdfService
cd PdfService
dotnet add package SelectPdf.Universal
dotnet add package SelectPdf.Universal.Native.linux-x64

The native package is the part that makes the container story simple: it carries the complete Chromium shared-library closure, including the modules Chromium loads at run time for HTTPS. dotnet publish copies it into the output, so the image needs nothing else.

2. The code

Replace Program.cs:

using SelectPdf.Universal;

var app = WebApplication.CreateBuilder(args).Build();

// GET /pdf?url=https://example.com  ->  the page as a PDF download
app.MapGet("/pdf", async (string url, CancellationToken ct) =>
{
    var converter = new HtmlToPdf();
    PdfDocument doc = await converter.ConvertUrlAsync(url, ct);
    byte[] pdf = doc.Save();
    doc.Close();
    return Results.File(pdf, "application/pdf", "page.pdf");
});

// POST /pdf with an HTML body  ->  that HTML as a PDF
app.MapPost("/pdf", async (HttpRequest request, CancellationToken ct) =>
{
    string html = await new StreamReader(request.Body).ReadToEndAsync(ct);
    var converter = new HtmlToPdf();
    PdfDocument doc = await converter.ConvertHtmlStringAsync(html, ct);
    byte[] pdf = doc.Save();
    doc.Close();
    return Results.File(pdf, "application/pdf", "document.pdf");
});

app.Run();

The async methods take a CancellationToken, so a client that disconnects cancels its conversion. doc.Save() with no arguments returns the PDF as a byte array; doc.Save("file.pdf") writes it to disk instead.

3. The Dockerfile

A standard multi-stage build. Note what's not in it:

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish PdfService.csproj -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080
USER app
ENTRYPOINT ["dotnet", "PdfService.dll"]

No apt-get, no fonts step, no Xvfb. The engine renders headless, so there's no display server. It also runs as the image's built-in non-root app user: when the app is published on Linux, as it is inside this build, the native package makes the engine files readable and executable for every user.

Add a .dockerignore so local build output stays out of the image:

bin/
obj/

4. Build and run

docker build -t pdfservice .
docker run --rm -p 8080:8080 pdfservice

A plain docker run: no --no-sandbox, no added capabilities, no privileged mode, no GPU and no --shm-size. Docker's default 64 MB of shared memory is enough.

Try it:

curl -o page.pdf "http://localhost:8080/pdf?url=https://example.com"

curl -X POST -H "Content-Type: text/html" \
     --data-binary "<h1>Hello from Docker</h1>" \
     -o hello.pdf http://localhost:8080/pdf

5. Fonts for every language

Base images ship with no fonts at all. The library carries the Liberation fonts, so Latin, Greek and Cyrillic text renders correctly out of the box. For anything else (Chinese, Japanese, Korean, Arabic, Hebrew, Hindi, Thai and more, plus color emoji), add one package:

dotnet add package SelectPdf.Universal.Fonts

It copies the Noto fonts into your publish output at build time, so nothing gets installed in the image. With it referenced, this renders correctly in the same container:

curl -X POST -H "Content-Type: text/html; charset=utf-8" \
     --data-binary "<p>中文 日本語 العربية 😀</p>" \
     -o languages.pdf http://localhost:8080/pdf

6. ARM64, and building on a Mac

For ARM64 containers (AWS Graviton, Ampere, or Docker on an Apple Silicon Mac), reference SelectPdf.Universal.Native.linux-arm64 instead of linux-x64. Nothing else changes: the mcr.microsoft.com/dotnet tags are multi-architecture, so the same FROM lines pick the right image.

One thing that catches people on a Mac: Docker Desktop runs Linux containers, so the image needs linux-arm64, not osx-arm64. The macOS package is for apps running natively on macOS.

What works, and what doesn't

Base images. Any glibc-based .NET image. The engines need glibc 2.30 or newer, which covers Ubuntu 20.04+, Debian 11+ and RHEL 9+. Verified end to end, with a real HTTPS page and no packages installed: Debian 12, Ubuntu 22.04, Ubuntu 24.04, and Amazon Linux 2023 through a self-contained publish.

Not supported: Alpine. The native engines need glibc, and Alpine uses musl. Stay on the default Debian or Ubuntu based tags.

Resources. Chromium-based rendering likes CPU and memory. Plan for at least 1 core and 2 GB of RAM per container, and 2+ cores if you convert a lot under load.

Windows containers work too, on Windows Server Core, but they need a step to install the core Windows fonts. If Windows isn't a requirement, Linux containers are smaller and simpler.

Licensing

SelectPdf.Universal is commercial. Without a license the output carries a trial watermark; with one, set GlobalProperties.LicenseKey at startup. Licenses are perpetual and per developer, from $499, and one license covers both SelectPdf.Universal and the classic Windows library.
SelectPdf.HtmlToPdf.Universal is the free Community Edition: HTML to PDF only, free for commercial use, no watermark, up to 5 pages per document. The code in this article runs unchanged with it: reference SelectPdf.HtmlToPdf.Universal instead of SelectPdf.Universal, keep the same native package, and longer documents stop at five pages.

Wrapping up

The whole container story comes down to two dotnet add package lines and an ordinary Dockerfile. The documentation has more: a Docker deployment guide with Windows containers and batch jobs, and step-by-step pages for Azure Container Apps, AWS Lambda and Google Cloud Run.

Cross-platform library: https://selectpdf.com/pdf-library-cross-platform/
Launch post (what's new in 26.4): https://selectpdf.com/selectpdf-universal-our-new-flagship-net-pdf-library-on-linux-macos-and-docker/

If you try it and hit something this article doesn't cover, let me know in the comments.

HTML to PDF in C#: The Complete Guide

Florentin Badea — Tue, 07 Jul 2026 15:39:39 +0000

This is a complete, hands-on guide to converting HTML to PDF in C# with the SelectPdf library for .NET. It works up from a three-line conversion to a production-ready workflow: every one of the 19 code steps is a full, compiling example taken straight from this project and rendered with the Chromium engine, so the code you copy is code that actually runs. Along the way you will build a real invoice from a data model, render complex CSS and paginating tables, control layout, handle dynamic and authenticated pages, secure and archive your output, integrate with ASP.NET Core, and finish with notes on running in production and troubleshooting.

Getting started

Add the SelectPdf packages, then build and run:

dotnet add package Select.Pdf.NetCore
dotnet add package Select.Pdf.NetCore.Chromium.Windows
dotnet run

Running the project writes each result PDF to output/ and the preview images shown below into images/.

Part 1 - Getting started

Convert an HTML string to PDF
Convert a URL to PDF
Convert a local HTML file to PDF

Part 2 - Build a real document

Build an invoice from a template
Render complex HTML that paginates

Part 3 - Control the page layout

Set page size, orientation and margins
Add headers and footers with page numbers
Use HTML for headers and footers
Generate bookmarks from HTML headings
Produce a single-page PDF
Add a watermark to every page

Part 4 - Dynamic and remote content

Wait for JavaScript-rendered content
Inject custom CSS and run a script
Control the browser viewport width
Send HTTP headers and cookies

Part 5 - Secure, archive, integrate

Set the document properties
Password-protect and restrict permissions
Create an archivable PDF/A-3 document
Generate a PDF in ASP.NET Core

Part 6 - Run it in production

Running in production
Troubleshooting

FAQ

Frequently asked questions

Part 1 - Getting started

1. Convert an HTML string to PDF

The simplest conversion: render a raw HTML string into a PDF document in a few lines of code.

// Create the HTML to PDF converter and select the Chromium (CEF) engine.
HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Convert a raw HTML string into a PDF document.
PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Hello, SelectPdf!</h1>" +
    "<p>This PDF was generated from an HTML string in C#.</p>");

// Save the document to disk, then release the native resources.
doc.Save(outputPdf);
doc.Close();

Output:

2. Convert a URL to PDF

Point the converter at any public web address and capture the rendered page as a PDF.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Convert a live web page to a PDF document.
PdfDocument doc = converter.ConvertUrl("https://www.selectpdf.com");

doc.Save(outputPdf);
doc.Close();

Output:

3. Convert a local HTML file to PDF

Render an HTML file from disk - together with its local CSS and images - into a PDF.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// ConvertUrl also accepts a local file path; relative CSS and images
// referenced by the file are resolved automatically.
PdfDocument doc = converter.ConvertUrl(htmlFile);

doc.Save(outputPdf);
doc.Close();

Output:

Part 2 - Build a real document

4. Build an invoice from a template

Turn a C# data model into a styled, real-world invoice: branded header, a line-item table, VAT totals and a page-numbered footer.

// 1) Your data - normally from a database or an order.
var items = new[]
{
    new LineItem { Description = "SelectPdf Developer License", Qty = 1, UnitPrice = 499m },
    new LineItem { Description = "Priority Support (1 year)",    Qty = 1, UnitPrice = 199m },
    new LineItem { Description = "On-site training (per day)",    Qty = 2, UnitPrice = 900m },
};

// 2) Render the data into an HTML template (see BuildInvoiceHtml in the source).
string html = BuildInvoiceHtml("INV-1042", items);

// 3) Convert to PDF, adding a footer with page numbers.
HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;
converter.Options.MarginTop = 20;
converter.Options.MarginBottom = 30;

converter.Options.DisplayFooter = true;
converter.Footer.Height = 28;
PdfTextSection pageNo = new PdfTextSection(0, 8,
    "Invoice INV-1042 - page {page_number} of {total_pages}",
    new Font("Arial", 8));
pageNo.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(pageNo);

PdfDocument doc = converter.ConvertHtmlString(html);
doc.Save(outputPdf);
doc.Close();

Output:

5. Render complex HTML that paginates

Prove the engine handles modern CSS - grid layout and a live web font - plus a long table whose header repeats on every page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Give the web font a moment to download before the page is captured.
converter.Options.MinPageLoadTime = 2;

// The report uses CSS grid, a Google web font, and a 30-row table.
// The table header repeats on every page (thead { display: table-header-group })
// and rows are kept whole (page-break-inside: avoid) - all controlled from CSS.
PdfDocument doc = converter.ConvertHtmlString(BuildReportHtml());

doc.Save(outputPdf);
doc.Close();

Output:

Part 3 - Control the page layout

6. Set page size, orientation and margins

Control the physical page: choose A4, switch to landscape, and set the page margins.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Page setup (margins are expressed in points; 72 points = 1 inch).
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Landscape;
converter.Options.MarginLeft = 36;
converter.Options.MarginRight = 36;
converter.Options.MarginTop = 36;
converter.Options.MarginBottom = 36;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>A4 Landscape</h1>" +
    "<p>This page uses a custom size, orientation and half-inch margins.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

7. Add headers and footers with page numbers

Draw a repeating header on every page and a footer that shows "Page X of Y".

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Enable and populate the header.
converter.Options.DisplayHeader = true;
converter.Header.Height = 40;
PdfTextSection headerText = new PdfTextSection(
    0, 12, "SelectPdf Tutorial", new Font("Arial", 10, FontStyle.Bold));
headerText.HorizontalAlign = PdfTextHorizontalAlign.Left;
converter.Header.Add(headerText);

// Enable and populate the footer with page numbering tokens.
converter.Options.DisplayFooter = true;
converter.Footer.Height = 40;
PdfTextSection footerText = new PdfTextSection(
    0, 12, "Page {page_number} of {total_pages}", new Font("Arial", 8));
footerText.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(footerText);

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

doc.Save(outputPdf);
doc.Close();

Output:

8. Use HTML for headers and footers

Build a fully styled header or footer from an HTML fragment instead of plain text.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Render the header from an HTML fragment so it can be fully styled with CSS.
converter.Options.DisplayHeader = true;
converter.Header.Height = 50;

PdfHtmlSection header = new PdfHtmlSection(
    "<div style='font-family:Arial;color:#b45309;font-size:18px;" +
    "border-bottom:2px solid #b45309;padding:6px 0;'>Acme Corporation</div>",
    string.Empty);
header.RenderingEngine = RenderingEngine.Chromium;
header.AutoFitHeight = HtmlToPdfPageFitMode.AutoFit;
converter.Header.Add(header);

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Report body</h1><p>The header above is rendered from HTML.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

9. Generate bookmarks from HTML headings

Turn the document's headings into a clickable PDF bookmarks (outline) tree.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Build PDF bookmarks from the elements matching these CSS selectors.
converter.Options.PdfBookmarkOptions.CssSelectors = new string[] { "h1", "h2" };

// Open the document with the bookmarks (outline) panel visible.
converter.Options.ViewerPreferences.PageMode = PdfViewerPageMode.UseOutlines;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Chapter 1</h1><p>Introduction.</p>" +
    "<h2>Section 1.1</h2><p>Details.</p>" +
    "<h1>Chapter 2</h1><p>More content.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

10. Produce a single-page PDF

Fit the whole document onto one continuous page with no page breaks - handy for receipts and tickets.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Produce one continuous page sized to the content, instead of paginating.
converter.Options.GenerateSinglePagePdf = true;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Single-page output</h1>" +
    "<p>Section one.</p><p>Section two.</p><p>Section three.</p>" +
    "<p>All content stays on a single, taller page with no page breaks.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

11. Add a watermark to every page

Stamp a semi-transparent text watermark - such as CONFIDENTIAL or DRAFT - behind the content of every page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Draft report</h1><p>Every page of this document carries a watermark.</p>");

// Draw a large, light "CONFIDENTIAL" behind the content of every page,
// using a background template that repeats on all pages.
PdfFont font = doc.AddFont(PdfStandardFont.Helvetica);
font.Size = 50;

RectangleF pageRect = doc.Pages[0].ClientRectangle;
PdfTemplate template = doc.AddTemplate(pageRect);
template.Background = true;

PdfTextElement watermark = new PdfTextElement(
    0, pageRect.Height / 2 - 30, pageRect.Width, "CONFIDENTIAL", font);
watermark.ForeColor = Color.FromArgb(210, 210, 210);
watermark.HorizontalAlign = PdfTextHorizontalAlign.Center;
template.Add(watermark);

doc.Save(outputPdf);
doc.Close();

Output:

Part 4 - Dynamic and remote content

12. Wait for JavaScript-rendered content

Give client-side scripts time to run so dynamic content is captured instead of a half-loaded page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Give client-side scripts time to run before the page is captured (seconds).
converter.Options.MinPageLoadTime = 2;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Dynamic content</h1>" +
    "<p id='status'>Loading...</p>" +
    "<script>setTimeout(function(){" +
    "document.getElementById('status').innerHTML = 'Loaded by JavaScript!';" +
    "}, 800);</script>");

doc.Save(outputPdf);
doc.Close();

Output:

13. Inject custom CSS and run a script

Restyle the page with your own CSS and execute JavaScript after load, without touching the source HTML.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Inject additional CSS into the page before rendering.
converter.Options.CustomCSS =
    "body { font-family: Arial; background: #fef3c7; }" +
    "h1 { color: #b45309; }";

// Run JavaScript after the page has loaded (Chromium/Blink only).
converter.Options.PostLoadingScript =
    "document.body.insertAdjacentHTML('beforeend', '<p>Added by script.</p>');";

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Custom styled page</h1>" +
    "<p>The amber background and heading color come from injected CSS.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

14. Control the browser viewport width

Set the virtual browser width the HTML is laid out at, then shrink oversized layouts to fit the PDF page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Lay the HTML out at a fixed 1200px browser width...
converter.Options.WebPageWidth = 1200;
converter.Options.WebPageFixedSize = true;

// ...then shrink it so the wide layout fits the PDF page width.
converter.Options.AutoFitWidth = HtmlToPdfPageFitMode.ShrinkOnly;

PdfDocument doc = converter.ConvertHtmlString(
    "<div style='width:1200px;background:#e0f2fe;padding:24px'>" +
    "<h1>Wide layout</h1>" +
    "<p>Rendered at a 1200px viewport, then shrunk to fit the page.</p></div>");

doc.Save(outputPdf);
doc.Close();

Output:

15. Send HTTP headers and cookies

Attach custom request headers and cookies to reach authenticated or localized pages.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Attach custom request headers (e.g. language, bearer token) and cookies.
converter.Options.HttpHeaders.Add("Accept-Language", "en-US");
converter.Options.HttpCookies.Add("session", "demo-cookie-value");

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

doc.Save(outputPdf);
doc.Close();

Output:

Part 5 - Secure, archive, integrate

16. Set the document properties

Fill in the PDF title, author, subject and keywords shown in the viewer and used by search indexes.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Quarterly Report</h1><p>Prepared for Acme Corporation.</p>");

// These appear in the viewer's "Document Properties" dialog and in search indexes.
doc.DocumentInformation.Title = "Quarterly Report";
doc.DocumentInformation.Author = "SelectPdf";
doc.DocumentInformation.Subject = "Q3 financial results";
doc.DocumentInformation.Keywords = "report, quarterly, finance";
doc.DocumentInformation.CreationDate = DateTime.Now;

doc.Save(outputPdf);
doc.Close();

Output:

17. Password-protect and restrict permissions

Encrypt the PDF with an owner password and disable copying and editing.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Encrypt with an owner password and restrict what readers may do.
// (Set UserPassword as well to also require a password just to open the file.)
converter.Options.SecurityOptions.OwnerPassword = "owner-secret";
converter.Options.SecurityOptions.CanPrint = true;
converter.Options.SecurityOptions.CanCopyContent = false;
converter.Options.SecurityOptions.CanEditContent = false;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Confidential</h1><p>Copying and editing are disabled on this document.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

18. Create an archivable PDF/A-3 document

Emit a PDF/A-3B file suitable for long-term archiving and compliance.

HtmlToPdf converter = new HtmlToPdf();

// PDF/A (and tagged/accessible) output requires the Chromium engine.
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Emit a PDF/A-3B document suitable for long-term archiving.
converter.Options.PdfStandard = PdfStandard.PdfA3B;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Archivable document</h1>" +
    "<p>Saved as PDF/A-3B for long-term archiving and compliance.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

19. Generate a PDF in ASP.NET Core

Build the PDF in a controller action and stream it straight to the browser as a downloadable file.

// In an ASP.NET Core app, generate the PDF inside a controller action and stream it back.
public sealed class InvoiceController : ControllerBase
{
    [HttpGet("/invoice/{id:int}")]
    public IActionResult Get(int id)
    {
        HtmlToPdf converter = new HtmlToPdf();
        converter.Options.RenderingEngine = RenderingEngine.Chromium;

        PdfDocument doc = converter.ConvertHtmlString(
            $"<h1>Invoice #{id}</h1><p>Thank you for your order.</p>");

        // Save straight to a byte array - no temp file needed.
        byte[] pdf = doc.Save();
        doc.Close();

        // Return it as a downloadable file (omit the file name to show it inline).
        return File(pdf, "application/pdf", $"invoice-{id}.pdf");
    }
}

Output:

Part 6 - Run it in production

20. Running in production

SelectPdf runs entirely in-process and is Windows-only (x86 and x64) - there is no Linux or macOS build, and the host needs full trust. Factor that into your hosting choice before you commit.

A converter instance is not thread-safe: create one HtmlToPdf per conversion rather than sharing one across threads, and cap parallelism with your own queue or semaphore - the library has no built-in concurrency limit.

Deployment - ship Select.Pdf.dll together with Select.Html.dep and Select.Tools.dep; for the Chromium engine also deploy its runtime folder (the Chromium.Windows package copies it on build).
Process bitness - match the package to the process or you get a BadImageFormatException. Under IIS, Enable 32-Bit Applications = True runs x86, False runs x64.
Memory - on 64-bit servers use the x64 package - it can allocate far more memory for image-heavy pages.
Timeouts - the default navigation timeout is 60 seconds; raise Options.MaxPageLoadTime for slow pages and use MinPageLoadTime to wait for late assets.
Licensing - set GlobalProperties.LicenseKey once at startup, before any conversion; the trial watermarks every page.
Untrusted HTML - disable scripts (Options.JavaScriptEnabled = false) and local file access (Options.DenyLocalFileAccess = true) when converting input you do not control.
Azure - App Service needs the Chromium engine (v26.2+, Basic plan or above); Virtual Machines and Cloud Services have no restrictions.

21. Troubleshooting

A handful of problems come up again and again - here is the quick fix for each.

Blank page, or images and CSS missing from an HTML string - pass a base URL: ConvertHtmlString(html, baseUrl) so relative URLs resolve.
Dynamic content missing - the page needs more time or a signal - set Options.MinPageLoadTime, or use WindowStatus / PostLoadingScript.
BadImageFormatException - the x86 or x64 package does not match the process bitness.
Could not find Select.Html.dep - copy Select.Html.dep and Select.Tools.dep next to Select.Pdf.dll.
Navigation timeout - the page is slower than 60s, the URL is not resolvable from the server, or a proxy is required - raise MaxPageLoadTime or set Options.ProxyOptions.
An image splits across two pages - set Options.KeepImagesTogether = true, or style the img with page-break-inside: avoid.
OutOfMemoryException - an image-heavy page - use the x64 package and optimize the images.

FAQ

22. Frequently asked questions

Is SelectPdf free? - The Community Edition (Select.HtmlToPdf) is free for HTML to PDF with a 5-page cap. This tutorial uses the commercial Select.Pdf library - a paid license with the full feature set and no page limit.
Does it run on Linux, macOS or in Docker? - No. The library is Windows-only (x86 and x64). To generate PDFs from Linux, host it on Windows or use the SelectPdf online HTML-to-PDF REST API instead.
Which rendering engine should I use? - Chromium (used throughout this tutorial) for modern HTML5, CSS3 and web fonts. WebKit is the embedded default with nothing extra to deploy; Blink is an alternative Chromium-based engine. Chromium and Blink each need their companion NuGet package.
How do I remove the trial watermark? - Set GlobalProperties.LicenseKey once at application startup, before any conversion. See .NET library pricing for license options.
Can it convert a page that requires login? - Yes - send authentication cookies or headers (see Send HTTP headers and cookies), or post form data with HttpPostParameters.
Is there a limit on the number of pages? - Not in the commercial library. The 5-page cap applies only to the free Community Edition.
Can I convert charts or content drawn by JavaScript? - Yes, with the Chromium engine. Give scripts time to run with Options.MinPageLoadTime, or wait for a signal via WindowStatus (see Wait for JavaScript-rendered content).
Is the converter thread-safe? - Use one HtmlToPdf instance per conversion and throttle concurrency yourself; see Running in production.

Conclusion

That is the full arc of HTML to PDF with SelectPdf - from a three-line string conversion to a real invoice, complex paginating layouts, security, archival compliance, ASP.NET Core integration and production hardening. Because the same Chromium engine powers every example, what you preview in the browser is what lands in the PDF. Start with a free trial, browse the full API reference, or try the live C# demo.

wkhtmltopdf is archived. A straight .NET migration guide (Windows, Linux, Docker and Azure)

Florentin Badea — Sun, 05 Jul 2026 06:53:30 +0000

Updated October 2026 for SelectPdf 26.4: the library now runs on Linux, in Docker and on macOS on Apple Silicon as well, through the new SelectPdf.Universal packages. The Linux sections below are rewritten accordingly.

If your .NET app still calls DinkToPdf, NReco.PdfGenerator, Rotativa, or WkHtmlToXSharp in production, you're shipping a wrapper around a binary that hasn't had a security patch in years — and one of its open holes is a CVSS 9.8.

wkhtmltopdf's repository has been frozen and read-only since January 2023, and the whole project org was archived by mid-2024. Development has stopped; nobody is accepting patches. The underlying QtWebKit engine forked from upstream around 2012 — no modern Flexbox, no Grid, no modern JavaScript, no ICU updates. And CVE-2022-35583 — an SSRF that lets an attacker reach your internal network by injecting an <iframe> pointing at an internal IP — sits at CVSS 9.8, unpatched, and permanently so.

If your app takes any user-influenced HTML and turns it into a PDF behind a public endpoint, that's not a "someday" cleanup. This post is the migration I'd actually run.

Disclosure: I work on SelectPdf, a .NET PDF library, and the code below is SelectPdf because that's what I can vouch for line by line. I'll be honest about where it fits and where it doesn't. The broader point stands no matter what you pick: stop wrapping the dead binary.

First: Windows, Linux or Docker?

I'm putting this at the top because it decides which packages you install, and nothing annoys an engineer more than finding it in paragraph 30. The good news: since version 26.4 there is a SelectPdf library for each case.

Linux, Docker, macOS on Apple Silicon — or any new project on modern .NET — use SelectPdf.Universal, the new flagship edition. It runs on Windows (x64, x86), Linux (x64, ARM64) and macOS on Apple Silicon, targets .NET 8 and .NET 10 plus .NET Standard 2.0, and renders with Chromium. You reference the library plus one native package per runtime you deploy to.
An existing Windows or .NET Framework app (IIS, a VM, Windows App Service) — the classic SelectPdf library is a direct NuGet reference with one API call, supports .NET Framework 2.0 and later, and keeps its four rendering engines. It is still maintained.
Not on .NET, or you want nothing to deploy at all — SelectPdf's Online REST API: your app POSTs HTML and gets back PDF bytes over HTTPS, from any OS and any language.

Linux is where wkhtmltopdf hurts most today (newer glibc/libssl combos crash it, and it's no one's job to fix), so it's worth being specific. The SelectPdf.Universal.Native.linux-x64 and linux-arm64 packages carry the shared libraries Chromium needs, so a stock .NET runtime image converts pages with no apt-get step, no X server and no special docker run flags. That was verified with real HTTPS conversions on Debian 12, Ubuntu 22.04, Ubuntu 24.04 and Amazon Linux 2023. Latin, Greek and Cyrillic text prints with the fonts built into the library; for other scripts (Arabic, Chinese, Japanese, Korean, Hindi, Thai and more) add the optional SelectPdf.Universal.Fonts package — also just a NuGet reference.

"Why not just use Playwright or PuppeteerSharp?"

Fair question, and for some teams that's the right call — they're free, cross-platform, and render with real Chromium. Here's the honest trade:

With Playwright/PuppeteerSharp you operate the browser yourself. You run a provisioning step (playwright install, or bundling the binaries) and version-manage Chromium; you own the headless browser's lifecycle (zombie processes are real under load); you write your own concurrency throttling; and you write and maintain the automation script. On Linux you also chase down the font and shared-library packages so text doesn't render as boxes. On Windows App Service specifically, a raw headless browser tends to fight the sandbox too — a similar restriction to the Win32k/GDI wall that bites wkhtmltopdf (more on that below).

Now the honest part, about what is not a difference: SelectPdf also ships a bundled Chromium (CEF) runtime of broadly similar size — so the disk/image footprint is roughly a wash. Chromium is Chromium. What differs is who provisions and babysits it. SelectPdf ships the matched runtime as a NuGet package that the build copies into your output automatically (no separate install step, no version drift), manages the browser for you, and caps parallelism through one built-in setting (MaximumConcurrentConversions) — all behind a single call that returns the PDF. On Linux the native package already carries the shared libraries, so there is nothing to apt-get. The engine is also built to run inside the App Service sandbox where a raw headless browser struggles. You don't write automation, and you don't provision a browser fleet.

And there's a scope difference that outlasts the migration: Playwright and Puppeteer only print HTML to PDF. The moment your requirements grow past "render this page" — merge the invoice with a cover sheet, stamp a watermark, fill an AcroForm, digitally sign it, encrypt it, or extract the text back out for search — you're bolting on a second PDF library (PdfSharp, iText, QuestPDF) and gluing two toolchains together. SelectPdf's commercial library does the rendering and that post-processing in one dependency: create PDFs from scratch, merge/split, stamp, fill and flatten forms, sign, encrypt, extract text and images, and emit tagged PDF/UA or PDF/A for accessibility and archival. (The free Community Edition is HTML→PDF only — these extras are the paid library.) If rendering HTML is genuinely all you'll ever do, that breadth doesn't matter and Puppeteer is fine. If you can feel a "can you also…" ticket coming, one library beats two.

If your team is happy operating headless Chrome directly and never needs more than print-to-PDF, Puppeteer is a perfectly defensible choice. Pick with eyes open.

(One more note on the "is it even alive?" question, since wkhtmltopdf just taught everyone to ask it: SelectPdf shipped **v26.4 in October 2026* — the release that added SelectPdf.Universal for Linux, Docker and macOS on Apple Silicon — and the packages sit at 23M+ NuGet downloads. Actively maintained, with a paid tier where a human answers.)*

What "archived" actually means for your stack

Most teams know wkhtmltopdf is "old" but haven't priced in the archive:

No more CVE patches. Ever. CVE-2022-35583 is filed, triaged, and will never be fixed upstream. Any SSRF reported after the repo froze lands in a read-only tracker.
QtWebKit is frozen near 2012. CSS Grid, container queries, modern JS, modern font features — anything your designers shipped in the last decade renders unreliably or not at all.
The .NET wrappers fix none of this. DinkToPdf, NReco.PdfGenerator, Rotativa.AspNetCore, WkHtmlToXSharp all P/Invoke into the same libwkhtmltox native binary. If wkhtmltopdf isn't patched, neither are they. (DinkToPdf itself hasn't shipped a release since 2017.)

The migration, in code

Here's a typical DinkToPdf setup — note the injected IConverter, which DinkToPdf requires as a singleton because the native lib can't be loaded repeatedly:

// Old: DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;

public class InvoiceController : ControllerBase
{
    private readonly IConverter _converter;
    public InvoiceController(IConverter converter) => _converter = converter;

    [HttpGet("invoice/{id}")]
    public IActionResult Get(int id)
    {
        var html = RenderInvoiceHtml(id);

        var doc = new HtmlToPdfDocument
        {
            GlobalSettings = {
                PaperSize = PaperKind.A4,
                Orientation = Orientation.Portrait,
                Margins = new MarginSettings { Top = 20, Bottom = 20 }
            },
            Objects = { new ObjectSettings { HtmlContent = html } }
        };

        var pdf = _converter.Convert(doc);
        return File(pdf, "application/pdf", $"invoice-{id}.pdf");
    }
}

Same endpoint with SelectPdf.Universal — the same code runs on Windows, Linux and macOS on Apple Silicon:

// New: SelectPdf.Universal
using SelectPdf.Universal;

public class InvoiceController : ControllerBase
{
    [HttpGet("invoice/{id}")]
    public IActionResult Get(int id)
    {
        var html = RenderInvoiceHtml(id);

        var converter = new HtmlToPdf();
        converter.Options.PdfPageSize        = PdfPageSize.A4;
        converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;
        converter.Options.MarginTop = 20;
        converter.Options.MarginBottom = 20;

        PdfDocument doc = converter.ConvertHtmlString(html);
        try
        {
            byte[] bytes = doc.Save();   // parameterless Save() returns the PDF bytes
            return File(bytes, "application/pdf", $"invoice-{id}.pdf");
        }
        finally
        {
            doc.Close();
        }
    }
}

On the classic Windows library the code is the same apart from using SelectPdf; and one extra line to pick the engine: converter.Options.RenderingEngine = RenderingEngine.Chromium; (SelectPdf.Universal renders with Chromium only, so it needs no such line).

About that lifecycle change

You probably noticed the DI singleton is gone. That's deliberate, and it's the question a careful reviewer should ask: is new HtmlToPdf() per request safe?

Yes. Unlike DinkToPdf's converter, there's no "load the native lib exactly once" dance — you construct a converter per conversion. Parallelism is governed by a single knob, HtmlToPdfOptions.MaximumConcurrentConversions (default 8 in SelectPdf.Universal, 4 in the classic library), which you set once at startup, before the first conversion; requests beyond the limit queue for a slot rather than thrashing the box. So the mental model is: new freely per request, cap total concurrency globally. If you'd rather keep a DI registration for testability, register the converter as transient — it doesn't need to be a singleton. SelectPdf.Universal also has ConvertHtmlStringAsync and ConvertUrlAsync, with cancellation, if your controllers are async.

NuGet packages

# SelectPdf.Universal — Windows, Linux, Docker, macOS on Apple Silicon.
# The library, plus one native package per runtime you deploy to
# (win-x64, win-x86, linux-x64, linux-arm64, osx-arm64).

# Free Community Edition — HTML->PDF only, 5-page cap;
# no PDF post-processing (merge/split, forms, signing, encryption, extraction)
dotnet add package SelectPdf.HtmlToPdf.Universal
dotnet add package SelectPdf.Universal.Native.linux-x64

# Commercial library once you outgrow 5 pages (from $499, perpetual)
dotnet add package SelectPdf.Universal
dotnet add package SelectPdf.Universal.Native.linux-x64

# Optional on Linux: fonts for non-Latin scripts
dotnet add package SelectPdf.Universal.Fonts

# Classic library on Windows (.NET Framework 4.6.1+ and modern .NET;
# for .NET Framework 2.0/4.0 use Select.HtmlToPdf / Select.Pdf)
dotnet add package Select.HtmlToPdf.NetCore                    # free CE
dotnet add package Select.HtmlToPdf.NetCore.Chromium.Windows
dotnet add package Select.Pdf.NetCore                          # commercial
dotnet add package Select.Pdf.NetCore.Chromium.Windows

Reference several native packages if you build for several targets — developing on Windows and deploying to a Linux container is the common case. Be honest with yourself about that 5-page cap: it's free forever, but a typical multi-page invoice or report blows past it, so for real workloads the CE is effectively an evaluation and you'll want a license (pricing). One perpetual license covers both the classic and the Universal library. The classic packages still target net20 and net40 (Select.Pdf, Select.HtmlToPdf) and net461, net472 and netstandard2.0 (the .NetCore packages), so migrating a .NET Framework app doesn't force a TFM bump.

Migrating your wkhtmltopdf flags

The ConvertHtmlString call is the easy 20%. The part that actually took you an afternoon in wkhtmltopdf was the CLI flags — headers, footers, page numbers, margins. Here's the mapping so you're not reverse-engineering it (it is the same in both libraries):

wkhtmltopdf	SelectPdf
`--page-size A4`	`Options.PdfPageSize = PdfPageSize.A4`
`--orientation Landscape`	`Options.PdfPageOrientation = PdfPageOrientation.Landscape`
`--margin-top 20` (etc.)	`Options.MarginTop = 20` (`MarginBottom/Left/Right`)
`--header-html header.html`	`Options.DisplayHeader = true;` then `converter.Header.Add(new PdfHtmlSection(url))`
`--footer-html footer.html`	`Options.DisplayFooter = true;` then `converter.Footer.Add(...)`
`[page] / [topage]` footer tokens	`{page_number}` / `{total_pages}` in a `PdfTextSection`
`--print-media-type`	`Options.CssMediaType = HtmlToPdfCssMediaType.Print`

Footer with page numbers, end to end:

converter.Options.DisplayFooter = true;
converter.Footer.Height = 40;

var pageNo = new PdfTextSection(0, 10,
    "Page {page_number} of {total_pages}",
    PdfFont.CreateStandardFont(PdfStandardFont.Helvetica, 9));
pageNo.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(pageNo);

(On the classic library, PdfTextSection takes a System.Drawing.Font instead, for example new System.Drawing.Font("Arial", 9). SelectPdf.Universal has its own font types because System.Drawing is Windows-only on current .NET.)

That — headers, footers, page numbering — all works in the free Community Edition too, within the 5-page cap.

The Azure App Service angle

This is the one I get asked about most, so I'll be explicit.

Azure App Service on Windows runs your app in a sandbox that blocks most User32/GDI32 (Win32k.sys) system calls — exactly what a GDI-based browser engine bundled in a .NET app needs. That's what makes wkhtmltopdf flaky there: P/Invoke load failures, missing GDI calls, font issues. Bundled headless-Chrome setups tend to struggle in the same sandbox too, for related reasons (process/GPU restrictions rather than GDI specifically).

SelectPdf's Chromium engine — on Chromium 154 as of v26.4 — is built to run inside that sandbox. With SelectPdf.Universal the same code runs on App Service and Azure Functions, on both Windows and Linux, on the Basic plan or above. One caveat worth knowing up front: on Windows, don't deploy with "Run From Package" (WEBSITE_RUN_FROM_PACKAGE) — the engine cannot load its libraries from the mounted package; Zip Deploy and Web Deploy are fine. The classic library runs on Windows App Service (Basic and above), and on Azure Functions when hosted on a Premium or App Service plan. From your code it's the same call you already saw:

var converter = new HtmlToPdf();

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

No "but it works locally" Slack thread at 11pm.

Closing the SSRF loop

We opened on CVE-2022-35583, so let's not hand-wave the fix. Two things change when you migrate:

You get a kill-switch for local-file exfiltration. Set HtmlToPdfOptions.DenyLocalFileAccess = true per conversion, or GlobalProperties.ForceDenyLocalFileAccess = true process-wide, and file:// reads are blocked — shutting off the local-file-read half of the classic wkhtmltopdf attack. Both libraries have both switches.
The internal-IP SSRF half is a network problem, and the right answer depends on trust. If you convert genuinely untrusted, user-supplied HTML, don't render it on your own infrastructure next to your internal network at all — push it to the Online REST API, so the conversion runs off your infrastructure, away from your internal network. And unlike the archived binary, when a rendering-side issue is found, there's a maintained product that can actually ship a fix.

That's the real difference: not "SelectPdf is magically SSRF-proof," but "you get controls, isolation options, and someone who patches."

What to actually do this week

A pragmatic checklist:

grep the solution for DinkToPdf, NReco.PdfGenerator, Rotativa, WkHtmlToX, wkhtmltopdf. Every hit is a candidate.
Pick the package for where you deploy (see the top): SelectPdf.Universal for Linux, Docker and new projects; the classic library for an existing Windows or .NET Framework app; the Online API for anything else.
Pick the one endpoint that renders user-influenced HTML. Highest-risk surface; start there.
dotnet add package SelectPdf.HtmlToPdf.Universal + SelectPdf.Universal.Native.<rid> for each runtime you deploy to. Free, 5-page cap.
Port the converter call and your header/footer flags using the mapping above; run your existing tests; eyeball the output diff.
If layout shifts (it might — wkhtmltopdf has 2012-era quirks your CSS may lean on), the fix is almost always a CSS cleanup, not a converter tweak.
Past 5 pages, get a license — but validate output on the free build first.

If SelectPdf isn't right for your stack, still migrate. Anything maintained beats an archived 9.8. And if you try it and hit a snag, drop me a line — I read the inbox.

Try it:

Cross-platform library (Windows, Linux, Docker, macOS on Apple Silicon): selectpdf.com/pdf-library-cross-platform
Free Community Edition: selectpdf.com/community-edition
Live demo (paste any URL): selectpdf.com/demo-universal
Online API for any language: selectpdf.com/html-to-pdf-api
Docs, including Docker and Azure deployment: selectpdf.com/pdf-library
NuGet: SelectPdf.HtmlToPdf.Universal

If this was useful, follow — the next post is "Top 10 HTML-to-PDF Libraries for C# / .NET (2026): A Practical Comparison," a fair head-to-head of the real options in this space, including where SelectPdf isn't the right pick.

Stop your AI assistant from hallucinating PDF APIs: SelectPdf AI Tools

Florentin Badea — Wed, 01 Jul 2026 14:38:44 +0000

AI coding assistants are great at .NET boilerplate, but ask one to generate PDF code and it will happily invent a method that doesn't exist, or reach for a commercial feature while claiming it's in the free edition. The model is guessing from training data.

SelectPdf AI Tools fixes that. It's a free, open-source (MIT) set of Agent Skills that give your assistant accurate, version-matched knowledge of the SelectPdf .NET library — real API signatures, working code, and the gotchas that matter.

What's in it

A single Claude Code plugin with two skills:

selectpdf-lib-net — the full commercial Select.Pdf library: HTML→PDF, building/editing PDFs, merge/split, AcroForms, digital signatures, encryption, PDF→text/image, and accessible tagged PDF/UA-1 and PDF/A-3.
selectpdf-lib-htmltopdf-net — the free Community Edition (HTML→PDF).

Every sample is in C# and VB.NET, tracking SelectPdf v26.3.

Install in Claude Code

/plugin marketplace add selectpdf/ai-tools
/plugin install selectpdf@selectpdf

The right skill activates automatically when you ask it to work with PDFs in a .NET project.

Cursor, Copilot, Codex

The same knowledge ships in each tool's native format — Cursor .mdc rules, Copilot .instructions.md, and a Codex AGENTS.md guide. Drop the file into your repo and your assistant is up to speed.

It's all open source, so you can read exactly what your assistant is being told — and send a PR if you spot something. 👉 https://github.com/selectpdf/ai-tools

Want to see the library itself? Browse the online documentation or try the C# and VB.NET live demos.

DEV Community: Florentin Badea

SelectPdf in 2026: A Cross-Platform .NET PDF Library for Windows, Linux and macOS

Where it runs

HTML to PDF

Async, with cancellation

New in 26.4: beyond HTML to PDF

New in 26.5: the remote engine

Also new in 26.5

For projects still on wkhtmltopdf

The free Community Edition

The classic library

Licensing

Links

HTML to PDF in a .NET Docker container, with no apt-get

What we're building

1. The project

2. The code

3. The Dockerfile

4. Build and run

5. Fonts for every language

6. ARM64, and building on a Mac

What works, and what doesn't

Licensing

Wrapping up

HTML to PDF in C#: The Complete Guide

Getting started

Contents

Part 1 - Getting started

1. Convert an HTML string to PDF

2. Convert a URL to PDF

3. Convert a local HTML file to PDF

Part 2 - Build a real document

4. Build an invoice from a template

5. Render complex HTML that paginates

Part 3 - Control the page layout

6. Set page size, orientation and margins

7. Add headers and footers with page numbers

8. Use HTML for headers and footers

9. Generate bookmarks from HTML headings

10. Produce a single-page PDF

11. Add a watermark to every page

Part 4 - Dynamic and remote content

12. Wait for JavaScript-rendered content

13. Inject custom CSS and run a script

14. Control the browser viewport width

15. Send HTTP headers and cookies

Part 5 - Secure, archive, integrate

16. Set the document properties

17. Password-protect and restrict permissions

18. Create an archivable PDF/A-3 document

19. Generate a PDF in ASP.NET Core

Part 6 - Run it in production

20. Running in production

21. Troubleshooting

FAQ

22. Frequently asked questions

Conclusion

wkhtmltopdf is archived. A straight .NET migration guide (Windows, Linux, Docker and Azure)

First: Windows, Linux or Docker?

"Why not just use Playwright or PuppeteerSharp?"

What "archived" actually means for your stack

The migration, in code

About that lifecycle change

NuGet packages

Migrating your wkhtmltopdf flags

The Azure App Service angle

Closing the SSRF loop

What to actually do this week

Stop your AI assistant from hallucinating PDF APIs: SelectPdf AI Tools

What's in it

Install in Claude Code

Cursor, Copilot, Codex