HTML-to-PDF Generator for .NET C# WkHtmlToPdf wrapper

PdfGenerator renders web page like a web browser and can load external resources like images, CSS and js files (javascript code is executed just before PDF rendering).

PdfGenerator executes WkHtmlToPdf command line tool in a separate process using System.Diagnostics.Process API and your app's hosting environment/platform should allow that.

WkHtmlToPdf is based on QtWebKit 4.8 so it doesn't support modern CSS3 features (like flex/grid layout, ES2015 etc).

Component cannot be used (does NOT work) if wkhtmltopdf cannot be deployed (installed) and executed via System.Diagnostics.Process API: most shared ASP.NET hostings, UWP/Univeral Apps, mobile apps.

• Azure Apps / Azure Functions (Windows) with a VM-based subscription plan (Basic, Standard, Premium) can use NReco.PdfGenerator with the following limitation: custom fonts cannot be loaded because of this specific hosting environment technical restrictions (it is possible to use only standard Windows fonts like Arial, Times New Roman etc).
  In the case of Azure Functions (Windows) + NReco.PdfGenerator nuget a default location for wkhtmltopdf binaries should be changed in this way:

  htmlToPdf.PdfToolPath = Path.Combine( Path.GetTempPath(), "wkhtmltopdf" );

  Shared Azure Apps plan is NOT supported.
• Azure Apps / Azure Functions (Linux) is supported via NReco.PdfGenerator.LT nuget + containerized Azure Functions deployment. Instructions for docker + wkhtmltopdf deployment are listed below.
• No restrictions when your .NET app that uses NReco.PdfGenerator is hosted on 'normal' Windows or Linux VM (Azure VM instance, AWS EC2 instance etc).
• AWS Lambda is supported via NReco.PdfGenerator.LT nuget + this special wkhtmltopdf deployment.

Legacy .NET Framework 4.5+ apps are fully supported.

