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 (x86 windows build) in the separate process with System.Diagnostics.Process and your project environment/platform should allow that.

WkHtmlToPdf is based on QtWebKit 4.8 (rather old version released in 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 starting new processes is prohibited (shared ASP.NET hostings)
• Windows Servers with restricted access to GDI API: "shared" Azure Apps is NOT supported.
  Azure Apps with VM-based subscription plan (Basic, Standard, Premium) can use NReco.PdfGenerator, but customs fonts are not loaded (it is possible to use only standard Windows fonts like Arial, Times New Roman etc).
• .NET platforms where System.Diagnostics.Process API is not available (like UWP/Univeral Apps)

PdfGenerator works fine on usual Azure VM instances (Web Role, Worker Role) and Azure Functions (Windows).
Legacy .NET Framework 4.x is supported.

.NET Core / NET6 apps
NReco.PdfGenerator.LT nuget package includes netstandard20 build and fully compatible with .NET Core 2.x & 3.x apps.
Note: you need to deploy wkhtmltopdf binaries for your target platform(s) (Windows, Linux or OS X) with your .NET Core app.

Legacy windows versions (XP/2003 Server)
NReco.PdfGenerator nuget package embeds windows build of wkhtmltopdf.exe (MSVC 2015) and it can work only on Windows Vista/2008 R2 or newer.
For older Windows versions NReco.PdfGenerator.LT should be used with MinGW-build of wkhtmltopdf.

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 ";

PdfGenerator can be used for converting Word documents (docx, Word 2007+) to PDF in the following way:

• convert docx (OpenXML) to HTML using OpenXmlPowerTools library (open source). It correctly handles embedded images, styles, tables etc.
• convert intermediate HTML file to PDF with PdfGenerator

This approach is illustrated by Word-To-Pdf C# example (included into commercial package).

There are 2 ways how ASPX page can be exported to PDF:

1. use GeneratePdfFromFile method and specify absolute URL to ASPX page as input file path (simplest solution if ASPX page is doesn't require authentication).
2. Override System.Web.UI.Page.Render method in the following way:

   protected override void Render(HtmlTextWriter writer) {
    if (Request["export"]=="pdf") {
     var strWr = new StringWriter();
     var htmlWr = new HtmlTextWriter(strWr); 		
     base.Render(htmlWr);
     var htmlToPdf = new HtmlToPdfConverter();
     Response.ContentType = "application/pdf";
     htmlToPdf.GeneratePdf(strWr.ToString(), null, Response.OutputStream);
     Response.End();
    }
   }

   As result you can download PDF version of the ASPX page by adding "?export=pdf" query parameter.

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).