C#'ta HTML'den PDF'e - Kütüphane Seçeneklerinin Gerçekliği

wkhtmltopdfSarmalayıcıları — DLL Yükleme Hatası Ekosistemi

Bu makalelere geliştiricileri getiren en yaygın arama sorgusu, şu varyasyonlardan biridir:

System.DllNotFoundException: 'libwkhtmltox' DLL'i yüklenemedi

Platforma özgü varyantlar şunlardır:

'wkhtmltox' veya bağımlılıklarından birini yükleme başarısız
    (Linux — libwkhtmltox.so not found)

Belirtilen modül bulunamadı. (0x8007007E)
    (Windows — wkhtmltox.dll path not configured)

dyld: Kütüphane yüklenemedi: libwkhtmltox.dylib
    (macOS — not supported on ARM64/Apple Silicon)

Bu hatalar DinkToPdf, NReco.PdfGenerator, WkHtmlToXSharp ve aynı terkedilmiş ikili etrafındaki diğer C# sarmalayıcılarından gelmektedir. wkhtmltopdf GitHub organizasyonu Temmuz 2024'te arşivlendi. Altında yatan QtWebKit motoru Qt tarafından 2015'te kaldırıldı. proje durum sayfası bunu açıkça kullanım dışı olarak işaretliyor.

DLL yükleme sorunlarının ötesinde, render motoru yaklaşık olarak Safari 2011 kapasitesinde donmuş durumda. Flexbox yok, Grid yok, sınırlı CSS3, güvensiz JavaScript. Ve yamalı olmayan kritik zafiyetler var: ⟨a href="https://github.com/wkhtmltopdf/wkhtmltopdf/issues/5249"⟩CVE-2022-35583⟨/a⟩ (CVSS 9.8), özel olarak oluşturulmuş HTML aracılığıyla AWS kimlik bilgilerini dışa sızdırabilen SSRF saldırılarına olanak tanır.

wkhtmltopdf'nin zamanı geçti. DLL yükleme hataları daha derin bir sorunun belirtisidir: ileriye yönelik hiçbir yolu olmayan terk edilmiş bir yazılıma bağımlısınız.

iText(pdfHTML Eklentisi) — Sınırlı CSS, AGPL Lisanslı

NedenPDFSharpHTML Desteklemez?

PdfSharp "HTML to PDF" arama sonuçlarında popülerliği (34,9 milyon NuGet indirme) ve sıkça önerilmesi nedeniyle görünür. Ancak PdfSharp'nin bir HTML ayrıştırıcısı yok. Koordinat tabanlı bir çizim API'si sağlar: açık X/Y pozisyonları ile DrawString(), DrawRectangle(), DrawImage().

Sık önerilen geçici çözüm, HtmlRenderer.PdfSharp, yalnızca HTML 4.01 ve CSS Seviye 2'yi destekler. HTML'iniz 2010 sonrasında tanıtılan bir CSS özelliği kullanıyorsa — Flexbox (2012), Grid (2017), özel özellikler (2017), border-radius (2011) — işlenmeyecektir.

PdfSharp'yi seçen ve HTML desteği bekleyen geliştiriciler, ya her elemanı koordinat tabanlı kodla elle konumlandırır ya da HTML işleme için ikinci bir kütüphane ekler — bu noktada PdfSharp gereksiz olur.

Puppeteer SharpNeden Kaynak Yoğun?

Puppeteer Sharp, Başsız Chrome'u .NET bağlamaları aracılığıyla kontrol eder. Render doğruluğu Chrome ile eşleşmektedir çünkü Chrome'dur. Maliyet, operasyoneldir: dış tarayıcı süreçlerini yönetirsiniz.

ÜretimPuppeteer Sharpdağıtımı, öğreticilerdeki 5 satırlık örnek kod değil, eşzamanlı PDF üretimi için gereken tarayıcı havuzu kodu olarak işte böyle görünüyor:

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

