PDFsharp Kılavuzu: MigraDoc ve PdfSharpCore ile PDF Dosyaları Oluşturma

PDFsharp, C# kodu kullanarak PDF belgeleri oluşturmak ve düzenlemek için kullanılan açık kaynaklı bir .NET kütüphanesidir. Sayfaya metin, çizgi ve resim çizersiniz, Kaydet'i çağırırsınız ve bir PDF dosyanız olur. Tarayıcı motoru yok, yerel ikili dosya yok. Proje 2005 yılına dayanıyor ve bugün .NET arka uçlarından çıkan faturaların, raporların ve sertifikaların çoğu hala bu kütüphaneden geçiyor.

Bu yazıyı, sunucuda PDF dosyalarına ihtiyaç duyan ve nelerle karşılaşacaklarını bilmek isteyen geliştiriciler için yazdım. PDFsharp ve MigraDoc'un nasıl birlikte çalıştığını, hangi sürümün yüklenmesi gerektiğini, ilk çalışan dosyayı, Linux'taki yazı tipi sorununu, son lisans değişikliğini ve başka bir şey seçmeniz gereken noktayı ele alacağız.

PDFsharp nedir ve neler yapabilir?

PDFsharp kütüphanesinin arkasında, yaklaşık yirmi yıldır bu işi ayakta tutan küçük bir Alman şirketi olan empira Software GmbH bulunuyor. Zamanınızın büyük bir kısmı XGraphics sınıfına ayrılıyor. Eğer daha önce System.Drawing.Graphics ile WinForms boyama yaptıysanız, on dakika içinde kendinizi evinizde hissedeceksiniz: yazı tipi, fırça, x ve y, başla.

Kutudan çıkanlar:

• Metin, vektör şekiller, çizgiler ve resimler kullanarak sıfırdan PDF belgeleri oluşturun.
• Mevcut PDF dosyalarını açın ve sayfalarına damga, filigran veya sayfa numarası gibi içerikler ekleyin.
• Dosyalar arasındaki sayfaları başka bir dosyaya aktararak belgeleri birleştirin ve bölün.
• Dosyanın her makinede aynı görünmesi için yazı tiplerini gömün ve alt kümelere ayırın.
• Yer işaretleri, bağlantılar ve başlık, yazar ve anahtar kelimeler gibi belge meta verileri ekleyin.
• Dosyaları parolalar ve izin bayraklarıyla koruyun.
• Belgeleri dijital olarak imzalayın (6.2 sürümünden itibaren).

Dağıtım sıkıcı, bunu bir övgü olarak söylüyorum. Her şey yönetilen kod, bu yüzden operasyon ekibinizin asla bir sunucuya başsız Chrome kurmasına veya gece 2'de bir Ghostscript DLL'si aramasına gerek yok. Tek bir NuGet paketini referans alıyorsunuz, gönderiyorsunuz, iş bitiyor.

Şimdi işin püf noktası. Elinize sadece bir tuval geçiyor, başka hiçbir şey geçmiyor. Uzun bir paragraf sayfanın alt kenarına mı değiyor? Sizin sorununuz. Tablo birinci sayfayı mı geçiyor? MigraDoc'u kullanmadığınız sürece bu da sizin sorununuz.

PDFsharp ve MigraDoc: Hangi Katmana İhtiyacınız Var?

Aynı tedarikçi, aynı yayın takvimi, ama çok farklı işler. MigraDoc Foundation, PDFsharp'ın bir üst katında yer alıyor. Ona bir metnin nereye gideceğini söylemek yerine, bölümler, paragraflar, tablolar, başlıklar, altbilgiler, stiller ve arada sırada grafikler veriyorsunuz ve o her şeyin nereye yerleşeceğini anlıyor. Sonuç olarak bir PDF dosyası ortaya çıkıyor. Ya da her şeyi Word'de açmakta ısrar eden meslektaşınız için RTF.

Benim kısaltılmış yöntemim şu: PDFsharp "bu metni x=40, y=120 konumuna yerleştirin." MigraDoc ise "işte otuz satır ve tekrarlanan bir başlık, sayfaları siz düzenleyin."

Gerçek projelerde genellikle her ikisi de bulunur. MigraDoc aracılığıyla oluşturulan gövde metni, alt katman aracılığıyla elle çizilmiş bir kapak veya bir tedarikçinin PDF'sine eklenen bir damga. Zaten PDFsharp'ı kurmaktan kaçınamazsınız, çünkü MigraDoc paketi onu bir bağımlılık olarak dahil eder.

PDFsharp Derlemeleri Açıklaması: Temel Derleme, GDI+ ve WPF

