HtmlToPdf.AspNetCore 1.0.1

HtmlToPdf.AspNetCore

A fast, accurate HTML to PDF conversion library for .NET with perfect RTL (Right-to-Left) language support. Built on Chromium for pixel-perfect rendering with full Arabic, Urdu, Persian, and Hebrew text support.

✨ Features

• 🌍 Perfect RTL Support - Native support for Arabic, Urdu, Persian, Hebrew and other RTL languages
• ⚡ Fast Performance - Optimized for high-throughput PDF generation
• 🎯 Pixel-Perfect Rendering - Chromium-based rendering with full CSS3, JavaScript, and web font support
• 🔧 Simple API - Easy to use with just one line of code
• 🚀 Automatic Browser Management - Auto-downloads Chromium if not installed
• 📱 Cross-Platform - Works on Windows, Linux, and macOS
• 🔒 Thread-Safe - Safe for concurrent use in web applications

📦 Installation

dotnet add package HtmlToPdf

Or via Package Manager:

Install-Package HtmlToPdf

🚀 Quick Start

Basic Usage

using HtmlToPdf;

// Simple PDF generation
var html = "<h1>Hello World</h1><p>This is a simple PDF document.</p>";
byte[] pdf = HtmlToPdfConverter.Render(html);
File.WriteAllBytes("output.pdf", pdf);

ASP.NET Core Controller Example

using HtmlToPdf;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/pdf")]
public class PdfController : ControllerBase
{
    [HttpPost]
    public IActionResult GeneratePdf([FromBody] string html)
    {
        byte[] pdfBytes = HtmlToPdfConverter.Render(html);
        return File(pdfBytes, "application/pdf", "document.pdf");
    }
}

🌍 RTL Language Support

Arabic Example

var arabicHtml = @"
<div dir='rtl' style='font-family: Arial, sans-serif; text-align: right;'>
    <h1>التقرير الشهري</h1>
    <p>هذا تقرير يحتوي على نص باللغة العربية مع دعم كامل للتشكيل والاتجاه من اليمين لليسار.</p>
</div>";

byte[] arabicPdf = HtmlToPdfConverter.Render(arabicHtml, new PdfOptions
{
    Language = PdfLanguage.Arabic,
    MarginMm = 20
});

Urdu Example

var urduHtml = @"
<div dir='rtl' style='font-family: Jameel Noori Nastaleeq;'>
    <h1>رپورٹ</h1>
    <p>یہ اردو زبان میں لکھی گئی ایک رپورٹ ہے جو کامل طور پر دائیں سے بائیں کی طرف چلتی ہے۔</p>
</div>";

byte[] urduPdf = HtmlToPdfConverter.Render(urduHtml, new PdfOptions
{
    Language = PdfLanguage.Urdu,
    PageSize = PageSize.A5
});

⚙️ Configuration Options

PdfOptions Class

var options = new PdfOptions
{
    // Page settings
    PageSize = PageSize.A4,        // A4, Letter, Legal, A3, A5
    Landscape = false,             // Portrait or Landscape
    MarginMm = 15,                 // Margin in millimeters
    
    // Language and rendering
    Language = PdfLanguage.Auto,   // Auto-detect or specify: Arabic, Urdu, English
    Scale = 1.0f,                  // Scale factor (0.5 = 50%, 2.0 = 200%)
    PrintBackground = true,        // Include background colors and images
    
    // Performance
    TimeoutMs = 7000               // JavaScript execution timeout
};

Custom Page Sizes

// Custom page size with specific dimensions
var customOptions = new PdfOptions
{
    PageSize = PageSize.A4,
    Landscape = true,      // Landscape orientation
    MarginMm = 10,         // Minimal margins
    Scale = 0.8f           // 80% scale
};

🔧 Advanced Usage

Pre-warm for Faster First Response

// Call this during application startup
HtmlToPdfConverter.Warmup();

Manual Shutdown (Optional)

// Call this when application is shutting down
HtmlToPdfConverter.Shutdown();

Handling Large HTML Content

public byte[] GenerateComplexReport(string htmlContent)
{
    try
    {
        var options = new PdfOptions
        {
            TimeoutMs = 15000,      // 15 seconds for complex pages
            PrintBackground = true,
            Scale = 1.0f
        };
        
        return HtmlToPdfConverter.Render(htmlContent, options);
    }
    catch (HtmlToPdfException ex)
    {
        // Handle conversion errors
        Console.WriteLine($"PDF generation failed: {ex.Message}");
        throw;
    }
}

📋 Requirements

Runtime Requirements

• .NET 8.0 or later
• One of the following browsers (automatically detected and used):
  • Google Chrome
  • Microsoft Edge
  • Chromium

Automatic Browser Installation

If no browser is detected, the library will automatically download and cache Chromium on first use. This requires:

• Internet access on first run
• ~200MB disk space for Chromium

🎯 Performance Tips

1. Use Warmup: Call HtmlToPdfConverter.Warmup() during application startup for faster first response
2. Cache Results: Cache generated PDFs for identical HTML content
3. Optimize HTML: Minimize external resources and use inline styles when possible
4. Adjust Timeout: Increase TimeoutMs for pages with complex JavaScript

🔒 Error Handling

try
{
    byte[] pdf = HtmlToPdfConverter.Render(html);
}
catch (HtmlToPdfException ex)
{
    // Handle conversion-specific errors
    Console.WriteLine($"PDF generation failed: {ex.Message}");
}
catch (Exception ex)
{
    // Handle other errors
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

🐛 Troubleshooting

Common Issues

1. "Browser not found" error

   • Ensure Chrome, Edge, or Chromium is installed
   • OR allow internet access for automatic download
   • Check firewall settings if download fails

2. Slow performance on first run

   • Call HtmlToPdfConverter.Warmup() during application startup
   • The first run includes browser initialization

3. RTL text not rendering correctly

   • Ensure proper dir='rtl' attribute in HTML
   • Use appropriate font-family for the language
   • Specify Language in PdfOptions when needed

Made with ❤️ by Muammar Siddiqui