Bu, tek bir PDF üretmeden önce ~60 satır altyapı kodudur. Ayrıca bellek sızıntısı izlemesi (Zamanla Chromium süreçleri bellek biriktirir), sağlık kontrolleri ve 20+ Chromium bağımlılığı ile bir Dockerfile gereklidir. Docker görüntü boyutu 300–400MB artar.

Bunu eşdeğerIronPDFyaklaşımı ile karşılaştırın:

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, ekibiniz operasyonel yükü absorbe edebilirse uygulanabilir. Tarayıcı altyapısına değil uygulamaya odaklanmak isteyen ekipler içinIronPDFaynı render işlemini dahili olarak ele alır.

QuestPDFNeden HTML'yi Dönüştüremez?

QuestPDF, Reddit ve Stack Overflow'da neredeyse her 'HTML to PDF C#' tartışmasında görünmektedir. Bu tutarlı bir model oluşturur: geliştiriciler HTML dönüştürme bekleyerek QuestPDF'yi satın alır veya entegre eder, ardından hiç HTML render etmediğini keşfeder.

QuestPDF programatik belge oluşturma için akıcı bir C# API'sidir. Pozisyonu açıkça 'HTML-to-PDF dönüşümüyle mücadele etmemeyi bırak' şeklindedir — HTML yaklaşımını C# kodu ile değiştirir. Bu kasti bir tasarım tercihi. 2022 ile 2024 arasındaki GitHub tartışmaları geliştiricilerin bu durumu uygulanmayı başlattıklarında keşfettiklerini göstermektedir. Yönetici ekibi sürekli olarak HTML desteğinin planlanmadığını doğrular.

Mevcut iş akışınızda HTML şablonlar — faturalar için Razor görünümleri, raporlar için gösterge paneli HTML'leri, arşivleme için web içeriği — kullanılıyorsa,QuestPDFher şablonu C# akıcı API kodu olarak yeniden yazmayı gerektirir. Yapılandırılmış verilerle sıfırdan belge düzenleri oluşturduğunuz yeni projeler için QuestPDF'nin API'si iyi tasarlanmış ve etkili.

Topluluk Lisansı, yıllık brüt geliri 1M$ altında olan işletmeleri kapsar. Bunun üzerinde ticari lisanslama gereklidir.

Aspose.PDF Ne Durumda?

Aspose.PDF, ticari lisanslama ile geniş bir PDF işlevselliği sağlar (geliştirici başına ~999 dolardan başlar). HTML dönüştürme, bir tarayıcı yerine özel bir motor kullanmaktadır — iText'e benzer biçimde, temel HTML'i işler ancak modern CSS özelliklerini doğru bir şekilde render etmez.

Asıl endişe platform istikrarıdır: Aspose, Linux üzerinde libgdiplus gerektiren System.Drawing.Common'a dayanır. Microsoft, bunu .NET 6+ üzerindeki non-Windows platformları için kullanımdan kaldırdı. Geliştiriciler, Windows üzerinde meydana gelmeyen Linux dağıtımlarına özgü bellek sızıntılarını bildirir. Yalnızca Windows ortamları için Aspose, yeterlidir. Çapraz platform ya da konteynırlaştırılmış dağıtımlar için bağımlılık zinciri sürekli risk yaratır.

Diğer Kütüphanelerden Nasıl Geçiş Yapılır?

iText veya wkhtmltopdf'den geçen ekipler için,IronPDFdoğrudan URL'leri kabul eder — mevcut iş akışınız HTML dosyaları oluşturduğunda veya sayfalar sunduğunda kullanışlıdır:

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")

Kullanım

IronPDF, Windows (x64), Linux (x64, ARM64), macOS (x64, Apple Silicon) ve Docker konteynerlerinde çalışır. Docker yapılandırması standart bir .NET görüntüsüdür:

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

Chromium kurulumu yok, yerel kütüphane bağımlılıkları yok, sandbox yapılandırması yok.

Lisanslama: $2,998'dan başlayan Süresiz Lisanslar. ironpdf.com adresinde yayınlanan fiyatlar. AGPL yok, belge başına ücret yok, gelir eşik limitleri yok.