Yeni başlayanlar genellikle NuGet'teki paket listesinde bir sonraki adımda takılıp kalırlar. PDFsharp 6, her biri kendi MigraDoc ikizine sahip üç farklı sürümde gelir.

Mevcut paketler .NET 8, 9 ve 10'un yanı sıra .NET Standard 2.0 ve .NET Framework 4.6.2'yi hedefliyor. Dolayısıyla, tozlu bir WinForms aracından yepyeni bir ASP.NET Core API'sine kadar, üzerinde hala çalışılan hemen her şey kapsanıyor.

Konsol uygulaması, web API, Docker, Azure Functions, Linux üzerinde çalışan her şey? Temel yapı. GDI+ veya WPF yalnızca sistem yazı tiplerini veya yerel bir denetimde önizlemeyi istediğiniz Windows masaüstü uygulamaları için mantıklıdır. Stack Overflow'da birisi bir keresinde konsol uygulamasının WPF sürümüne ihtiyacı olup olmadığını sormuştu. İhtiyaç duymamıştı.

Visual Studio'da NuGet'ten PDFsharp Nasıl Kurulur?

Hala WinForms döneminden kalma, ZIP dosyasını indirip içinden DLL dosyasını çıkarıp referansı kendiniz eklemenizi söyleyen forum gönderileri bulacaksınız. Bunları görmezden gelin. PDFsharp'ı NuGet üzerinden yükleyin; paket yöneticisi sürümleri takip eder, böylece sizin bunu yapmanıza gerek kalmaz.

1. Çözümünüzü Visual Studio'da açın ve Çözüm Gezgini'nde projeye sağ tıklayın.
2. "NuGet Paketlerini Yönet" seçeneğini seçin, " Gözat " sekmesine geçin ve "PDFsharp" araması yapın.
3. Belge düzenine de ihtiyacınız varsa PDFsharp (Core build) veya PDFsharp-MigraDoc'u seçin. Yayıncının empira Software GmbH olduğundan emin olun.
4. Yükle'ye tıklayın ve lisans istemini kabul edin.
5. Paketin doğru şekilde geri yüklendiğini doğrulamak için projeyi bir kez derleyin.

Terminal kullanıcıları tıklama işlemini atlayabilirler:

bash dotnet add package PDFsharp dotnet add package PDFsharp-MigraDoc

Paket Yöneticisi Konsolu'nda aynı şey Install-Package PDFsharp komutuyla yapılır. Ve lütfen farklı sürümleri karıştırmayın. Bir proje PDFsharp'ı referans alırken, komşu proje PDFsharp-GDI'yı kullandığı için bir ekibin tüm öğleden sonrasını tür çakışmaları yüzünden kaybettiğini gördüm.

C dilinde PDFsharp ile İlk PDF Belgeniz

Aşağıda, tek sayfalık bir PDF dosyası üreten en küçük program hakkında bilgi verilmektedir. Bu program, bir yazı tipi çözümleyicisi ayarlanmış olduğu sürece (sonraki bölüm), herhangi bir işletim sisteminde Core sürümünde çalışır.

```csharp
PdfSharp.Drawing kullanarak;
PdfSharp.Pdf kullanarak;

// PDFsharp 6.5 ve üzeri sürümler için ilk kullanımdan önce lisans seçimi yapılması gerekmektedir.
PdfSharpLicense.SetAgplLicense();

var document = new PdfDocument();
document.Info.Title = "Merhaba PDFsharp";

PdfPage page = document.AddPage();
XGraphics gfx = XGraphics.FromPdfPage(page);

var font = new XFont("Arial", 20, XFontStyleEx.Bold);
gfx.DrawString("Merhaba, PDFsharp!", font, XBrushes.Black,
yeni XRect(0, 0, page.Width.Point, page.Height.Point),
XStringFormats.Center);

belgeyi kaydet("hello.pdf");
```

Her PDFsharp programı şu yapıyı izler: belge, sayfa, XGraphics, çizim, kaydetme. Birimler noktadır (1/72 inç) ve başlangıç noktası sol üst köşededir. 6.2.x sürümünde lisans satırını silin. Bu API yalnızca 6.5.0 sürümünde ortaya çıktı.

Ve MigraDoc versiyonu:

```csharp
MigraDoc.DocumentObjectModel kullanılarak;
MigraDoc.Rendering kullanılarak;

var doc = new Document();
Bölüm bölüm = doc.AddSection();
bölüm.ParagrafEkle("Merhaba, MigraDoc!");

var oluşturucu = new PdfDocumentRenderer { Document = doc };
oluşturucu.RenderDocument();
renderer.PdfDocument.Save("merhaba-migradoc.pdf");
```

