Convert HTML to PDF in C# and VB.NET

If a lot of your time and money already spent on creating content in HTML form, you might want to create PDFs from that HTML. Such an approach is a natural direction for everyone, who wants to avoid duplicate work.

For successful reuse of investments, the conversion should be performed programmatically and the resulting PDF should be as close visually to the source HTML as possible.

HTML to PDF conversion

API for HTML to PDF conversion in .NET applications

Free HTML to PDF add-on for Docotic.Pdf library provides an API for such conversions. Both the add-on and the library can be used from web and desktop applications built for .NET and .NET Core frameworks.

Docotic.Pdf library 9.4.17444-dev HTML to PDF add-on 9.4.17444-dev
Regression tests 14,746 passed Total NuGet downloads 4,394,692

The add-on is an HTML to PDF .NET library that uses Chromium during conversion. Before each conversion, the add-on automatically checks if the most recent supported Chromium is already downloaded. Any already downloaded eligible version will be reused. If no eligible version is found, the add-on downloads one before the conversion. It is expected to have the same web standards compliance as in Google Chrome (R).

The add-on can generate PDF from HTML in Windows, macOS, and Linux environments. Read how to configure the add-on in Linux in the article about HTML to PDF conversion in Azure.

The add-on is available on NuGet, and it is also included in the zip with binaries of the library. To try the library without evaluation mode restrictions, you may get the free time-limited license key here.

Simple HTML to PDF C# conversion

Using the HTML to PDF API, the C# conversion code can look like this:

static async Task convertUrlToPdfAsync(string urlString, string pdfFileName)
    using (var converter = await HtmlConverter.CreateAsync())
        using (var pdf = await converter.CreatePdfAsync(new Uri(urlString)))

It is rather simple. Only two calls are required to produce a PDF document. As you can see, the API is asynchronous and does not provide synchronous methods at all.

In cases when you would like to call the API from some synchronous code, you can use the following wrapper:

Task.Run(async () =>
    await convertUrlToPdfAsync("", "output.pdf");

Please note that in general it is not recommended to call async methods synchronously, so use the wrapper only when you have no other choice.

We provide sample code that shows how to use the API from both synchronous and asynchronous console applications. Also, there are sample codes for Windows Forms and WPF applications.

There is also the HTML to PDF group of samples. Each sample comes in C# and VB.NET version.

Create a PDF with an HTML string or file in C# and VB.NET

It's easy to convert an HTML string to PDF with the API. The string can contain a complete HTML document or just a fragment. The converter will create a PDF from the HTML code for you.

var html = "<body><br/><br/><br/><h1>Hello, World<h1></body>";
using (var pdf = await converter.CreatePdfFromStringAsync(html))

You can specify a base URL for all the relative links in the HTML code you are going to convert. Here is a code snippet for how to convert HTML to PDF with a base URL in C#.

var incompleteHtml = "<img src=\"/images/team.svg\"></img>";
var options = new HtmlConversionOptions();
options.Load.BaseUri = new Uri("");
using (var pdf = await converter.CreatePdfFromStringAsync(incompleteHtml, options))

Converting an HTML file is almost the same as converting an URL. Just use the CreatePdfAsync overload that accepts a path instead of an URL. The base URL and other options are also supported when converting an HTML file to PDF in C# or VB.NET code.

var sampleHtmlPath = @"C:\path\to\sample.html";
using (var pdf = await converter.CreatePdfAsync(sampleHtmlPath))

You can also convert SVG images to PDF using the API.

Use custom page size, margins, and scale

You can set up any HTML to PDF C# conversion by providing conversion options to PDF creating methods.

Here is a code snippet that shows how to configure the output page size, margins, and scale in C#:

using (var converter = await HtmlConverter.CreateAsync())
    var options = new HtmlConversionOptions();

    // you can also specify if the page orientation should be landscape
    // and you can provide a size in points or inches

    options.Page.MarginLeft = 10;
    options.Page.MarginTop = 20;
    options.Page.MarginRight = 30;
    options.Page.MarginBottom = 40;

    options.Page.Scale = 1.5;

    using (var pdf = await converter.CreatePdfAsync(url, options))

You can specify header and footer templates using page options. The templates use regular HTML code with support for a few variables. These variables are date, title, url, pageNumber and totalPages. Header templates and footer templates support the same set of variables.

It is recommended to use inline styles and Data URIs for images.

You might want to specify top and bottom margins for the page. Without margins, the header or the footer may be obscured by the page contents.

The Convert HTML to PDF with header and footer in C# or VB.NET sample code shows how to use the variables and Data URIs in the templates.

Password-protected HTML to PDF C# conversion

You can create PDF even if an HTML page is protected by a username/password pair. It's as easy as setting the authentication options inside the HtmlConversionOptions.

var options = new HtmlConversionOptions();
options.Authentication.SetCredentials("foo", "bar");

using (var pdf = await converter.CreatePdfAsync(url, options))

It is also easy if the page needs some cookies set to function properly. Just add those cookies to the options. Here is how:

var options = new HtmlConversionOptions();
options.Cookies.Add(new Cookie("sessionID", "my-session-ID"));

using (var pdf = await converter.CreatePdfAsync(url, options))

Delay conversion start

By default, the conversion starts immediately after loading. But there are cases when the page needs some time to settle. For example, when it performs some calculations and updates the contents after those calculations are ready.

Using the conversion start options you can delay the conversion for a specified number of milliseconds.

// Wait for 10 seconds before starting the conversion.
var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);

Sometimes it is required to run a script to toggle elements on the loaded page, or to make dynamic content loading happen. This is also possible:

var options = new HtmlConversionOptions();
var js = @"
    async function scrollDownUntilYouCantAnyMore() {
        await new Promise((resolve, reject) => {
            // omitted for brevity
            }, 400);
using (var pdf = await converter.CreatePdfAsync(url, options))

The HTML to PDF after a script run in C# or VB.NET sample code contains the full scrollDownUntilYouCantAnyMore function. The sample shows how to execute a script before HTML to PDF conversions.

Convert HTML to PDF in .NET ignoring SSL errors

During a conversion, an SSL error can happen. Such errors usually happen because of self-signed or otherwise untrusted certificates. Revoked and expired certificates can cause the HTML to PDF converter to throw exceptions, too.

You can ignore SSL errors if you understand why they happen and you are sure it is safe to ignore them. To ignore SSL errors during an HTML to PDF conversion, use the engine options with IgnoreSslErrors = true.

var engineOptions = new HtmlEngineOptions
    IgnoreSslErrors = true
using (var converter = await HtmlConverter.CreateAsync(engineOptions))
    var url = new Uri("");
    using (var pdf = await converter.CreatePdfAsync(url))

Put HTML content over PDF pages

There are cases when you might need to convert HTML and put the conversion result on top of some existing PDF pages. For example, when you have a picture of a form, you might want to put something over empty areas in that picture. The result will look like a filled form.

To put converted HTML over existing PDF content, you will need to:

  • create PDF pages with transparent background from the HTML
  • create XObjects from the converted pages
  • draw those XObjects on existing PDF pages.

The Convert HTML and put it over existing PDF content in C# or VB.NET sample code shows all the steps. Please take a look at the sample.