NET6/NET8+ apps
Starting from version 1.2.1 it is possible to reference NReco.PdfGenerator nuget in modern .NET apps and get leverages of simplified deployment (no need to deploy wkhtmltopdf separately). This will work only for Windows deployments.
For cross-platform apps (Linux, Mac-OS, Docker images) another nuget NReco.PdfGenerator.LT should be used instead (C# API is the same). This version doesn't include wkhtmltopdf binaries so you need to deploy the latest wkhtmltopdf (builds for modern Linux are here) your target platform(s) with your .NET app separately.

LT build usage
The following C# code snippet illustrates how to initialize LT build:

var htmlToPdfConv = new NReco.PdfGenerator.HtmlToPdfConverter();
htmlToPdfConv.License.SetLicenseKey(
	"your_id", "your_license_key");

// for Linux/OS-X: "wkhtmltopdf"
htmlToPdfConv.WkHtmlToPdfExeName = "wkhtmltopdf.exe";

// specify where wkhtmltopdf binaries are installed/deployed
htmlToPdfConv.PdfToolPath = "<path_to_folder_with_wkhtmltopdf>";
htmlToPdfConv.GeneratePdfFromFile(
	"http://www.google.com", null, "google.pdf");

If you want to test LT nuget package you can contact support and ask for a demo key.

It is possible to specify custom header/footer in the following way:

var htmlToPdf = new NReco.PdfGenerator.HtmlToPdfConverter();
htmlToPdf.PageHeaderHtml = "<div style='text-align:right;'>HEADER <span class='page'></span> of <span class='topage'></span> </div>";

If PDF is produced from several HTML inputs header/footer may be specified individually for each HTML:

htmlToPdf.GeneratePdfFromFiles(
  new [] {
    new WkHtmlInput("https://wkhtmltopdf.org/") {
      PageHeaderHtml = "HEADER 1"
    },
    new WkHtmlInput("https://www.google.com") {
      PageHeaderHtml = "HEADER 2"
    },
  },
  null,
  "multi_header.pdf"
);

Note that this GeneratePdfFromFiles overload can be used only with a license key.

It is possible to render table headers on each PDF page and get correct page breaks with long tables:

• wrap header row(s) with THEAD.
• specify CSS rule page-break-inside:avoid for TR, TH, TD.

Note: wkhtmltopdf still has several open issues related to rendering long tables (for example, if table has cell that take more than one page).

In some cases PDF generation fails with one of the following errors:

• Exit with code 1 due to network error: ContentNotFoundError
• Exit with code 1 due to network error: ProtocolUnknownError
• Exit with code 1 due to network error: HostNotFoundError

This error means that input HTML has external js/css/image URL reference(s) that cannot be loaded by WkHtmlToPdf. In most cases PDF can be generated by specifying additional WkHtmlToPdf parameter:

var htmlToPdf = new HtmlToPdfConverter();
htmlToPdf.CustomWkHtmlArgs = " --load-media-error-handling ignore ";

There are 2 ways how ASP.NET web page can be exported to PDF:

1. use GeneratePdfFromFile method and specify absolute URL to ASP.NET MVC Core page as an input. If this page requires authentication (cookie) it may be specified in this way:

   var authCookieName = "your_app_auth_coookie_name";
   htmlToPdf.CustomWkHtmlArgs = String.Format(" --cookie {0} {1} ", authCookieName, HttpContext.Request.Headers[authCookieName]);

2. Render MVC Core Razor view to string, and then render it to PDF. This approach is illustrated in "DemoMvc" example ( ViewPdfResult.cs).

You can force wkhtmltopdf to use print media type by specifying the following option:

var pdfGen = new HtmlToPdfConverter();
pdfGen.CustomWkHtmlArgs ="  --print-media-type ";

Note that in some cases (esp. when page has complex javascript - for example, that renders dynamic SVG charts) this option may cause wkhtmltopdf crush. As alternative to "--print-media-type" you may use extra CSS file that applied only when PDF is generated.

This is known wkhtmltopdf (Windows) issue when letters are rendered too close to each other (condensed). Usually this effect appears with system-installed fonts (Arial, Times New Roman etc) and small font sizes.

There are 2 known workarounds:

• use custom font (registered with @font-face)
• set custom DPI value with wkhtmltopdf "dpi" option, for example -dpi 300 (values >=200 usually fix letter spacing).

If your table is rendered on 2 (or more) pages you might want to prevent page breaks in the middle of cells. To do that, add these CSS rules:

tr, td, th {
  page-break-inside: avoid !important;
}

Note that this works only for top-most <table>, therefore try to avoid nested tables in your HTML layout.

To repeat table row with headers on each page, it is enough to wrap headers with <thead>.

When you have background color on body if content goes to second page then second page have background color till content, and rest of the page remains white. If you'd like to keep the background color going down to the end of the page add this at the end (just before closing </body>):

<div style="position: fixed;display: block;min-height: 100%;width: 100%;background: #YOUR_BACKGROUND_COLOR;margin: 0;padding: 0;"></div>

NReco.PdfGenerator.LT is a .NET wrapper for wkhtmltopdf and this means that wkhtmltopdf should be included into your app's Docker image.
Normally NET8+ app Linux image is based on mcr.microsoft.com/dotnet/aspnet:8.0 (Debian 12 "bookworm"), to deploy wkhtmltopdf the following commands should be added into the 'Dockerfile':

RUN apt-get update && apt-get install -y --no-install-recommends wget ca-certificates fontconfig libc6 libfreetype6 libjpeg62-turbo libpng16-16 libssl3 libstdc++6 libx11-6 libxcb1 libxext6 libxrender1 xfonts-75dpi xfonts-base zlib1g
RUN wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb
RUN dpkg -i wkhtmltox_0.12.6.1-3.bookworm_amd64.deb

Do NOT install wkhtmltopdf via apt-get install -y wkhtmltopdf because most likely you'll install legacy (old) version and possibly a wrong build (without 'patched' QT).

If you want to use Windows fonts (Arial, Times New Roman, Courier New etc) add these commands into 'Dockerfile':

RUN echo "deb http://deb.debian.org/debian bookworm contrib non-free" > /etc/apt/sources.list.d/contrib.list
RUN echo "ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true" | debconf-set-selections
RUN apt-get update -y && apt-get install -y --no-install-recommends ttf-mscorefonts-installer
RUN fc-cache -f -v

NReco.PdfGenerator, as a .NET wrapper, relies on wkhtmltopdf which uses a rather old version of QtWebKit engine for HTML-to-PDF rendering. This means that modern things like ES2015+ syntax or CSS3 are not supported (including flex/grid). For the number of reasons, it is unlikely that wkhtmltopdf will support flex/grid in the future; however, wkhtmltopdf is still good for various exports / formal documents generation (like orders, invoices etc) where you have control HTML template and can use classic tables / floating divs to get a desired layout.

If you need to generate PDFs from webpages that use flex/grid layout you may consider the following alternatives based on headless Chromium:

• Puppeteer Sharp (how to generate PDF)
• If you can deploy a separate docker container for PDF generation, Gotenberg is what you need (+ C# client).