McAPI - HTML to PDF Converter API with C#

C# sample code to convert websites and plain HTML to a PDF document with the McAPI HTML to PDF Converter REST API service. We provide a simple VS console app (VisualStudio 2019 or newer) that you can use for testing, download. The sample uses C# with .NET 5 but older .NET runtimes should work too. To parse the returned JSON, the sample project uses Newtonsoft Json which can be installed via the NuGet package manager. The console app targets for Windows 10 but the C# code will compile and run on ASP .NET servers as well.

Requirements: A free RapidAPI account. Replace YOUR_API_KEY in the code below with your RapidAPI key.

All samples below work with the free tier of the API, see the McAPI HTML to PDF API Listing for available plans.

See the overview page for a reference that lists all available parameters and error codes.

Convert invoices, package lists, delivery notes and other business documents from HTML to PDF with Swift

In the first Swift snippet we'll convert this invoice from HTML to PDF, a common application of HTML to PDF conversion. All parameters relevant for the actual screenhot capture are in the payload-string which is added as content to the request. The payload-string is formatted as a C# verbatim string for readability.

We set the paper size to "A4" and the storeExternal parameter to "true"; the PDF will then be stored on McAPI cloud servers and the API returns a downloadable URL (If you plan to store the returned URLs, keep in mind that server-stored PDFs are deleted after 30 days.)

The source code:

// C#

using Newtonsoft.Json;
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace McAPI
{
    public class Result
    {
        public string service { get; set; }
        public string version { get; set; }
        public string pdf { get; set; }
    }

    class Program
    {
        static async Task Main(string[] args)
        {
            string payload = @"
            { 
                ""url"": ""https://mcapi.io/html2pdf/templates/invoice.html"",
                ""format"": ""A4"",
                ""storeExternal"": ""true"",
            }";

            using (var client = new HttpClient())
            {
                var request = new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri("https://mcapi-html-2-pdf.p.rapidapi.com/"),
                    Headers =
                    {
                        { "x-rapidapi-key", "YOUR_API_KEY" },
                        { "x-rapidapi-host", "mcapi-html-2-pdf.p.rapidapi.com" },
                    },
                    Content = new StringContent(payload)
                    {
                        Headers =
                        {
                            ContentType = new MediaTypeHeaderValue("application/json")
                        }
                    }
                };

                using (var response = await client.SendAsync(request))
                {
                    response.EnsureSuccessStatusCode();
                    var body = await response.Content.ReadAsStringAsync();
                    ...
                }
            }
        }
    }
}

The PDF's URL will be delivered as part of a JSON object in body, see further below for sample code that shows how to parse the JSON with C#:

{
  "service": "McAPI HTML 2 PDF, https://mcapi.io",
  "version": "V1",
  "pdf": "https://...pdf"
}

McAPI HTML to PDF API - Converted HTML Invoice as PDF with C#

Here's the created PDF from the C# program. Just like the HTML source the generated PDF is mostly text (except for the ACME-logo) and as such it is fully indexable and searchable:

Image of Converted HTML Invoice to PDF in C#

Specifying page formats

The HTML to PDF Converter API comes with a built-in list of standard paper formats like "Letter" or "A4". To get a list of all formats use the listFormats option, like so:

// C#
  
...

string payload = @"
{ 
    ""listFormats"": ""true"",
}";

...

When this option is set, the API ignores all other options and will instead return an array of all predefined page sizes, shown here as JSON source:

{
  formats: ["Letter", "Legal", "Tabloid", "Ledger", "A0", "A2", "A3", "A4", "A5", "A6"]
}

Selecting one of the predefined formats is simple, just use its name in the call (Note that all parameters and options are case sensitive with the HTML to PDF API):

// C#
  
...

string payload = @"
{ 
    ""url"": ""https://mcapi.io/html2pdf/templates/invoice.html"",
    ""format"": ""Letter"",
    ""storeExternal"": ""true"",
}";

...

Convert a HTML string to PDF with C#

All previous examples sent URLs for conversion to the API. You can also add HTML code directly to your call to the API with the html option. We first load the HTML code from a file and then escape the HTML data with JsonConvert so that we can put it safely into a JSON string.

A basic example without error handling etc.:

// C#

...

var data = File.ReadAllText("invoice.html");
var html = JsonConvert.ToString(data);

... 

Then we set the parameters like so:

// C#

...

string payload = @"
{ 
    ""html"": " + html + @",
    ""format"": ""A4"",
    ""storeExternal"": ""true"",
}";

...

The rest of the call to the API remains unchanged. The API will now render the HTML string into a PDF and return it to the caller.

Note that relative references or links in the HTML string will not resolve. Example for an image that will not be loaded:

<img src="../templates/logo.png"/>

All references and links in the provided HTML code must be absolute and point to valid web locations, here's an example:

<img src="https://mcapi.io/html2pdf/templates/logo.png"/>

Make sure to see the section in the API overview for discussion.

With your call you can also add some HTML to define header and footer sections for the PDF. Those sections can display page number, print date and other static and dynamic data. The API overview has more on this and provides some sample HTML.

Cookie consent banners and ad blocking with C#

If so configured, the API can auto-click the "Accept", "Accept all" (or a similarly worded) button on European DSGVO / GDPR cookie consent banners (Note that this feature is currently experimental, see discussion.)

Consider the website of CNBC which we convert to a PDF with this C# payload string:

// C#
  
...

string payload = @"
{ 
    ""url"": ""https://cnbc.com"",
    ""format"": ""Letter"",
    ""storeExternal"": ""true"",
    ""background"": ""true"",
    ""orientation"": 1,
}";

...

Screenshot from the captured PDF (link to PDF), note the dominant cookie consent banner which covers half the page:

