Overview

Puppeteer Sharp is a .NET port of the popular headless Chrome Node.js library, Puppeteer, which provides a high-level API over the Chrome DevTools Protocol. This library empowers developers to programmatically control headless Chrome or Chromium browsers, allowing for automated tasks such as web scraping, UI testing, and, importantly, HTML to PDF conversion. The ability to convert HTML to PDF is vital in many applications, particularly for generating reports, invoices, and documentation that require precise layouts and formatting.

In real-world scenarios, businesses often need to convert web pages into PDF documents for various reasons, such as archiving, sharing, or printing. For example, an e-commerce platform may require generating PDF invoices for customers after purchase, or a reporting tool might need to produce downloadable reports based on user queries. Puppeteer Sharp facilitates this process by providing an easy-to-use interface to manipulate and render HTML content accurately in a PDF format.

Prerequisites

• ASP.NET Core: Familiarity with ASP.NET Core framework and basic web application development.
• C#: Understanding of C# programming language, including async/await patterns.
• Puppeteer Sharp: Basic knowledge of Puppeteer Sharp's installation and setup.
• HTML/CSS: Understanding of HTML and CSS for rendering pages correctly in PDF.

Setting Up Puppeteer Sharp in ASP.NET Core

To use Puppeteer Sharp, the first step is to install the library in your ASP.NET Core project. This can be done easily via NuGet Package Manager. Puppeteer Sharp not only allows you to convert HTML to PDF but also requires the installation of the Chromium browser that it uses under the hood for rendering.

dotnet add package PuppeteerSharp

This command will download and install Puppeteer Sharp along with its dependencies. It is essential to ensure that the Chromium browser is also downloaded, which can be done programmatically in your application.

public class Startup
 {
     public void ConfigureServices(IServiceCollection services)
     {
         services.AddRazorPages();
         Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
     }
     public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
     {
         if (env.IsDevelopment())
         {
             app.UseDeveloperExceptionPage();
         }
         else
         {
             app.UseExceptionHandler("/Error");
             app.UseHsts();
         }
         app.UseHttpsRedirection();
         app.UseStaticFiles();
         app.UseRouting();
         app.UseAuthorization();
         app.UseEndpoints(endpoints =>
         {
             endpoints.MapRazorPages();
         });
     }
 }

In this code snippet, the Startup class is configured to launch Puppeteer when the application starts. The Puppeteer.LaunchAsync method is called with options to run Chromium in headless mode, which is ideal for server environments where a graphical interface is unavailable.

Downloading Chromium

Prior to using Puppeteer, it is necessary to download the Chromium browser. This can be accomplished with the following code snippet:

public async Task DownloadChromiumAsync()
 {
     await new BrowserFetcher().DownloadAsync(BrowserFetcher.DefaultChromiumRevision);
 }

The BrowserFetcher class is responsible for managing the downloading of the Chromium binary. By calling the DownloadAsync method, you ensure that the necessary browser is available for Puppeteer to use when converting HTML to PDF.

HTML to PDF Conversion

Once Puppeteer is set up and the Chromium browser is downloaded, you can proceed to convert HTML content into PDF files. This process involves launching the browser, creating a page, setting its content, and then generating the PDF. Below is a complete example demonstrating this process.

