HTML do PDF w C# — Rzeczywistość opcji bibliotek

Owijaczewkhtmltopdf— ekosystem błędów ładowania DLL

Najczęściej wyszukiwane zapytanie przyciągające programistów do tych artykułów to jakaś wariacja:

System.DllNotFoundException: Nie można załadować DLL 'libwkhtmltox'

Warianty specyficzne dla platformy obejmują:

Nie można załadować biblioteki współdzielonej 'wkhtmltox' lub jednej z jej zależności
    (Linux — libwkhtmltox.so not found)

Nie można odnaleźć określonego modułu. (0x8007007E)
    (Windows — wkhtmltox.dll path not configured)

dyld: Biblioteka nie załadowana: libwkhtmltox.dylib
    (macOS — not supported on ARM64/Apple Silicon)

Te błędy pochodzą z DinkToPdf, NReco.PdfGenerator, WkHtmlToXSharp i innych owijaczy C# wokół tej samej porzuconej binarki. Organizacjawkhtmltopdfna GitHub została zarchiwizowana w lipcu 2024. Podstawowy silnik QtWebKit został zdeprecjonowany przez Qt w 2015 roku. Strona statusu projektu wyraźnie oznacza go jako zdeprecjonowany.

Poza problemami z ładowaniem DLL, silnik renderujący jest zamrożony na poziomie możliwości około Safari 2011. Brak Flexbox, brak Grid, ograniczony CSS3, zawodny JavaScript. I są niezałatane krytyczne luki: CVE-2022-35583(CVSS 9.8) umożliwia ataki SSRF, które mogą wyciekają dane AWS przez spreparowany HTML.

Czaswkhtmltopdfjuż minął. Błędy ładowania DLL są symptomem głębszego problemu: polegasz na porzuconym oprogramowaniu bez drogi do przodu.

iText 7(pdfHTML Add-On) — Ograniczony CSS, Licencjonowany AGPL

DłączegoPdfSharpnie obsługuje HTML?

PdfSharp pojawia się w wynikach wyszukiwania "HTML to PDF" ze względu na swoją popularność (34.9 milionów pobrań z NuGet) i częste polecenia. Ale PdfSharp nie posiada parsera HTML. Dostarcza API rysowania oparte na współrzędnych: DrawString(), DrawRectangle(), DrawImage() z jednoznacznie określonymi pozycjami X/Y.

Często sugerowane obejście, HtmlRenderer.PdfSharp, obsługuje tylko HTML 4.01 i CSS Level 2. Jeśli Twój HTML używa jakiejkolwiek funkcji CSS wprowadzonej po 2010 roku — Flexbox (2012), Grid (2017), niestandardowe właściwości (2017), border-radius (2011) — nie będzie renderowany.

Programiści, którzy wybierają PdfSharp oczekując wsparcia dla HTML, albo kończą z ręcznym umieszczaniem każdego elementu przy użyciu kodu opartego na współrzędnych, albo dodają drugą bibliotekę do renderowania HTML — w tym momencie PdfSharp jest zbędny.

Co sprawia, że Puppeteer jest tak wymagający pod względem zasobów?

Puppeteer Sharp steruje przeglądarką Chrome w trybie headless za pośrednictwem powiązań .NET. Dokładność renderowania odpowiada Chrome, ponieważ jest to Chrome. Koszt jest operacyjny: zarządzasz zewnętrznymi procesami przeglądarki.

Oto jak faktycznie wygląda wdrożeniePuppeteer Sharpw środowisku produkcyjnym — nie jest to 5-wierszowy przykład z samouczków, ale kod puli przeglądarek potrzebny do równoczesnego generowania plików PDF:

using PuppeteerSharp;
using System.Collections.Concurrent;

public class PdfBrowserPool : IAsyncDisposable
{
    private readonly ConcurrentBag<IBrowser> _available = new();
    private readonly SemaphoreSlim _semaphore;
    private readonly int _maxBrowsers;