Hiçbir yerde koordinat yok. 500 paragraf yazın, sayfa sayısı ne kadar olursa olsun, sizin tarafınızda hiçbir sayfalama kodu olmadan sonuç alırsınız.

PDFsharp Temel Sürümündeki Yazı Tipleri: Çözümleyici Sorunu

Etrafınıza sorarsanız, en çok duyacağınız şikayet yazı tipleriyle ilgili olacaktır. GDI+ ve WPF derlemeleri, Windows'tan yüklenmiş TrueType yazı tiplerini okur. Core derlemesi hiçbir şey varsayamaz, çünkü ince bir Linux konteynerinde genellikle hiç kullanılabilir yazı tipi bulunmaz. Bu nedenle, ilk Docker dağıtımı genellikle uygun bir yazı tipi bulunamadığına dair bir istisna ile sonuçlanır.

Çözüm, IFontResolver arayüzünü uygulayan bir sınıf olan yazı tipi çözümleyicisidir. İki yöntemi vardır:

• ResolveTypeface, istenen bir yazı tipi ailesini ve stilini (örneğin, "Arial", kalın) bir yazı tipi adına eşler.
• GetFont, o yüz adına ait TTF dosyasının ham baytlarını döndürür.

İlk XFont oluşturulmadan önce, GlobalFontSettings.FontResolver aracılığıyla başlangıçta bir kez kaydedin.

```csharp
public class AppFontResolver : IFontResolver
{
public FontResolverInfo? ResolveTypeface(string family, bool bold, bool italic)
=> new FontResolverInfo(bold ? "Inter-Bold" : "Inter-Regular");

public byte[]? GetFont(string faceName) => File.ReadAllBytes(Path.Combine(AppContext.BaseDirectory, "Fonts", faceName + ".ttf"));

}

GlobalFontSettings.FontResolver = new AppFontResolver();
```

Kendiniz deneyimlemeden önce bilmeniz gerekenler:

• TTF dosyalarınızı proje içindeki bir Yazı Tipleri klasöründe saklayın ve bunların çıktı dizinine kopyalanmasını ayarlayın veya bunları kaynak olarak gömün, böylece kapsayıcı görüntü her zaman bunlara sahip olur.
• 6.2.0 sürümü eski CoreBuildFontResolver'ı kaldırdı. Windows veya WSL2'de GlobalFontSettings.UseWindowsFontsUnderWindows ile benzer davranışı geri yükleyebilirsiniz, ancak bu Linux veya macOS'ta hiçbir işe yaramaz.
• Resmi örnekler deposunda, başlangıç noktası olarak kopyalayabileceğiniz bir SubstitutingFontResolver bulunmaktadır.
• Oluşturulan dosyalara ticari bir yazı tipi eklemeden önce yazı tipi lisansını kontrol edin. Inter, Roboto veya Noto gibi açık kaynaklı yazı tipleri bu soruyu tamamen ortadan kaldırır.

Çözümleyici devreye girdiğinde, çıktı Windows, Linux ve macOS'ta tamamen aynı görünür.

PDFsharp 6 ile Dosyaları Birleştirme, İmzalama ve Güvenli Hale Getirme

Birçok ekip hiçbir zaman sıfırdan bir belge oluşturmaz. Mevcut dosyaları birleştirmek, damgalamak veya kilitlemek için kütüphaneyi kullanırlar. Birleştirme birkaç satırdan ibarettir: her kaynağı içe aktarma modunda açın ve sayfaları kopyalayın.

csharp var output = new PdfDocument(); foreach (var path in new[] { "part1.pdf", "part2.pdf" }) { using var input = PdfReader.Open(path, PdfDocumentOpenMode.Import); foreach (PdfPage p in input.Pages) output.AddPage(p); } output.Save("merged.pdf");

Bölme işlemi, aynı döngünün tersten işlenmesidir; her sayfa veya aralık için bir çıktı dosyası oluşturulur. Koruma için, document.SecuritySettings bir kullanıcı şifresi, bir sahip şifresi ve izin bayrakları (yazdırma, metin kopyalama vb.) alır.

Uzun zamandır istenen iki özellik nihayet 6.2 sürümüne eklendi:

• CMS tabanlı dijital imzalar . Varsayılan imzalayıcı ayrı bir PDFsharp.Cryptography derlemesinde bulunur ve IDigitalSigner'ı uygulayarak kendi imzalayıcınızı entegre edebilirsiniz. Zaman damgası sunucu desteği modern .NET'te çalışır ancak .NET Framework derlemesinde çalışmaz.
• Arşivleme için PDF/A çıktısı . Resmi belgelerde "bazı sınırlamalarla" çalıştığı ve hala geliştirme aşamasında olduğu belirtiliyor, bu nedenle uyumluluk açısından güvenmeden önce sonucu bir PDF/A denetleyicisiyle doğrulayın.

