دليل PDFsharp: إنشاء ملفات PDF باستخدام MigraDoc وPdfSharpCore

PDFsharp مكتبة مفتوحة المصدر لبيئة .NET لإنشاء وتعديل ملفات PDF باستخدام لغة C#. يمكنك رسم النصوص والخطوط والصور على الصفحة، ثم حفظ الملف، لتحصل على ملف PDF جاهز. لا حاجة لمتصفح أو برنامج تشغيل أصلي. يعود تاريخ المشروع إلى عام 2005، ولا تزال العديد من الفواتير والتقارير والشهادات الصادرة من أنظمة .NET الخلفية تعتمد عليه حتى اليوم.

كتبتُ هذا الدليل للمطورين الذين يحتاجون إلى ملفات PDF على الخادم ويرغبون في معرفة تفاصيلها. سنتناول كيفية عمل PDFsharp وMigraDoc معًا، وأي إصدار يجب تثبيته، وكيفية إنشاء ملف تجريبي، ومشاكل الخطوط على نظام Linux، والتغيير الأخير في الترخيص، والنقطة التي يُنصح فيها باختيار بديل.

ما هو برنامج PDFsharp وماذا يمكنه أن يفعل؟

تقف وراء مكتبة PDFsharp شركة empira Software GmbH، وهي شركة ألمانية صغيرة حافظت على استمراريتها لما يقارب العشرين عامًا. يُخصص معظم وقتك لفئة واحدة، وهي XGraphics. إذا سبق لك استخدام الرسم في WinForms باستخدام System.Drawing.Graphics، فستشعر بالراحة التامة في غضون عشر دقائق: الخط، الفرشاة، إحداثيات س و ص، وانطلق.

ستحصل عند فتح العلبة على:

• أنشئ مستندات PDF من الصفر باستخدام النصوص والأشكال المتجهة والخطوط والصور
• افتح ملفات PDF الموجودة وأضف محتوى إلى صفحاتها، مثل الطوابع أو العلامات المائية أو أرقام الصفحات.
• دمج وتقسيم المستندات عن طريق استيراد الصفحات من ملف إلى آخر
• قم بتضمين الخطوط وتقسيمها بحيث يبدو الملف متطابقًا على جميع الأجهزة
• أضف الإشارات المرجعية والروابط وبيانات تعريف المستند مثل العنوان والمؤلف والكلمات المفتاحية.
• قم بحماية الملفات باستخدام كلمات المرور وعلامات الأذونات.
• التوقيع على المستندات رقميًا (منذ إصدار 6.2)

عملية النشر سلسة للغاية، وهذا في رأيي مدح. كل شيء عبارة عن كود مُدار، لذا لن يضطر مسؤول العمليات لديك أبدًا إلى تثبيت متصفح كروم بدون واجهة رسومية على جهاز أو البحث عن ملف Ghostscript DLL في الساعة الثانية صباحًا. كل ما عليك فعله هو الإشارة إلى حزمة NuGet واحدة، ثم دفعها، وانتهى الأمر.

والآن، إليكم المشكلة. ستحصلون على مساحة للكتابة فقط، لا أكثر. هل تصل فقرة طويلة إلى الهامش السفلي؟ هذه مشكلتكم. هل يتجاوز الجدول الصفحة الأولى؟ هذه مشكلتكم أيضاً، إلا إذا استخدمتم برنامج MigraDoc.

PDFsharp و MigraDoc: أي طبقة تحتاج؟

نفس المورّد، نفس جدول الإصدارات، وظائف مختلفة تمامًا. يعمل برنامج MigraDoc Foundation في الطابق العلوي من PDFsharp. بدلًا من تحديد مكان نص معين، تُزوّده بالأقسام والفقرات والجداول والرؤوس والتذييلات والأنماط، وحتى بعض المخططات، وهو يتولى تحديد مكان كل عنصر. والنتيجة ملف PDF. أو RTF، للزميل الذي يُصرّ على فتح كل شيء في برنامج Word.

باختصار: PDFsharp تعني "ضع هذا النص عند x=40، y=120". أما MigraDoc فتعني "هذه ثلاثون صفًا وعنوان يتكرر، قم بترتيب الصفحات".

غالباً ما تنتهي المشاريع الحقيقية باستخدام كليهما. نص أساسي عبر MigraDoc، وغلاف مرسوم يدوياً أو ختم على ملف PDF من أحد الموردين عبر الطبقة السفلية. لا يمكنك تجنب تثبيت PDFsharp على أي حال، لأن حزمة MigraDoc تتضمنه كجزء من المتطلبات.