    public PdfBrowserPool(int maxBrowsers = 4)
    {
        _maxBrowsers = maxBrowsers;
        _semaphore = new SemaphoreSlim(maxBrowsers, maxBrowsers);
    }

    public async Task InitializeAsync()
    {
        await new BrowserFetcher().DownloadAsync(); // ~280MB download
        for (int i = 0; i < _maxBrowsers; i++)
        {
            var browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox",
                               "--disable-dev-shm-usage" }
            });
            _available.Add(browser);
        }
    }

    public async Task<byte[]> ConvertHtmlToPdf(string html)
    {
        await _semaphore.WaitAsync();
        IBrowser browser = null;
        try
        {
            if (!_available.TryTake(out browser))
                throw new InvalidOperationException("No browser available");

            await using var page = await browser.NewPageAsync();
            await page.SetContentAsync(html, new NavigationOptions
            {
                WaitUntil = new[] { WaitUntilNavigation.Networkidle0 }
            });
            var result = await page.PdfAsync(new PdfOptions
            {
                Format = PaperFormat.A4,
                PrintBackground = true
            });
            return result;
        }
        catch (Exception ex) when (ex is NavigationException or TargetClosedException)
        {
            // Browser crashed — replace it
            browser?.Dispose();
            browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox" }
            });
            throw; // Re-throw after recovery
        }
        finally
        {
            if (browser != null) _available.Add(browser);
            _semaphore.Release();
        }
    }

    public async ValueTask DisposeAsync()
    {
        foreach (var browser in _available)
        {
            await browser.CloseAsync();
            browser.Dispose();
        }
    }
}

using PuppeteerSharp;
using System.Collections.Concurrent;

public class PdfBrowserPool : IAsyncDisposable
{
    private readonly ConcurrentBag<IBrowser> _available = new();
    private readonly SemaphoreSlim _semaphore;
    private readonly int _maxBrowsers;

    public PdfBrowserPool(int maxBrowsers = 4)
    {
        _maxBrowsers = maxBrowsers;
        _semaphore = new SemaphoreSlim(maxBrowsers, maxBrowsers);
    }

    public async Task InitializeAsync()
    {
        await new BrowserFetcher().DownloadAsync(); // ~280MB download
        for (int i = 0; i < _maxBrowsers; i++)
        {
            var browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox",
                               "--disable-dev-shm-usage" }
            });
            _available.Add(browser);
        }
    }

    public async Task<byte[]> ConvertHtmlToPdf(string html)
    {
        await _semaphore.WaitAsync();
        IBrowser browser = null;
        try
        {
            if (!_available.TryTake(out browser))
                throw new InvalidOperationException("No browser available");

            await using var page = await browser.NewPageAsync();
            await page.SetContentAsync(html, new NavigationOptions
            {
                WaitUntil = new[] { WaitUntilNavigation.Networkidle0 }
            });
            var result = await page.PdfAsync(new PdfOptions
            {
                Format = PaperFormat.A4,
                PrintBackground = true
            });
            return result;
        }
        catch (Exception ex) when (ex is NavigationException or TargetClosedException)
        {
            // Browser crashed — replace it
            browser?.Dispose();
            browser = await Puppeteer.LaunchAsync(new LaunchOptions
            {
                Headless = true,
                Args = new[] { "--no-sandbox", "--disable-setuid-sandbox" }
            });
            throw; // Re-throw after recovery
        }
        finally
        {
            if (browser != null) _available.Add(browser);
            _semaphore.Release();
        }
    }

    public async ValueTask DisposeAsync()
    {
        foreach (var browser in _available)
        {
            await browser.CloseAsync();
            browser.Dispose();
        }
    }
}

Imports PuppeteerSharp
Imports System.Collections.Concurrent
Imports System.Threading

