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) in the following cases:

• partial-trust environments where your .NET app cannot start new processes using System.Diagnostics.Process API (most shared ASP.NET hostings, UWP/Univeral Apps, mobile apps)
• Windows Servers with restricted access to GDI API: "shared" Azure Apps is NOT supported.
  Azure Apps with a VM-based subscription plan (Basic, Standard, Premium) can use NReco.PdfGenerator, but customs fonts cannot be loaded because of this hosting environment technical limitations (it is possible to use only standard Windows fonts like Arial, Times New Roman etc).

PdfGenerator works fine on 'normal' Azure VM instances and Azure Functions (Windows).
Legacy .NET Framework 4.5+ apps are fully supported.

.NET Core/ NET6/NET7 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 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).