How to convert HTML to PDF in C#

Install the HTML package

dotnet add package ZingPDF.FromHTML

Convert an HTML string

Use the string overload when your application has already rendered the markup.

The application supplies cancellationToken and sets ZINGPDF_BROWSER_PATH to the installed executable.

using ZingPDF.FromHTML;

await using var renderer = new HtmlToPdfRenderer(new HtmlToPdfOptions
{
    BrowserExecutablePath = Environment.GetEnvironmentVariable("ZINGPDF_BROWSER_PATH")
        ?? throw new InvalidOperationException("Set ZINGPDF_BROWSER_PATH to an installed browser."),
    MaxConcurrency = 4,
    RenderTimeout = TimeSpan.FromSeconds(30)
});

await using var pdfStream = await renderer.RenderAsync("""
<!doctype html>
<html>
<head><style>@page { size: A4; margin: 15mm; }</style></head>
<body><h1>Invoice INV-1001</h1></body>
</html>
""", cancellationToken);

await using var output = File.Create("invoice.pdf");
await pdfStream.CopyToAsync(output, cancellationToken);

Convert a URL

Use the configured renderer above for any absolute URL supported by Chromium, including HTTP, HTTPS, file, data and about URLs. URL content must be trusted.

using ZingPDF.FromHTML;

await using var pdfStream = await renderer.RenderAsync(
    new Uri("https://example.com/report"),
    new NavigationOptions
    {
        TimeoutExpiration = 60_000,
        WaitUntilFlags = WaitUntil.Networkidle0
    }, cancellationToken);

await using var output = File.Create("report.pdf");
await pdfStream.CopyToAsync(output);

Navigation options

NavigationOptions controls URL navigation. The default timeout is 30 seconds. The wait flags map to browser navigation states such as Load, DOMContentLoaded, Networkidle0, and Networkidle2. Set TimeoutExpiration to zero to disable the navigation timeout. A finite renderer deadline still applies to the conversion; the original static converter disables that overall deadline and retains a finite startup budget.

var options = NavigationOptions.WaitUntil(WaitUntil.DOMContentLoaded);
options.TimeoutExpiration = 15_000;

Deployment notes

• Supply an installed Chromium-compatible executable through BrowserExecutablePath. Browser downloading is disabled by default; AllowBrowserDownload enables it explicitly.
• Reuse HtmlToPdfRenderer across jobs. One browser serves isolated contexts; MaxConcurrency defaults to four and additional jobs queue.
• The new renderer's default 30-second RenderTimeout covers queueing, startup, loading, font readiness and printing. Timeout.InfiniteTimeSpan disables the overall deadline. The separate BrowserStartupTimeout defaults to 30 seconds and must remain finite. Expiry throws TimeoutException; caller cancellation throws OperationCanceledException. Context creation and cleanup must finish; browser startup or downloading can remain renderer-owned after a caller stops waiting, within the separate startup budget. Disposal cancels browser provisioning. The deadline is not an OS-enforced hard worker bound.
• Options are copied at construction. The caller disposes the renderer and returned streams. New defaults use print media, background printing and CSS page sizes; customize PdfOptions for paper, margins, headers or page ranges.
• Original static Converter.ToPdfAsync(...) overloads retain automatic browser downloading, screen media and default PuppeteerSharp print settings. They disable the overall deadline to preserve explicit navigation timeouts, including zero; the browser startup budget remains finite. The overload taking HtmlToPdfOptions uses explicit settings for one job.
• Offline emulates offline page networking. Embed fonts and images as data URLs. It is not a network sandbox or security guarantee. Accept trusted HTML and scripts; isolated contexts do not replace OS process isolation.
• Install the browser, OS libraries and fonts with the deployment. The renderer does not disable Chromium's sandbox by default.

GenerateInvoices includes a paginated invoice template, embedded fonts and a Linux container recipe. It exercises 0, 1, 40 and 500 rows, repeated table headers and totals. Validate the recipe in the target Linux image.

Next step

For model-driven HTML, see How to create a PDF from a Liquid HTML template in C#.