public async Task GeneratePdf()
 {
     await DownloadChromiumAsync();
     await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
     await using var page = await browser.NewPageAsync();
     await page.SetContentAsync("
Hello, World!
This is a sample PDF document generated using Puppeteer Sharp.
");
     var pdfBytes = await page.PdfAsync(new PdfOptions { Format = PaperFormat.A4 });
     return File(pdfBytes, "application/pdf", "sample.pdf");
 }

This method, GeneratePdf, is an asynchronous action method that performs the following steps:

1. DownloadChromiumAsync: Ensures the Chromium browser is downloaded.
2. Puppeteer.LaunchAsync: Launches a new instance of the Chromium browser in headless mode.
3. NewPageAsync: Creates a new page in the browser.
4. SetContentAsync: Sets the HTML content of the page.
5. PdfAsync: Generates the PDF and returns it as a byte array.
6. File: Returns the PDF file as a downloadable response.

Customizing PDF Options

Puppeteer Sharp allows for customization of the PDF output through various options. You can specify margins, page size, and more. Here is an example that demonstrates how to set margins and orientation:

var pdfOptions = new PdfOptions
 {
     Format = PaperFormat.A4,
     MarginOptions = new MarginOptions
     {
         Top = "20mm",
         Bottom = "20mm",
         Right = "10mm",
         Left = "10mm"
     },
     PrintBackground = true,
     Landscape = true
 };
 var pdfBytes = await page.PdfAsync(pdfOptions);

In this example, the PdfOptions class is utilized to set the desired margins and orientation of the PDF document. The PrintBackground option is set to true to ensure that background colors and images are included in the PDF rendering.

Handling Edge Cases & Gotchas

While using Puppeteer Sharp, developers may encounter various pitfalls. Here are some common edge cases and their solutions:

Incorrect Rendering of CSS Styles

One common issue is when CSS styles do not render correctly in the generated PDF. This can occur if the CSS is not fully loaded before the PDF generation starts. To mitigate this, ensure that all resources are properly loaded by waiting for the network to be idle:

await page.SetContentAsync(htmlContent, new NavigationOptions { WaitUntil = new[] { WaitUntilNavigation.Networkidle0 } });

Using WaitUntilNavigation.Networkidle0 ensures that the PDF generation process waits until there are no more than 0 network connections for at least 500 ms, allowing all stylesheets and resources to load completely.

Large HTML Content

When converting large HTML content, you may run into performance issues or timeouts. To handle this, consider increasing the timeout settings:

var pdfOptions = new PdfOptions
 {
     Timeout = 60000 // 60 seconds
 };

This adjustment increases the timeout for PDF generation, accommodating larger documents that may take longer to process.

Performance & Best Practices

To optimize the performance of HTML to PDF conversion using Puppeteer Sharp, consider the following best practices:

Use Headless Mode

Always run Puppeteer in headless mode for production environments to reduce overhead and improve performance. Headless mode requires fewer resources and is typically faster than running with a visible UI.

Optimize HTML Content

Minimize the size of the HTML content being converted. Use simple layouts and avoid excessive images or external resources that slow down rendering. Compress images and combine CSS files to reduce load times.

Batch PDF Generation

If your application needs to generate multiple PDF files, consider batching the generation process. This can reduce the overhead associated with launching and closing the browser multiple times. Here’s an example:

public async Task GenerateMultiplePdfs(List htmlContents)
 {
     await DownloadChromiumAsync();
     await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
     var pdfTasks = htmlContents.Select(async html =>
     {
         var page = await browser.NewPageAsync();
         await page.SetContentAsync(html);
         return await page.PdfAsync();
     });
     var pdfBytesList = await Task.WhenAll(pdfTasks);
     // Combine PDF bytes logic here
     return File(combinedPdfBytes, "application/pdf", "combined.pdf");
 }

By launching the browser only once and creating multiple pages, you can significantly reduce the time taken to generate multiple PDFs.

Real-World Scenario: Generating Invoices in ASP.NET Core

Let’s consider a scenario where you need to generate invoices for an e-commerce application. The invoices will be generated as PDF files and sent to customers via email. Below is a complete implementation of how this can be achieved using Puppeteer Sharp.

public class InvoiceService
 {
     public async Task GenerateInvoicePdf(Invoice invoice)
     {
         await DownloadChromiumAsync();
         await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
         await using var page = await browser.NewPageAsync();
         var htmlContent = GenerateInvoiceHtml(invoice);
         await page.SetContentAsync(htmlContent);
         return await page.PdfAsync(new PdfOptions { Format = PaperFormat.A4 });
     }
 
     private string GenerateInvoiceHtml(Invoice invoice)
     {
         return $"
Invoice #{invoice.Id}
Amount: {invoice.Amount}
";
     }
 }

In this implementation, the GenerateInvoicePdf method receives an Invoice object, generates the HTML content using the GenerateInvoiceHtml method, and then converts that HTML into a PDF document. The PDF can then be sent as an email attachment to the customer.

Conclusion

• Puppeteer Sharp is a powerful tool for converting HTML to PDF in ASP.NET Core applications.
• Proper setup and configuration are crucial for ensuring reliable PDF generation.
• Customization options in Puppeteer Sharp allow for control over the PDF output, including margins and page size.
• Handling edge cases is essential for robust applications, especially concerning CSS rendering and large content.
• Performance optimization techniques can significantly improve the efficiency of PDF generation.