iTextSharp لـ C# (.NET): دليل شامل مع أمثلة عملية

مقدمة عن iTextSharp: ما هي ولماذا تستخدمها

iTextSharp هي مكتبة قوية لإنشاء ومعالجة مستندات PDF على منصة .NET (C#, VB.NET, F#). وهي نسخة منقولة من مكتبة iText الشهيرة بلغة Java، وتمنح المطورين تحكمًا كاملاً في إنشاء وتعديل وقراءة ملفات PDF.

أهم ميزات iTextSharp:

• إنشاء مستندات PDF من الصفر
• إضافة نصوص، صور، جداول، قوائم
• التعامل مع الخطوط (بما في ذلك العربية و Unicode)
• إدراج روابط تشعبية، إشارات مرجعية، بيانات وصفية
• تشفير وحماية بكلمة مرور
• دمج وتقسيم ملفات PDF
• إضافة علامات مائية ورؤوس وتذييلات
• التعامل مع النماذج (AcroForms)

تُستخدم المكتبة على نطاق واسع في التطبيقات المؤسسية لإنشاء التقارير والفواتير وسندات الشحن والشهادات والمستندات الأخرى. تدعم iTextSharp .NET Framework 2.0+ و .NET Core (عبر iTextSharp.LGPLv2.Core).

تثبيت iTextSharp

لتثبيت iTextSharp في مشروع .NET، استخدم مدير الحزم NuGet. تتوفر عدة إصدارات من المكتبة:

• iTextSharp (الإصدار القديم 5.x، رخصة LGPL) — مجاني ولكن مع بعض القيود
• iTextSharp.LGPLv2.Core — نسخة معدلة لـ .NET Core / .NET 5+
• iText7 (iText.LGPLv2.Core) — الإصدار الجديد iText 7 لـ .NET

التثبيت عبر Package Manager Console:

Install-Package iTextSharp.LGPLv2.Core -Version 1.7.0

التثبيت عبر .NET CLI:

dotnet add package iTextSharp.LGPLv2.Core --version 1.7.0

التثبيت عبر واجهة NuGet في Visual Studio:

1. انقر بزر الماوس الأيمن على المشروع → "Manage NuGet Packages"
2. ابحث عن: "iTextSharp.LGPLv2.Core"
3. اختر الإصدار واضغط "Install"

ملاحظة مهمة: للتعامل مع الخطوط العربية أو الخطوط غير القياسية الأخرى، ستحتاج إلى إعدادات إضافية (راجع قسم "نصائح").

بداية سريعة: إنشاء أول مستند PDF

لنلقِ نظرة على مثال بسيط لإنشاء ملف PDF يحتوي على نص "Hello, World!":

using System.IO;
using iTextSharp.text;
using iTextSharp.text.pdf;

class Program
{
    static void Main()
    {
        // إنشاء المستند
        Document doc = new Document();
        
        // إنشاء تيار للكتابة في الملف
        using (FileStream fs = new FileStream("HelloWorld.pdf", FileMode.Create))
        {
            // الحصول على مثيل من PdfWriter
            PdfWriter writer = PdfWriter.GetInstance(doc, fs);
            
            // فتح المستند
            doc.Open();
            
            // إضافة فقرة نصية
            doc.Add(new Paragraph("Hello, World!"));
            
            // إغلاق المستند
            doc.Close();
        }
        
        Console.WriteLine("تم إنشاء PDF بنجاح!");
    }
}

سينشئ هذا الكود ملفًا باسم HelloWorld.pdf في مجلد التطبيق. لاحظ التسلسل: إنشاء Document → فتح → إضافة محتوى → إغلاق.

الدوال والوظائف الأساسية في iTextSharp

دعنا نستعرض 10 دوال/كلاسات رئيسية في المكتبة مع شرح وأمثلة تفصيلية.

1. كلاس Document

الوظيفة: يمثل مستند PDF نفسه. يدير الصفحات والهوامش والاتجاه.

معاملات المُنشئ:

• Rectangle pageSize — حجم الصفحة (مثل PageSize.A4)
• float marginLeft, marginRight, marginTop, marginBottom — الهوامش

مثال:

// إنشاء مستند بحجم A4 واتجاه أفقي وهوامش مخصصة
Document doc = new Document(PageSize.A4.Rotate(), 50, 50, 30, 30);
doc.Open();
doc.Add(new Paragraph("اتجاه أفقي"));
doc