شرح بناء PDFsharp: البناء الأساسي، وGDI+، وWPF

عادةً ما يواجه المستخدمون الجدد صعوبة في تثبيت الحزمة التالية في قائمة NuGet. يأتي PDFsharp 6 بثلاث إصدارات، لكل منها نسخة MigraDoc مماثلة.

تستهدف الحزم الحالية إصدارات .NET 8 و9 و10، بالإضافة إلى .NET Standard 2.0 و.NET Framework 4.6.2. لذا فهي تغطي تقريبًا كل ما لا يزال قيد التطوير، بدءًا من أداة WinForms القديمة وصولًا إلى واجهة برمجة تطبيقات ASP.NET Core الجديدة كليًا.

تطبيق وحدة تحكم، واجهة برمجة تطبيقات ويب، Docker، Azure Functions، أي شيء على Linux؟ بناء أساسي. GDI+ أو WPF مناسبان فقط لتطبيق سطح مكتب Windows حيث تريد خطوط النظام أو معاينة في عنصر تحكم أصلي. سأل أحدهم على Stack Overflow ذات مرة عما إذا كان تطبيق وحدة التحكم الخاص به يحتاج إلى إصدار WPF. لم يكن كذلك.

كيفية تثبيت PDFsharp من NuGet في Visual Studio

ستجد منشورات في المنتديات من حقبة WinForms تنصحك بتحميل ملف ZIP، واستخراج ملف DLL، وإضافة المرجع بنفسك. تجاهل هذه المنشورات. ثبّت PDFsharp عبر NuGet؛ فمدير الحزم يتتبع الإصدارات، لذا لن تحتاج إلى ذلك.

1. افتح الحل الخاص بك في Visual Studio وانقر بزر الماوس الأيمن على المشروع في مستكشف الحلول.
2. اختر إدارة حزم NuGet ، ثم انتقل إلى علامة التبويب استعراض ، وابحث عن "PDFsharp".
3. اختر PDFsharp (الإصدار الأساسي) أو PDFsharp-MigraDoc إذا كنت بحاجة أيضًا إلى تنسيق المستند. تأكد من أن الناشر هو empira Software GmbH.
4. انقر فوق "تثبيت " واقبل مطالبة الترخيص.
5. قم ببناء المشروع مرة واحدة للتأكد من استعادة الحزمة بشكل صحيح.

يمكن لمستخدمي الأجهزة الطرفية تخطي عملية النقر:

bash dotnet add package PDFsharp dotnet add package PDFsharp-MigraDoc

في وحدة تحكم إدارة الحزم، يوجد الأمر نفسه: Install-Package PDFsharp. ويرجى عدم خلط الإصدارات. لقد شاهدتُ فريقًا يُضيّع عصرًا كاملًا بسبب تعارضات في أنواع البيانات، لأن أحد المشاريع كان يُشير إلى PDFsharp بينما كان المشروع المجاور يستخدم PDFsharp-GDI.

أول مستند PDF لك باستخدام PDFsharp بلغة C

فيما يلي أصغر برنامج تقريبًا يُنتج ملف PDF من صفحة واحدة. يعمل هذا البرنامج على إصدار Core على أي نظام تشغيل، طالما تم إعداد مُحلِّل الخطوط (القسم التالي).

```csharp
باستخدام PdfSharp.Drawing؛
باستخدام PdfSharp.Pdf؛

يتطلب برنامج PDFsharp 6.5+ اختيار ترخيص قبل الاستخدام الأول
PdfSharpLicense.SetAgplLicense();

var document = new PdfDocument();
document.Info.Title = "مرحباً PDFsharp";

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

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

document.Save("hello.pdf");
```

يتبع كل برنامج PDFsharp هذا النمط: مستند، صفحة، XGraphics، رسم، حفظ. الوحدات هي نقاط (1/72 بوصة) ونقطة الأصل في الزاوية العلوية اليسرى. في الإصدار 6.2.x، احذف سطر الترخيص. ظهرت واجهة برمجة التطبيقات هذه فقط في الإصدار 6.5.0.

ونسخة MigraDoc:

```csharp
باستخدام MigraDoc.DocumentObjectModel؛
باستخدام MigraDoc.Rendering؛

var doc = new Document();
القسم section = doc.AddSection();
section.AddParagraph("مرحباً، MigraDoc!");

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

لا توجد إحداثيات في أي مكان. ضع 500 فقرة وستحصل على عدد الصفحات الذي يتطلبه ذلك، دون أي كود ترقيم صفحات من جانبك.

الخطوط في إصدار PDFsharp الأساسي: مشكلة المُحلِّل

إذا سألت من حولك، ستجد أن أكثر الشكاوى شيوعًا هي الخطوط. تعتمد إصدارات GDI+ وWPF على قراءة خطوط TrueType المثبتة من نظام Windows. أما إصدار Core فلا يمكنه افتراض أي شيء، لأن حاوية Linux المصغّرة غالبًا لا تحتوي على أي خطوط قابلة للاستخدام. لذا، غالبًا ما ينتهي أول نشر لـ Docker بظهور خطأ يفيد بعدم العثور على خط مناسب.

الحل هو مُحلِّل الخطوط، وهو فئة تُطبِّق واجهة IFontResolver. يحتوي على طريقتين:

• تقوم دالة ResolveTypeface بربط عائلة ونمط مطلوبين (على سبيل المثال، "Arial"، غامق) باسم الخط
• تُعيد الدالة GetFont البايتات الخام لملف TTF الخاص باسم الخط هذا

قم بتسجيله مرة واحدة عند بدء التشغيل عبر GlobalFontSettings.FontResolver، قبل إنشاء أول XFont.

```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();
```

أمورٌ يجدر معرفتها قبل أن تصطدم بها بنفسك:

• احتفظ بملفات TTF الخاصة بك في مجلد Fonts في المشروع وقم بتعيينها للنسخ إلى دليل الإخراج، أو قم بتضمينها كموارد بحيث تحتوي صورة الحاوية دائمًا عليها.
• أزال الإصدار 6.2.0 مُحلِّل الخطوط CoreBuildFontResolver القديم. في نظامي التشغيل Windows وWSL2، يُمكن استعادة سلوك مشابه باستخدام GlobalFontSettings.UseWindowsFontsUnderWindows، ولكن هذا لا يُجدي نفعًا في نظامي التشغيل Linux أو macOS.
• يحتوي مستودع العينات الرسمي على SubstitutetingFontResolver يمكنك نسخه كنقطة بداية.
• تحقق من ترخيص الخط قبل تضمين أي خط تجاري في الملفات المُنشأة. الخطوط المفتوحة مثل Inter وRoboto وNoto تتجنب هذه المشكلة تمامًا.

مع وجود المُحلِّل، تبدو المخرجات متطابقة على أنظمة التشغيل Windows وLinux وmacOS.

دمج الملفات وتوقيعها وتأمينها باستخدام PDFsharp 6

كثير من الفرق لا تُنشئ مستندًا من الصفر أبدًا، بل تستخدم المكتبة لدمج أو ختم أو قفل الملفات الموجودة مسبقًا. عملية الدمج لا تتطلب سوى بضعة أسطر: افتح كل مصدر في وضع الاستيراد وانسخ الصفحات.

في لغة C#، يتم إنشاء كائن PdfDocument جديد، ثم يتم حفظه باستخدام حلقة تكرارية على كل مسار في مصفوفة جديدة.

عملية التقسيم هي نفس العملية العكسية، حيث يتم إنشاء ملف إخراج واحد لكل صفحة أو نطاق. ولأغراض الحماية، تتطلب خاصية document.SecuritySettings كلمة مرور المستخدم، وكلمة مرور المالك، وعلامات الأذونات (الطباعة، ونسخ النص، وما إلى ذلك).

تم أخيرًا إضافة ميزتين طال انتظارهما إلى سلسلة الإصدارات 6.2:

• التوقيعات الرقمية المستندة إلى نظام إدارة المحتوى (CMS). يتوفر مُوقِّع افتراضي في حزمة PDFsharp.Cryptography منفصلة، ويمكنك إضافة مُوقِّع خاص بك عن طريق تطبيق واجهة IDigitalSigner. يدعم خادم الطابع الزمني الإصدارات الحديثة من .NET، ولكنه لا يدعم إصدارات .NET Framework.
• يُستخدم ملف PDF/A للإخراج لأغراض الأرشفة. تشير الوثائق الرسمية إلى أنه يعمل "مع بعض القيود" وما زال قيد التطوير، لذا يُرجى التحقق من صحة النتيجة باستخدام مدقق PDF/A قبل الاعتماد عليه لأغراض الامتثال.

وقد جلب هذا الإصدار أيضًا رموزًا تعبيرية ملونة وتطبيقًا مُدارًا لـ MD5، وهو أمر مهم إذا كنت تعمل بموجب قواعد FIPS أو في Blazor.

مستودع PDFsharp، ونسخ PdfSharpCore المتفرعة، والإصدارات 1.x

ابحث في GitHub عن PDFsharp وستجد عدداً من المشاريع التي تحمل نفس الاسم تقريباً. السبب هو التاريخ.

كانت الإصدارات القديمة من سلسلة 1.x (1.50، 1.51) تعمل فقط على .NET Framework. عندما صدر .NET Core، لم يرغب المستخدمون في الانتظار، فقاموا بنقله بأنفسهم. يُعد PdfSharpCore، الذي بدأه ستيفان ستايغر وتبنته لاحقًا نسخ أخرى، هو الأكثر شهرة. لقد استغنى عن GDI+ وجعل الكود يعمل على نظام Linux قبل سنوات من الإصدار الرسمي.

ثم ظهر PDFsharp 6: إعادة كتابة كاملة باستخدام .NET الحديثة مع إصدار Core رسمي متعدد المنصات. فقدت النسخ المتفرعة معظم مبرراتها.

إذن، هل تقصد موضوع "PdfSharp مقابل PdfSharpCore" الذي يظهر باستمرار على ريديت؟ مشروع جديد، حزم رسمية. احتفظ بنسخة معدلة فقط إذا كان الكود القديم يعتمد عليها بالفعل، ولا يستحق التحديث الآن. وعندما تشعر أن التوثيق غير كافٍ، انتقل إلى مستودع الأمثلة الخاص بـ empira. مجلداته وملفاته عبارة عن أمثلة قابلة للتنفيذ، مما يغنيك عن التخمين.

هل برنامج PDFsharp مجاني؟ تغييرات الترخيص في PDFsharp 6.5

نعم، كان البرنامج مرخصًا بموجب ترخيص MIT طوال معظم فترة استخدامه. وهذا يعني إمكانية استخدامه تجاريًا دون أي قيود تقريبًا. ولا تزال جميع الإصدارات حتى الإصدار 6.2.4 مرخصة بموجب هذا الترخيص.

غيّر الإصدار 6.5.0 ذلك. أصبحت المكتبة الآن مرخصة بترخيص مزدوج:

• رخصة AGPL (مجانية). يمكنك تفعيلها باستدعاء الدالة PdfSharpLicense.SetAgplLicense() قبل استخدام المكتبة. تتطلب رخصة AGPL إتاحة شفرة المصدر للمستخدمين، بمن فيهم المستخدمون الذين يتفاعلون مع برنامجك عبر الشبكة، لذا فهي غير مناسبة لبرامج SaaS مغلقة المصدر.
• رخصة تجارية. تشتري مفتاح ترخيص من البائع وتقوم بتحميله باستخدام PdfSharpLicense.LoadLicense(...). هذا يُلغي التزامات رخصة AGPL.

ابتداءً من الإصدار 6.5.0، يجب على التعليمات البرمجية الخاصة بك اختيار أحد الخيارات بشكل صريح. وتعمل معاينات الإصدار 7.0 بنفس الطريقة.

عملياً:

• يمكن للمشاريع مفتوحة المصدر المتوافقة مع رخصة AGPL الاستمرار في استخدام أحدث إصدار مجانًا.
• يمكن للمنتجات ذات المصادر المغلقة إما شراء ترخيص تجاري أو البقاء على الإصدار 6.2.x، الذي لا يزال خاضعًا لترخيص MIT. البقاء على الإصدار الحالي يعني تفويت التحديثات المستقبلية، لذا فكّر في هذا الأمر بصدق.
• مهما كان اختيارك، اقرأ نص الترخيص الأصلي واحصل على موافقة فريقك القانوني. هذا الدليل ليس استشارة قانونية.

نقاط ضعف PDFsharp وما يمكن استخدامه معه

تؤدي المكتبة وظيفتها على أكمل وجه، إلا أن نطاق عملها محدود، وتظهر نفس الثغرات في كل موضوع من مواضيع المنتديات.

• لا يدعم PDFsharp تحويل HTML إلى PDF. فهو لا يُنشئ صفحات HTML أو CSS. توجد إضافة مجتمعية، HtmlRenderer.PdfSharp، لكنها تدعم فقط HTML 4.01 وCSS المستوى 2، لذا لن تعمل معها التصاميم الحديثة التي تستخدم Flexbox أو Grid. عادةً ما تلجأ الفرق التي تحتاج إلى قوالب HTML إلى مُنشئ صفحات يعمل بدون واجهة رسومية.
• ممنوع استخدام جافا سكريبت. لا يمكن التقاط الرسوم البيانية أو المحتوى المُنشأ على جانب العميل.
• لا يدعم PDFsharp تحويل صفحات PDF إلى صور PNG لعرض الصور المصغرة أو المعاينات. أنت بحاجة إلى برنامج تحويل الصور النقطية (الراسم) لهذا الغرض.
• استخراج النصوص محدود. يمكنك استعراض محتوى الصفحة، لكن لا توجد واجهة برمجة تطبيقات (API) متطورة تُعيد نصًا نظيفًا مع تحديد المواقع. مكتبة PdfPig، وهي مكتبة مفتوحة المصدر منفصلة، مصممة خصيصًا لقراءة النصوص واستخراجها.
• دعم جزئي للنماذج. تعبئة نماذج AcroForm البسيطة تعمل؛ أما النماذج المعقدة التي تحتوي على نصوص برمجية فهي قصة أخرى.
• تحتاج الجداول إلى MigraDoc. أما مع PDFsharp العادي، فيمكنك حساب ارتفاع كل صف بنفسك.

هذا لا يجعله خيارًا سيئًا. فالمستندات التي تعتمد على البيانات، مثل الفواتير والبيانات والملصقات والشهادات، هي مجال تخصصه الأمثل، وحجمه صغير جدًا. أما النسخ الدقيقة لصفحات الويب فليست كذلك.

PDFsharp لفواتير العملات الرقمية وإيصالات الدفع

تُعدّ الإيصالات على الأرجح أكثر العناصر شيوعًا التي يُنشئها المستخدمون باستخدام PDFsharp. تتطلب إيصالات العملات الرقمية بعض الجهد الإضافي مقارنةً بإيصالات البطاقات. لكن الخبر السار هو: بمجرد أن تتصل بوابة الدفع بخطاف الويب الخاص بك (وهو رد اتصال HTTP يُرسل عند تغيير حالة الدفع)، ستكون جميع البيانات جاهزة. لا حاجة للبحث عن أي شيء إضافي.

ما سأضعه على واحدة:

• رقم الطلب أو الفاتورة وتفاصيل التاجر
• المبلغ بالعملة المشفرة وما يعادلها من العملات الورقية وقت الدفع
• العملة والشبكة (على سبيل المثال، USDT على TRON مقابل USDT على Ethereum)
• تجزئة المعاملة، حتى يتمكن العميل من التحقق منها على مستكشف الكتل
• عنوان محفظة استلام مختصر ووقت التأكيد
• رمز الاستجابة السريعة (QR) الذي يربط بصفحة المعاملة أو الفاتورة

يُستخدم الخط ذو المسافة الثابتة للرموز (الهاش) والعناوين. يُحدّق العملاء فيها حرفًا حرفًا، وفي خط Arial يبدو الصفر وحرف O الكبير متشابهين. إذا كان الرمز (الهاش) عريضًا جدًا، فقم بلفّه؛ فالنص بحجم 6 نقاط لا يُفيد أحدًا. قم بتضمين الخطوط، واحفظ الملف مع الطلب، ووقّعه إذا طلب منك المحاسب إيصالات.

لا يشمل ذلك استلام الأموال فعليًا. في هذه المرحلة، يمكنك استخدام بوابة مثل Plisio . تقبل هذه البوابة عملات البيتكوين (BTC) والتيثرنت (USDT) والعديد من العملات الأخرى، وتُصدر الفاتورة، وتتصل بنقطة النهاية الخاصة بك كلما تغيرت حالة المعاملة. يقوم معالجك بتمرير البيانات إلى MigraDoc، ويحصل المشتري على إيصال يحمل شعارك أثناء وجوده في صفحة الشكر.

خاتمة

أعود دائمًا إلى PDFsharp لسبب واحد: صغر حجمه وسهولة استخدامه. يعمل الإصدار الأساسي في أي بيئة .NET، ويتولى MigraDoc مهمة التنسيق عندما لا تكفي لوحة الرسم. هناك ثلاثة أمور يجب تحديدها مبكرًا: أي إصدار، وكيفية تحميل الخطوط، ونوع الترخيص الذي تستخدمه الآن بعد أن أصبح الإصدار 6.5 مرخصًا بموجب رخصة AGPL. اطبع البيانات، وليس صفحات الويب، وسيبقى البرنامج فعالًا لسنوات.

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.