DEV Community: Florentin Badea

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 (Azure, Windows, and the Linux caveat)

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

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 — including a Windows/Linux fork you need to know about before you write any code. The broader point stands no matter what you pick: stop wrapping the dead binary.

First, the honest part: Windows or Linux?

I'm putting this at the top because it decides everything downstream, and nothing annoys an engineer more than finding it in paragraph 30.

If you deploy to Windows (App Service on Windows, Windows containers, a VM, IIS) — the SelectPdf library is a direct NuGet reference: one synchronous API call, no separate service to stand up. This whole guide applies. Keep reading.
If you deploy to Linux (Linux containers, Linux App Service, AKS) — the library is Windows-only. Don't fight it. The cross-platform answer is SelectPdf's Online REST API: your app POSTs HTML and gets back PDF bytes over HTTPS, so it runs on any OS and any language. Same rendering engine, none of the native-dependency wrestling.

Yes — wkhtmltopdf's Linux story is genuinely bad now (newer glibc/libssl combos crash it, and it's no one's job to fix). I'm not going to pretend the SelectPdf library fixes Linux; it doesn't run there. It moves the rendering off-box to the API instead. If rendering must stay self-hosted on Linux and you don't want a hosted call, that's a legitimate reason to look at a headless-Chrome option instead — which brings us to the other question everyone asks.

"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 process 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: with SelectPdf's Chromium engine there is still a browser process, and it ships a bundled Chromium (CEF) runtime of broadly similar size — so the disk/image footprint and cold-start cost are roughly a wash. Chromium is Chromium. What differs is who provisions and babysits it. SelectPdf ships the matched runtime as a NuGet package that MSBuild copies into your output automatically (no separate install step, no version drift), launches and supervises the render process for you, isolates it so a crash doesn't take your app down, and caps parallelism through one built-in setting (MaximumConcurrentConversions) — all behind a single synchronous call that returns bytes. Its CEF engine is also built specifically 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.3 on June 16, 2026, and the core packages sit around **22M+ 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:

// New: SelectPdf
using SelectPdf;

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

        var converter = new HtmlToPdf();
        converter.Options.RenderingEngine    = RenderingEngine.Chromium;
        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();
            return File(bytes, "application/pdf", $"invoice-{id}.pdf");
        }
        finally
        {
            doc.Close();
        }
    }
}

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, Options.MaximumConcurrentConversions (default 4), 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.

NuGet packages

# Free Community Edition — HTML->PDF only, 5-page cap; 
# no PDF post-processing (merge/split, signing, encryption, extraction)
dotnet add package Select.HtmlToPdf.NetCore
dotnet add package Select.HtmlToPdf.NetCore.Chromium.Windows

# Commercial library once you outgrow 5 pages (from $499, perpetual)
dotnet add package Select.Pdf.NetCore
dotnet add package Select.Pdf.NetCore.Chromium.Windows

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). The Chromium.Windows runtime packages are AnyCPU (they run in both x86 and x64 workers); the commercial library additionally ships .x64-pinned variants, the CE does not. On .NET Framework the same packages work — SelectPdf still targets net20, net40, net461, net472, and netstandard2.0, so migrating 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:

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}",
    new System.Drawing.Font("Arial", 9));
pageNo.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(pageNo);

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 runs your app in a Windows 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 — a CEF/Chromium backend introduced in v26.2, on Chromium 148 as of v26.3 — is built to run inside that sandbox. The same code you run on your dev machine runs unchanged on Azure App Service (Basic plan and above), and on Azure Functions when hosted on a Premium or App Service plan (not Consumption or Free/Shared). From your code it's the one line you already saw:

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

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.
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, which runs the conversion in an isolated, SSRF-guarded environment off your infrastructure. 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.
Decide Windows vs Linux first (see the top) — library or Online API. Don't skip this.
Pick the one endpoint that renders user-influenced HTML. Highest-risk surface; start there.
dotnet add package Select.HtmlToPdf.NetCore + Select.HtmlToPdf.NetCore.Chromium.Windows. 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:

Free Community Edition: selectpdf.com/community-edition
Live demo (paste any URL): selectpdf.com/demo
Cross-platform Online API: selectpdf.com/api-pricing
Docs: selectpdf.com/pdf-library
NuGet: Select.HtmlToPdf.NetCore

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

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 (Azure, Windows, and the Linux caveat)

First, the honest part: Windows or Linux?

"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