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 hosting environment/platform should allow that.

WkHtmlToPdf is based on QtWebKit 4.8 (rather old version from 2011) so it doesn't support modern CSS3 features (like flex/grid layout).

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).
• AWS Lambda is supported via NReco.PdfGenerator.LT nuget + this special wkhtmltopdf deployment.

Legacy .NET Framework 4.5+ apps are fully supported.

.NET Core/ 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) another nuget NReco.PdfGenerator.LT should be used instead (API is 100% the same). Since this version doesn't include wkhtmltopdf binaries you need to deploy wkhtmltopdf for 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).

NReco.PdfGenerator is a .NET wrapper for wkhtmltopdf and this means that wkhtmltopdf (a command line tool) should be deployed on your hosting environment. When your .NET app is hosted inside Docker container (Debian-based Linux) to deploy wkhtmltopdf the following commands should be added into your image's 'Dockerfile':

RUN apt-get update && apt-get install -y --no-install-recommends wget ca-certificates fontconfig libc6 libfreetype6 libjpeg62-turbo libpng16-16 libssl1.1 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-2/wkhtmltox_0.12.6.1-2.bullseye_amd64.deb
RUN dpkg -i wkhtmltox_0.12.6.1-2.bullseye_amd64.deb

Do NOT install wkhtmltopdf via apt-get install -y wkhtmltopdf because most likely you'll install legacy (old) version and possibly 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 sed -i'.bak' 's/$/ contrib/' /etc/apt/sources.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