C# ASP .NET Website HTML to PDF Conversion with Cookie Banner

Set the cookie option in the parameters array to "true" to capture the site without the banner:

// C#
  
...

string payload = @"
{ 
    ""url"": ""https://cnbc.com"",
    ""format"": ""Letter"",
    ""storeExternal"": ""true"",
    ""background"": ""true"",
    ""orientation"": 1,
    ""cookie"": ""true""
}";

...

The CNBC site without the banner. Instead it displays some ads (link to PDF):

C# ASP .NET Website HTML to PDF Conversion with Ad.png

Blocking ads on a website before conversion to a PDF with C#

In most cases you'll prefer your PDFs without any ads whatsoever (although there are use cases where you want to capture a site including ads). The API features a very capable blocker, put it to use with the adblock option:

// C#
  
...

string payload = @"
{ 
    ""url"": ""https://cnbc.com"",
    ""format"": ""Letter"",
    ""storeExternal"": ""true"",
    ""background"": ""true"",
    ""orientation"": 1,
    ""cookie"": ""true"",
    ""adblock"": ""true""
}";

...

The site without cookie banner and without ads (link to PDF):

C# ASP .NET Website HTML to PDF Conversion no Cookies no Ads

For the conversion of the CNBC site we had set the orientation to "1" for landscape (default is "0", portrait) and the background param to "true". This is a useful option for converting websites to a PDF because they frequently have inverted text (i.e. light text on dark background) and similar styling.

Here's the CNBC site with background set to "false". The site's design features lots of white text against a blue or black background which is now no longer visible against the white background of the page:

C# ASP .NET Website HTML to PDF Conversion Transparent Background

As a rule of thumb, set the background option to "false" for conversion of documents like invoices, package lists, time sheets, set it to "true" when converting web pages or sites to a PDF.

The header-parameter - writing PDFs to a file with C#

With the storeExternal option set to "false", the PDF is returned immediately as a base64 encoded string rather than being stored in the cloud. Per default, this string has a MIME prefix (or header) that describes the media type of the encoded content.

Sample payload string:

// C#

...

string payload = @"
{ 
    ""url"": ""https://mcapi.io/html2pdf/templates/invoice.html"",
    ""format"": ""A4"",
    ""storeExternal"": ""false""
}";

...

The returned response with the MIME prefix at the beginning of the PDF string:

{
  "service": "McAPI HTML 2 PDF, https://mcapi.io",
  "version": "V1",
  "pdf": "data:application/pdf;base64,JVBERi0 ... JUVPRg=="
}

To parse the JSON string, we set up an auxiliary class, Result, that declares the fields that the API returns. After decoding you can then directly set the "pdf"-string as the data property of an HTML object tag.

This is particularly useful if you want to inject PDFs into a web page, like in this example:

// C#

...

public class Result
{
    public string service { get; set; }
    public string version { get; set; }
    public string pdf { get; set; }
}

...

using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();

    // In production code you would wrap the Json parser in try / catch blocks
    var pdf = JsonConvert.DeserializeObject<Result>(body).pdf;
    var object = "<object data=\"" + pdf + "\"/>";
    Console.WriteLine(object);
}

...

The included MIME prefix will make sure that browser will interpret the PDF data correctly (Note that not all browsers support the embedding of PDF files with the object tag.)

However, when writing the PDF data to a file, including the prefix would result in an invalid PDF document as the header is not part of the PDF file format. To have the API convert your HTML content to a PDF without the prefix, set the header-parameter to "false", like so:

// C#

...

string payload = @"
{ 
    ""url"": ""https://mcapi.io/html2pdf/templates/invoice.html"",
    ""format"": ""A4"",
    ""storeExternal"": ""false"",
    ""header"": ""false""
}";

...

The API will now return the PDF data without the MIME header:

{
  "service": "McAPI HTML 2 PDF, https://mcapi.io",
  "version": "V1",
  "pdf": "JVBERi0 ... JUVPRg=="
}

All that is left now is decoding the base64 string to get the binary PDF data and then write this data to a file. Shown here as a complete and executable C# command-line application (this is essentially the contents of the VS console app from the introduction):

// C#

using Newtonsoft.Json;
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace McAPI
{
    public class Result
    {
        public string service { get; set; }
        public string version { get; set; }
        public string pdf { get; set; }
    }

    class Program
    {
        static async Task Main(string[] args)
        {
            string payload = @"
            { 
                ""url"": ""https://mcapi.io/html2pdf/templates/invoice.html"",
                ""format"": ""A4"",
                ""storeExternal"": ""false"",
                ""header"": ""false""
            }";

            using (var client = new HttpClient())
            {
                var request = new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri("https://mcapi-html-2-pdf.p.rapidapi.com/"),
                    Headers =
                    {
                        { "x-rapidapi-key", "YOUR_API_KEY" },
                        { "x-rapidapi-host", "mcapi-html-2-pdf.p.rapidapi.com" },
                    },
                    Content = new StringContent(payload)
                    {
                        Headers =
                        {
                            ContentType = new MediaTypeHeaderValue("application/json")
                        }
                    }
                };

                using (var response = await client.SendAsync(request))
                {
                    response.EnsureSuccessStatusCode();
                    var body = await response.Content.ReadAsStringAsync();

                    // In production code you would wrap the Json parser in try / catch blocks

                    var pdf = JsonConvert.DeserializeObject<Result>(body).pdf;
                    var pdfData = Convert.FromBase64String(pdf);
                    var desktop = Environment.GetFolderPath(Environment.SpecialFolder.Desktop);
                    var path = Path.Combine(desktop, "invoice.pdf");
                    File.WriteAllBytes(path, pdfData);
                }
            }
        }
    }
}

Back to McAPI HTML to PDF API main page.