Public Class PdfBrowserPool
    Implements IAsyncDisposable

    Private ReadOnly _available As New ConcurrentBag(Of IBrowser)()
    Private ReadOnly _semaphore As SemaphoreSlim
    Private ReadOnly _maxBrowsers As Integer

    Public Sub New(Optional maxBrowsers As Integer = 4)
        _maxBrowsers = maxBrowsers
        _semaphore = New SemaphoreSlim(maxBrowsers, maxBrowsers)
    End Sub

    Public Async Function InitializeAsync() As Task
        Await (New BrowserFetcher()).DownloadAsync() ' ~280MB download
        For i As Integer = 0 To _maxBrowsers - 1
            Dim browser = Await Puppeteer.LaunchAsync(New LaunchOptions With {
                .Headless = True,
                .Args = New String() {"--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"}
            })
            _available.Add(browser)
        Next
    End Function

    Public Async Function ConvertHtmlToPdf(html As String) As Task(Of Byte())
        Await _semaphore.WaitAsync()
        Dim browser As IBrowser = Nothing
        Try
            If Not _available.TryTake(browser) Then
                Throw New InvalidOperationException("No browser available")
            End If

            Await Using page = Await browser.NewPageAsync()
                Await page.SetContentAsync(html, New NavigationOptions With {
                    .WaitUntil = New WaitUntilNavigation() {WaitUntilNavigation.Networkidle0}
                })
                Dim result = Await page.PdfAsync(New PdfOptions With {
                    .Format = PaperFormat.A4,
                    .PrintBackground = True
                })
                Return result
            End Using
        Catch ex As Exception When TypeOf ex Is NavigationException OrElse TypeOf ex Is TargetClosedException
            ' Browser crashed — replace it
            browser?.Dispose()
            browser = Await Puppeteer.LaunchAsync(New LaunchOptions With {
                .Headless = True,
                .Args = New String() {"--no-sandbox", "--disable-setuid-sandbox"}
            })
            Throw ' Re-throw after recovery
        Finally
            If browser IsNot Nothing Then _available.Add(browser)
            _semaphore.Release()
        End Try
    End Function

    Public Async Function DisposeAsync() As ValueTask Implements IAsyncDisposable.DisposeAsync
        For Each browser In _available
            Await browser.CloseAsync()
            browser.Dispose()
        Next
    End Function
End Class

To około 60 wierszy kodu infrastruktury, zanim wygenerujesz pojedynczy plik PDF. Potrzebne jest również monitorowanie wycieków pamięci (procesy Chromium z czasem gromadzą pamięć), kontrolę stanu oraz plik Dockerfile z ponad 20 zależnościami Chromium. Rozmiar obrazu Docker wzrasta o 300–400 MB.

Porównaj to z odpowiednim podejściem IronPDF:

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
// Browser pooling, process management, crash recovery — handled internally

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
// Browser pooling, process management, crash recovery — handled internally

Imports IronPdf

Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf(html)
' Browser pooling, process management, crash recovery — handled internally

Puppeteer Sharp jest opłacalny, jeśli Twój zespół jest w stanie pokryć związane z nim koszty operacyjne. Dla zespołów, które chcą skupić się na swojej aplikacji, a nie na infrastrukturze przeglądarki,IronPDFobsługuje to samo renderowanie wewnętrznie.

DłączegoQuestPDFnie może konwertować plików HTML?

QuestPDF pojawia się praktycznie w każdej dyskusji na temat "HTML do PDF w C#" na Reddicie i Stack Overflow. Powstaje w ten sposób spójny schemat: programiści kupują lub integrują QuestPDF, oczekując konwersji do HTML, a następnie odkrywają, że w ogóle nie renderuje on HTML.

QuestPDF to płynnie działający interfejs API w języku C# do programowego tworzenia dokumentów. Jego pozycjonowanie wyraźnie brzmi: "przestań zmagać się z konwersją HTML na PDF" — zastępuje ono podejście oparte na HTML kodem C#. Jest to świadomy wybór projektowy. Dyskusje na GitHubie z lat 2022–2024 pokazują, że programiści odkrywają to po rozpoczęciu wdrażania. Twórcy konsekwentnie potwierdzają, że obsługa HTML nie jest planowana.