Bu sürüm ayrıca renkli emoji glifleri ve yönetilen bir MD5 uygulaması da getirdi; bu da FIPS kuralları altında veya Blazor'da çalışıyorsanız önemlidir.

PDFsharp Deposu, PdfSharpCore Çatalları ve 1.x Sürümleri

GitHub'da PDFsharp diye arama yaparsanız, neredeyse aynı isimde birkaç proje bulacaksınız. Suçu tarihe atın.

Eski 1.x serisi (1.50, 1.51) yalnızca .NET Framework üzerinde çalışıyordu. .NET Core çıktığında, insanlar beklemek istemediler ve kodu kendileri uyarladılar. Stefan Steiger tarafından başlatılan ve daha sonra diğer dallanmalar tarafından devralınan PdfSharpCore, çoğu insanın bildiği versiyondur. GDI+'ı kaldırdı ve kodu resmi sürümden yıllar önce Linux üzerinde çalışır hale getirdi.

Ardından PDFsharp 6 geldi: modern .NET üzerinde yeniden yazılmış, resmi çapraz platform Core yapısına sahip bir sürüm. Çatal sürümlerin var olma nedenlerinin çoğu ortadan kalktı.

Peki, Reddit'te sürekli çıkan "PdfSharp vs PdfSharpCore" tartışması ne anlama geliyor? Yeni proje, resmi paketler. Sadece eski kod zaten ona dayanıyorsa ve geçiş şu anda bir sprint'e değmiyorsa çatalı saklayın. Ve belgeler yetersiz geliyorsa, Empira'nın ayrı örnek deposuna gidin. Klasörleri ve dosyaları çalıştırılabilir örneklerdir, bu da tahmin yürütmekten çok daha iyidir.

PDFsharp Ücretsiz mi? PDFsharp 6.5'te Lisans Değişiklikleri

Evet, ömrünün büyük bir bölümünde ticari kullanıma izin veriliyordu. MIT lisansına sahipti, bu da neredeyse hiçbir kısıtlama olmaksızın ticari kullanım anlamına geliyordu. 6.2.4 sürümüne kadar olan tüm sürümler hala bu lisansa sahip.

6.5.0 sürümü bunu değiştirdi. Kütüphane artık çift lisanslıdır:

• AGPL (ücretsiz). Kütüphaneyi kullanmadan önce PdfSharpLicense.SetAgplLicense() yöntemini çağırarak etkinleştirirsiniz. AGPL, kaynak kodunuzu, ağ üzerinden yazılımınızla etkileşim kuran kullanıcılar da dahil olmak üzere kullanıcılara sunmanızı gerektirir; bu nedenle kapalı kaynaklı SaaS için pek uygun değildir.
• Ticari lisans. Satıcıdan bir lisans anahtarı satın alırsınız ve bunu PdfSharpLicense.LoadLicense(...) ile yüklersiniz. Bu, AGPL yükümlülüklerini ortadan kaldırır.

6.5.0 sürümünden itibaren kodunuzun bunlardan birini açıkça seçmesi gerekiyor. 7.0 önizlemeleri de aynı şekilde çalışıyor.

Pratikte:

• AGPL ile uyumlu açık kaynak projeleri, en yeni sürümü ücretsiz olarak kullanmaya devam edebilir.
• Kapalı kaynak kodlu ürünler ya ticari bir lisans satın alabilir ya da MIT lisansı altında kalan 6.2.x sürümünde kalabilirler. Mevcut sürümde kalmak, gelecekteki düzeltmeleri kaçırmak anlamına gelir, bu nedenle bu maliyeti dürüstçe değerlendirin.
• Seçiminiz ne olursa olsun, lisansın asıl metnini okuyun ve hukuk ekibinize onaylatın. Bu kılavuz yasal tavsiye niteliğinde değildir.

PDFsharp'ın Yetersiz Kaldığı Noktalar ve Onunla Birlikte Kullanılabilecek Araçlar

Kütüphane görevini iyi yapıyor. Ancak görev alanı dar ve aynı eksiklikler her forum başlığında ortaya çıkıyor.

