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

wkhtmltopdf Sargıları — DLL Yükleme Hatası Ekosistemi

Bu makalelere geliştirici getiren en yaygin arama sorgusu bir varyasyonu sunar:

System.DllNotFoundException: DLL 'libwkhtmltox' yuklenemedi

Platforma özgü değişkenler şunları içerir:

'wkhtmltox' veya bagimliliklardan biri olan paylasilan kutuphane yuklenemiyor
    (Linux — libwkhtmltox.so not found)

Belirtilen modul bulunamadi. (0x8007007E)
    (Windows — wkhtmltox.dll path not configured)

dyld: Kutuphane yuklenemedi: libwkhtmltox.dylib
    (macOS — not supported on ARM64/Apple Silicon)

Bu hatalar DinkToPdf, NReco.PdfGenerator, WkHtmlToXSharp ve ayni terkedilmis binari etrafinda C# sargilari oluşturan diğer urunlerden gelir. wkhtmltopdf GitHub organizasyonu Temmuz 2024'te arsive eklendi. Altta yatan QtWebKit motoru, Qt tarafindan 2015'te kullanıma kapatıldı. proje durum sayfası açik bir sekilde kullanımdan kaldirildi olarak isaretlenmistir.

DLL yükleme sorunlarinin utesinde, görüntüleme motoru yaklasik Safari 2011 yeteneginde donduruldu. Flexbox yok, Grid yok, sinirli CSS3, guvenilmez JavaScript. Ve yamalanmayan kritik guvenlik aciklari vardir: CVE-2022-35583(CVSS 9.8), ozenle hazirlanan HTML araciligiyla AWS kimlik bilgilerini celme edebilecek SSRF saldırılarını etkinlestirir.

wkhtmltopdf'nin zamanı geçti. DLL yükleme hataları daha derin bir sorunun belirtileridir: ilerleme yolu olmayan terkedilmis yazilima bagimli oluyorsunuz.

iText 7 (pdfHTML Eklentisi) — Sinirli CSS, AGPL Lisansli

NedenPdfSharpHTML'yi Desteklemiyor?

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

Sıkça önerilen geçici çözüm, HtmlRenderer.PdfSharp, yalnızca HTML 4.01 ve CSS Level 2'yi destekler. Eğer HTML'iniz 2010'dan sonra tanıtılmış bir CSS özelliği kullanıyorsa — Flexbox (2012), Grid (2017), özel özellikler (2017), border-radius (2011) — render edilmeyecektir.

HTML desteği bekleyerek PdfSharp seçen geliştiriciler, ya her bir elemanı koordinat tabanlı kodla manuel olarak konumlandırır ya da HTML renderleme için ikinci bir kütüphane eklerler — bu noktada PdfSharp gereksiz hale gelir.

Puppeteer Sharp'i Nasıl Kaynak Sert Yapan?

Puppeteer Sharp başsız Chrome'u .NET bağlamaları aracılığıyla kontrol eder. Görüntüleme dogrulugu Chrome ile eslesir, cunku o Chrome'dur. Maliyet operasyoneldir: harici tarayici sureclerini siz yonetirsiniz.

IsletmedekiPuppeteer Sharpdagitimi aslen ornegi izgara görüntülu bir sekline suruyle PDF oluşturumak icin tarayici havuzlama kodunu gerektirir.

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

Bir tek PDF oluşturmadan once ~60 satir alt yapi kodudur. Ayrica hafiza sızıntı izlemesi (Chromium is sur leleri zamanla hafiza alikoyar), saglik kontrolleri ve 20+ Chromium bagimliliklari olan bir Dockerfile'a ihtiyaç duyarsiniz. Docker imaj boyutu 300–400MB artis gösterir.

Bu, esdegerIronPDFyaklasimi ile karsilastirilir:

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

Ekibiniz operasyonel yükleri absorbe edebilirsePuppeteer Sharpuygulanabilir. Tarayici alt yapi isine odaklanmaktan çok uygulamalarina odaklanmak isteyen takimlar icin,IronPDFayni işleme dahili olarak yonetir.

NedenQuestPDFHTML Dönüştüremez?

QuestPDF hemen her Reddit ve Stack Overflow 'HTML to PDF C#' tartismasinda gorunur. Bu surekli bir model yaratir: geliştiriciler, HTML donusumu beklentisiyle QuestPDF'i satin alir veya birlestirir, sonra HTML'yi hic yorumlamadigini kesfederler.

QuestPDF, programatik dokumen oluşturmak icin bir akici C# API'sidir. Konumlandirilmasi, "HTML to PDF donusumuyle mucadeleyi durdurun" acik bir sekilde — HTML yaklasimi C# kodu ile değiştirir. Bu, kasten bir tasarim secimi. GitHub tartısmaları 2022'den 2024'e kadar bu kesfin başlangicinda geliştiricilerin kesfettigini gösterir. Bakimcilar sürekli olarak HTML desteginin planlanmadigini dogruluyor.

Mesaî mevcut iş akışı HTML şablonlarını kullaniyorsa — faturalar icin Razor görünümleri, raporlar icin pano HTML'ler, arsivleme icin web içeriği —QuestPDFher şablonu C# akici API koduyla yeniden yonetmez. Yeni projelerde belgeleri sıfırdan yaparken,QuestPDFAPI'si iyi tasarlanmis ve verimlidir.

Baglam Izin Koleji, $1M EGT altinda isletmeleri kapsar. Bunun üzerinde, ticari lisans zorunludur.

Aspose.PDF Hakkında Ne Söyleyebiliriz?

Aspose.PDF, ticari lisanslama ile geniş PDF işlevselliği sağlar (başlangıç ~999$/geliştirici). HTML dönüşümü, bir tarayıcı yerine özel bir motor kullanır — iText'e benzer şekilde, temel HTML'yi işler ancak modern CSS özelliklerini doğru şekilde işleyemez.

Asıl endişe platformun kararlılığıdır: Aspose, Linux'ta libgdiplus gerektiren System.Drawing.Common'e bağlıdır. Microsoft, .NET 6+ için bu durumu Windows dışı platformlarda devre dışı bıraktı. Geliştiriciler, Windows'ta meydana gelmeyen Linux dağıtımlarına özgü bellek sızıntılarını rapor etmektedir. Yalnızca Windows ortamları için,Asposeyeteneklidir. Platformlar arası veya konteyner tabanlı dağıtımlar için, bağımlılık zinciri sürekli bir risk oluşturur.

Diğer Kütüphanelerden Nasıl Geçiş Yaparım?

iTextSharp veya wkhtmltopdf'den geçiş yapan ekipler için,IronPDFURL'leri doğrudan kabul eder — HTML dosyaları oluşturduğunuzda veya sayfalar sunduğunuzda yararlı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")

Dağıtım

IronPDF, Windows (x64), Linux (x64, ARM64), macOS (x64, Apple Silicon) ve Docker konteynerlerinde çalışır. Docker konfigürasyonu standart bir .NET imajı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ığı yok, sandbox konfigürasyonu yok.

Lisanslama: Sonsuz lisanslar 749$'dan başlar. Yayınlanan fiyatlar ironpdf.com adresinde. AGPL yok, belge başına ücret yok, gelir eşiği yok.