PDF Dönüşüm Servisi

PDF oluşturma, CPU ve bellek yoğun bir işlemdir. Ana uygulamanızın içinde PDF render etmek; hem performansı düşürür hem de ölçeklendirmeyi zorlaştırır. html-to-pdf bu sorunu bağımsız bir mikroservis olarak çözer — Playwright'ın headless Chromium motoru ile piksel mükemmelliğinde PDF çıktısı üretir.

Neden Ayrı Bir Mikroservis?

Özellikler

• Tekli HTML → PDF — Tam CSS/JS desteğiyle her türlü HTML belgesini PDF'e dönüştürür
• Çoklu HTML → Birleştirilmiş PDF — Birden fazla HTML'i tek PDF'te birleştirir
• Chromium Render — Playwright'ın headless Chromium motoru ile piksel mükemmelliğinde çıktı
• PDF Birleştirme — PdfSharpCore ile çoklu belge birleştirme
• Otomatik Tarayıcı Kurulumu — Chromium ilk çalıştırmada otomatik indirilir
• İstemci SDK'sı — .NET tüketicileri için hazır NuGet paketi
• Scalar API Dokümantasyonu — /scalar/v1 adresinde etkileşimli API referansı
• Docker Hazır — Sağlık kontrolü dahil üretime hazır Dockerfile
• 73 Test — Birim, entegrasyon ve performans/stres testleri (gerçek e-fatura şablonlarıyla)

Hızlı Başlangıç

Servisi Çalıştırma

dotnet run --project src/Web

Servis http://localhost:5090 adresinde başlar. İlk çalıştırmada Playwright otomatik olarak Chromium'u indirir.

Docker ile Çalıştırma

docker build -t mersel-htmltopdf .
docker run -p 5090:8080 mersel-htmltopdf

API Endpoint'leri

Tek HTML → PDF

# Varsayılan ayarlarla
curl -X POST http://localhost:5090/convert \
  -F "file=@fatura.html" \
  -o cikti.pdf

# Landscape, özel kenar boşlukları
curl -X POST "http://localhost:5090/convert?landscape=true&marginTop=25mm&marginBottom=25mm" \
  -F "file=@rapor.html" \
  -o rapor.pdf

# Akıllı küçültme + JS bekleme (wkhtmltopdf uyumlu davranış)
curl -X POST "http://localhost:5090/convert?smartShrinking=true&jsDelay=2000" \
  -F "file=@fatura.html" \
  -o cikti.pdf

Çoklu HTML → Tek PDF

curl -X POST http://localhost:5090/convert/merge \
  -F "files=@sayfa1.html" \
  -F "files=@sayfa2.html" \
  -F "files=@sayfa3.html" \
  -o birlesmis.pdf

Sağlık Kontrolü

curl http://localhost:5090/health

{
  "status": "Healthy",
  "service": "HtmlToPdf",
  "duration": 0.42,
  "checks": [
    {
      "name": "chromium",
      "status": "Healthy",
      "description": "Chromium tarayıcısı bağlı ve hazır",
      "duration": 0.12
    }
  ]
}

Tüm PDF Ayarları

.NET İstemci SDK

Kurulum

dotnet add package MERSEL.Services.HtmlToPdf.Client

DI Kaydı

// Yapılandırma dosyasından
builder.Services.AddHtmlToPdfClient(builder.Configuration);

// Veya doğrudan URL belirterek
builder.Services.AddHtmlToPdfClient("http://htmltopdf-service:8080");

Kullanım

public class FaturaServisi(IHtmlToPdfConverter pdfConverter)
{
    // Basit kullanım (varsayılan: A4, dikey, arka plan açık)
    public async Task<byte[]> FaturaPdfOlustur(string htmlIcerik)
    {
        var htmlBytes = Encoding.UTF8.GetBytes(htmlIcerik);
        return await pdfConverter.ConvertAsync(htmlBytes);
    }

    // wkhtmltopdf uyumlu preset ile
    public async Task<byte[]> EFaturaPdfOlustur(string htmlIcerik)
    {
        var htmlBytes = Encoding.UTF8.GetBytes(htmlIcerik);
        return await pdfConverter.ConvertAsync(
            htmlBytes, PdfConvertOptions.WkHtmlCompatible);
    }

    // Özel ayarlarla
    public async Task<byte[]> RaporPdfOlustur(string htmlIcerik)
    {
        var htmlBytes = Encoding.UTF8.GetBytes(htmlIcerik);
        return await pdfConverter.ConvertAsync(htmlBytes, new PdfConvertOptions
        {
            Landscape = true,
            MarginTop = "25mm",
            MarginBottom = "25mm",
            SmartShrinking = true,
            JavaScriptDelayMs = 2000
        });
    }

    // Birden fazla HTML'i tek PDF'te birleştirme
    public async Task<byte[]> TopluFaturaPdf(List<string> htmlSayfalar)
    {
        var htmlByteList = htmlSayfalar.Select(Encoding.UTF8.GetBytes);
        return await pdfConverter.ConvertAndMergeAsync(htmlByteList);
    }
}

Hazır Preset'ler

wkhtmltopdf'den Geçiş

wkhtmltopdf artık bakım almıyor ve modern web standartlarını desteklemiyor. Bu servise geçmek için:

Parametre Karşılıkları

Kod Değişikliği

// Önce (wkhtmltopdf)
var converter = new WkHtmlToPdfConverter();
var pdf = converter.Convert(htmlString, "--page-size A4 --enable-smart-shrinking ...");

// Sonra (MERSEL.Services.HtmlToPdf)
public class FaturaServisi(IHtmlToPdfConverter pdfConverter)
{
    public async Task<byte[]> Olustur(string html)
    {
        var htmlBytes = Encoding.UTF8.GetBytes(html);
        return await pdfConverter.ConvertAsync(
            htmlBytes, PdfConvertOptions.WkHtmlCompatible);
    }
}

Yatay Ölçeklendirme

Servis tamamen stateless olduğu için load balancer arkasında sorunsuz ölçeklenir.

Docker Compose — 3 Replica

services:
  htmltopdf:
    build: .
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 1G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    ports:
      - "5090:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - htmltopdf

Observability

Prometheus Metrikleri (/metrics)

Grafana Dashboard

monitoring/ klasöründe hazır dashboard, tek komutla kurulur:

cd monitoring
docker compose up -d --build

Dashboard 4 bölümden oluşur:

• Genel Bakış — Toplam dönüşüm, hata oranı, aktif dönüşüm, ortalama süre, PDF boyutu
• Dönüşüm Performansı — İstek hızı, süre dağılımı (p50/p95/p99), tekli vs birleştirme
• HTTP İstekleri — Durum koduna göre istek hızı, yanıt süresi, endpoint bazında trafik
• .NET Runtime — GC heap, thread pool, proses bellek, CPU kullanımı

Performans

Sonuç

html-to-pdf, PDF dönüşümünü ana uygulamanızdan ayırarak hem performansı hem de ölçeklenebilirliği artırır. wkhtmltopdf'den geçiş minimum kod değişikliği gerektirir; hazır preset'ler ve .NET SDK ile dakikalar içinde entegre olursunuz.

• GitHub: github.com/mersel-os/html-to-pdf
• Detay Sayfası: Proje Detayları
• NuGet: MERSEL.Services.HtmlToPdf.Client
• Lisans: MIT