• HTML'den PDF'ye dönüştürme yok. PDFsharp HTML veya CSS'i işlemez. Topluluk tarafından geliştirilen HtmlRenderer.PdfSharp eklentisi mevcut ancak yalnızca HTML 4.01 ve CSS seviye 2'yi desteklediği için flexbox veya grid içeren modern düzenler çalışmaz. HTML şablonlarına ihtiyaç duyan ekipler genellikle bunun yerine başsız tarayıcı tabanlı bir oluşturucuya yönelirler.
• JavaScript kullanılamaz. İstemci tarafında oluşturulan grafikler veya içerikler yakalanamaz.
• Görüntüye dönüştürme işlemi yapılmaz. PDFsharp, PDF sayfasını küçük resimler veya önizlemeler için PNG'ye dönüştüremez. Bunun için ayrı bir rasterleştiriciye ihtiyacınız var.
• Sınırlı metin çıkarma özelliği mevcuttur. İçerik akışında gezinebilirsiniz, ancak konum bilgileriyle birlikte temiz metin döndüren üst düzey bir API bulunmamaktadır. Ayrı bir açık kaynak kütüphanesi olan PdfPig, özellikle metin okuma ve çıkarma için geliştirilmiştir.
• Kısmi form desteği. Basit AcroForm doldurma işlemleri çalışır; komut dosyaları içeren karmaşık formlar ise farklı bir konudur.
• Tablolar için MigraDoc gereklidir. Düz PDFsharp ile her satırın yüksekliğini kendiniz hesaplarsınız.

Bu onu kötü bir seçim yapmaz. Faturalar, ekstreler, etiketler ve sertifikalar gibi veri odaklı belgeler tam olarak onun ideal kullanım alanıdır ve kapladığı alan çok küçüktür. Web sayfalarının piksel piksel mükemmel kopyaları ise öyle değildir.

Kripto Para Faturaları ve Ödeme Makbuzları için PDFsharp

PDFsharp ile en sık oluşturulan şeylerden biri muhtemelen makbuzlardır. Kripto para makbuzları, kart makbuzlarına göre biraz daha karmaşıktır. İyi haber şu: Ödeme ağ geçidi web kancanıza (ödeme durumu değiştiğinde gönderilen bir HTTP geri çağrısı) ulaştığında, tüm verilere sahip olursunuz. Başka bir yere bakmanıza gerek yok.

Üzerine şunları yazardım:

• Sipariş veya fatura numarası ve satıcının bilgileri
• Ödeme anındaki kripto para birimi ve itibari para karşılığı tutar.
• Kripto para ve ağ (örneğin, TRON'daki USDT ile Ethereum'daki USDT arasındaki fark)
• İşlem özeti (hash), böylece müşteri bunu bir blok gezgini üzerinden doğrulayabilir.
• Kısaltılmış alıcı cüzdan adresi ve onay süresi
• İşlem veya fatura sayfasına bağlantı veren bir QR kodu.

Hash kodları ve adresler için tek tip yazı tipi kullanın. Müşteriler bunları tek tek karakterlere bakarak zorlarlar ve Arial yazı tipinde sıfır ile büyük O harfi ikiz gibi görünür. Hash kodu çok genişse, satır sonuna getirin; 6 punto metin kimseye fayda sağlamaz. Yazı tiplerini gömün, dosyayı siparişle birlikte kaydedin ve muhasebeciniz makbuz istediğinde imzalayın.

Bunların hiçbiri parayı gerçekten alma kısmını kapsamıyor. O kısım için Plisio gibi bir ödeme geçidi kullanmanız gerekir. BTC, USDT ve diğer birçok kripto parayı kabul eder, faturayı oluşturur ve durum her değiştiğinde uç noktanızı çağırır. İşleyici, veriyi MigraDoc'a iletir ve alıcı, teşekkür sayfasındayken logonuzun bulunduğu bir makbuz alır.

Çözüm

PDFsharp'a sürekli geri dönmemin tek bir nedeni var: küçük ve yer kaplamayan bir yapıda olması. Core sürümü .NET'in çalıştığı her yerde çalışıyor ve canvas yeterli olmadığında MigraDoc düzenleme işini üstleniyor. Önceden karar vermeniz gereken üç şey: hangi sürüm, yazı tiplerinin nasıl yüklendiği ve 6.5 sürümünün AGPL lisansı almasıyla hangi lisansı kullandığınız. Web sayfaları değil, veri yazdırın, böylece yıllarca sorunsuz çalışacaktır.

Lena Hartmann

Lena Hartmann is a freelance tech writer and software engineer with over 9 years of experience in backend development and 5 years of hands-on work with smart contracts on Ethereum and other EVM chains. She writes about programming fundamentals, algorithms, compilers, and developer tooling, from beginner coding challenges to time complexity and blockchain infrastructure. Her guides explain technical concepts through working code and practical examples.