Jeśli obecny proces wykorzystuje szablony HTML — widoki Razor dla faktur, kod HTML pulpitu nawigacyjnego dla raportów, treści internetowe do archiwizacji —QuestPDFwymaga przepisania każdego szablonu w płynnym kodzie API języka C#. W przypadku nowych projektów, w których tworzysz układy dokumentów od podstaw przy użyciu danych strukturalnych, APIQuestPDFjest dobrze zaprojektowane i wydajne.

Licencja społecznościowa obejmuje firmy o rocznych przychodach brutto poniżej 1 mln USD. Ponadto wymagańa jest licencja komercyjna.

A co z Aspose.PDF?

Aspose.PDF zapewnia szeroki zakres funkcji związanych z plikami PDF w ramach licencji komercyjnej (ceny zaczynają się od ~999 USD/programista). Konwersja HTML wykorzystuje niestandardowy silnik, a nie przeglądarkę — podobnie jak iText, obsługuje podstawowy HTML, ale nie renderuje poprawnie nowoczesnych funkcji CSS.

Głównym problemem jest stabilność platformy:Asposeopiera się na System.Drawing.Common, co wymaga libgdiplus w systemie Linux. W .NET 6+ firma Microsoft wycofała tę funkcję dla platform innych niż Windows. Programiści zgłaszają wycieki pamięci charakterystyczne dla wdrożeń w systemie Linux, które nie występują w systemie Windows. W środowiskach wyłącznie dla systemu Windows sprawdzi się Aspose. W przypadku wdrożeń wielopłatformowych lub kontenerowych łańcuch zależności stwarza ciągłe ryzyko.

Jak przeprowadzić migrację z innych bibliotek?

Dla zespołów migrujących z iTextSharp lub wkhtmltopdf,IronPDFakceptuje bezpośrednio adresy URL — jest to przydatne, gdy istniejący przepływ pracy generuje pliki HTML lub wyświetla strony:

using IronPdf;

var renderer = new ChromePdfRenderer();

// Convert from URL — useful when migrating fromwkhtmltopdfURL-based workflows
var pdf = renderer.RenderUrlAsPdf("https://localhost:5001/reports/quarterly");
pdf.SaveAs("report.pdf");

// Convert from local HTML file
var pdfFromFile = renderer.RenderHtmlFileAsPdf("templates/invoice.html");
pdfFromFile.SaveAs("invoice.pdf");

using IronPdf;

var renderer = new ChromePdfRenderer();

// Convert from URL — useful when migrating fromwkhtmltopdfURL-based workflows
var pdf = renderer.RenderUrlAsPdf("https://localhost:5001/reports/quarterly");
pdf.SaveAs("report.pdf");

// Convert from local HTML file
var pdfFromFile = renderer.RenderHtmlFileAsPdf("templates/invoice.html");
pdfFromFile.SaveAs("invoice.pdf");

Imports IronPdf

Dim renderer As New ChromePdfRenderer()

' Convert from URL — useful when migrating from wkhtmltopdf URL-based workflows
Dim pdf = renderer.RenderUrlAsPdf("https://localhost:5001/reports/quarterly")
pdf.SaveAs("report.pdf")

' Convert from local HTML file
Dim pdfFromFile = renderer.RenderHtmlFileAsPdf("templates/invoice.html")
pdfFromFile.SaveAs("invoice.pdf")

Wdrożenie

IronPDF działa na systemach Windows (x64), Linux (x64, ARM64), macOS (x64, Apple Silicon) oraz w kontenerach Docker. Konfiguracja Docker to standardowy obraz .NET Standard:

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY . .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Bez instalacji Chromium, bez zależności od bibliotek natywnych, bez konfiguracji piaskownicy.

Licencjonowanie: Licencje wieczyste już od 749 USD. Ceny opublikowane na stronie IronPDF.com. Bez licencji AGPL, bez opłat za dokument, bez progów przychodów.