راهنمای PDFsharp: ایجاد فایل‌های PDF با MigraDoc و PdfSharpCore

PDFsharp یک کتابخانه متن‌باز دات‌نت برای ایجاد و ویرایش اسناد PDF از کد C# است. شما متن، خطوط و تصاویر را روی یک صفحه رسم می‌کنید، دستور Save را فراخوانی می‌کنید و یک فایل PDF خواهید داشت. نه موتور مرورگری وجود دارد و نه فایل باینری بومی. این پروژه به سال ۲۰۰۵ برمی‌گردد و بسیاری از فاکتورها، گزارش‌ها و گواهی‌هایی که امروزه از بک‌اندهای دات‌نت می‌آیند، هنوز از طریق آن ارسال می‌شوند.

من این را برای توسعه‌دهندگانی نوشتم که به فایل‌های PDF روی سرور نیاز دارند و می‌خواهند بدانند که با چه چیزی مواجه می‌شوند. ما نحوه‌ی ترکیب PDFsharp و MigraDoc با یکدیگر، کدام نسخه‌ها برای نصب، اولین فایل کاری، دردسر فونت در لینوکس، تغییر مجوز اخیر و نقطه‌ای که باید چیز دیگری را انتخاب کنید، را پوشش خواهیم داد.

PDFsharp چیست و چه کاری می‌تواند انجام دهد؟

پشت کتابخانه PDFsharp، empira Software GmbH قرار دارد، یک فروشگاه کوچک آلمانی که نزدیک به بیست سال است این محصول را زنده نگه داشته است. بیشتر وقت شما صرف یک کلاس می‌شود، XGraphics. اگر تا به حال با System.Drawing.Graphics نقاشی WinForms انجام داده باشید، ظرف ده دقیقه احساس راحتی خواهید کرد: فونت، قلم‌مو، x و y، شروع کنید.

از جعبه ای که دریافت می کنید:

• ایجاد اسناد PDF از ابتدا با متن، اشکال برداری، خطوط و تصاویر
• فایل‌های PDF موجود را باز کنید و به صفحات آنها محتوا اضافه کنید، مانند تمبر، واترمارک یا شماره صفحه
• ادغام و تقسیم اسناد با وارد کردن صفحات از یک فایل به فایل دیگر
• فونت‌ها را جاسازی و زیرمجموعه‌بندی کنید تا فایل در هر دستگاهی یکسان به نظر برسد
• اضافه کردن بوکمارک‌ها، لینک‌ها و ابرداده‌های سند مانند عنوان، نویسنده و کلمات کلیدی
• محافظت از فایل‌ها با رمز عبور و پرچم‌های مجوز
• اسناد را به صورت دیجیتالی امضا کنید (از نسخه ۶.۲ به بعد)

استقرار کسل‌کننده است، که منظورم تعریف است. همه چیز با کد مدیریت‌شده انجام می‌شود، بنابراین مسئول عملیات شما هرگز مجبور نیست کروم بی‌سروصدا را روی دستگاه قرار دهد یا ساعت ۲ بامداد دنبال یک DLL از Ghostscript بگردد. شما به یک بسته 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 مخصوص به خود را دارند.

بسته‌های فعلی، دات‌نت ۸، ۹ و ۱۰، به علاوه دات‌نت استاندارد ۲.۰ و دات‌نت فریم‌ورک ۴.۶.۲ را هدف قرار می‌دهند. بنابراین تقریباً هر چیزی که هنوز روی آن کار می‌شود، از یک ابزار قدیمی WinForms گرفته تا یک رابط برنامه‌نویسی کاربردی کاملاً جدید ASP.NET Core، پوشش داده شده است.

برنامه کنسول، API وب، داکر، توابع Azure، یا هر چیز دیگری روی لینوکس؟ ساخت هسته. GDI+ یا WPF فقط برای یک برنامه دسکتاپ ویندوز که در آن به فونت‌های سیستمی یا پیش‌نمایش در یک کنترل بومی نیاز دارید، منطقی هستند. شخصی در Stack Overflow یک بار پرسید که آیا برنامه کنسول آنها به نسخه WPF نیاز دارد یا خیر. اینطور نبود.

نحوه نصب PDFsharp از NuGet در Visual Studio

هنوز هم پست‌های انجمن از دوران WinForms را پیدا خواهید کرد که به شما می‌گویند یک فایل ZIP بگیرید، یک DLL پیدا کنید و خودتان مرجع را اضافه کنید. آنها را نادیده بگیرید. PDFsharp را از طریق NuGet نصب کنید؛ مدیر بسته نسخه‌ها را ردیابی می‌کند، بنابراین لازم نیست این کار را انجام دهید.

1. راه حل خود را در ویژوال استودیو باز کنید و روی پروژه در Solution Explorer کلیک راست کنید.
2. مدیریت بسته‌های NuGet را انتخاب کنید، به برگه مرور بروید و عبارت "PDFsharp" را جستجو کنید.
3. اگر به طرح‌بندی سند نیز نیاز دارید ، PDFsharp (Core build) یا PDFsharp-MigraDoc را انتخاب کنید. بررسی کنید که ناشر empira Software GmbH باشد.
4. روی نصب کلیک کنید و درخواست مجوز را بپذیرید.
5. پروژه را یک بار Build کنید تا از بازیابی صحیح بسته اطمینان حاصل شود.

کاربران ترمینال می‌توانند از کلیک کردن صرف نظر کنند:

اضافه کردن بسته به bash dotnet در dotnet، اضافه کردن بسته به PDFsharp در dotnet، PDFsharp-MigraDoc

در داخل کنسول مدیریت بسته‌ها (Package Manager Console) هم همین مورد وجود دارد: Install-Package PDFsharp. و لطفاً نسخه‌های مختلف را با هم قاطی نکنید. من شاهد بوده‌ام که یک تیم تمام بعدازظهر خود را صرف تداخل نوع داده کرده است، زیرا یک پروژه به PDFsharp ارجاع داده و پروژه همسایه‌اش PDFsharp-GDI را اجرا کرده است.

اولین سند PDF شما با PDFsharp در C

در زیر درباره کوچکترین برنامه‌ای که یک فایل PDF یک صفحه‌ای تولید می‌کند، آمده است. این برنامه روی نسخه Core هر سیستم عاملی اجرا می‌شود، البته تا زمانی که یک ابزار تشخیص فونت (font resolver) تنظیم شده باشد (بخش بعدی).

سی‌شارپ
با استفاده از PdfSharp.Drawing؛
با استفاده از PdfSharp.Pdf؛

// PDFsharp 6.5+ قبل از اولین استفاده نیاز به انتخاب مجوز دارد
PdfSharpLicense.SetAgplLicense();

متغیر document = new PdfDocument();
document.Info.Title = "سلام PDFsharp";

صفحه PdfPage = document.AddPage();
XGraphics gfx = XGraphics.FromPdfPage(page);

متغیر فونت = new XFont("Arial", 20, XFontStyleEx.Bold);
gfx.DrawString("سلام، PDFsharp!")، فونت، XBrushes.Black،
تابع XRect جدید (0، 0، عرض صفحه، ارتفاع صفحه)
XStringFormats.Center);

سند.ذخیره("hello.pdf");
```

هر برنامه‌ی PDFsharp از این شکل پیروی می‌کند: سند، صفحه، XGraphics، رسم، ذخیره. واحدها نقاط (1/72 اینچ) هستند و مبدا در گوشه‌ی بالا سمت چپ قرار دارد. در نسخه‌ی 6.2.x، خط مجوز را حذف کنید. این API فقط در نسخه‌ی 6.5.0 نمایش داده می‌شد.

و نسخه MigraDoc:

سی‌شارپ
با استفاده از MigraDoc.DocumentObjectModel؛
با استفاده از MigraDoc.Rendering؛

متغیر doc = سند جدید();
بخش بخش = doc.AddSection();
section.AddParagraph("سلام، MigraDoc!");

var renderer = PdfDocumentRenderer جدید { Document = doc };
رندرکننده.سند رندر();
renderer.PdfDocument.Save("hello-migradoc.pdf");
```

هیچ مختصاتی در هیچ کجا وجود ندارد. ۵۰۰ پاراگراف به آن اضافه کنید و هر تعداد صفحه که لازم باشد، بدون هیچ کد صفحه‌بندی، دریافت خواهید کرد.

فونت‌های موجود در نسخه اصلی PDFsharp: مشکل Resolver

اگر بپرسید، بیشترین شکایتی که خواهید شنید مربوط به فونت‌ها است. نسخه‌های GDI+ و WPF فقط فونت‌های TrueType نصب شده از ویندوز را می‌خوانند. نسخه Core نمی‌تواند چیزی را فرض کند، زیرا یک کانتینر باریک لینوکس اغلب هیچ فونت قابل استفاده‌ای ندارد. بنابراین اولین استقرار Docker معمولاً با یک استثنا در مورد عدم یافتن فونت مناسب به پایان می‌رسد.

راه حل، یک حل کننده فونت است، کلاسی که IFontResolver را پیاده سازی می کند. این کلاس دو متد دارد:

• ResolveTypeface یک خانواده و سبک درخواستی (مثلاً "Arial" و پررنگ) را به نام چهره نگاشت می‌کند.
• GetFont بایت‌های خام فایل TTF مربوط به آن نام چهره را برمی‌گرداند.

قبل از ایجاد اولین XFont، آن را یک بار در هنگام راه‌اندازی از طریق GlobalFontSettings.FontResolver ثبت کنید.

سی‌شارپ
کلاس عمومی 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 در پروژه نگه دارید و آنها را طوری تنظیم کنید که در پوشه خروجی کپی شوند، یا آنها را به عنوان منابع جاسازی کنید تا تصویر کانتینر همیشه آنها را داشته باشد.
• نسخه ۶.۲.۰، CoreBuildFontResolver قدیمی را حذف کرد. در ویندوز یا WSL2 می‌توانید رفتار مشابه را با GlobalFontSettings.UseWindowsFontsUnderWindows بازیابی کنید، اما این کار در لینوکس یا macOS هیچ کاری انجام نمی‌دهد.
• مخزن رسمی نمونه‌ها شامل یک SubstitutetingFontResolver است که می‌توانید به عنوان نقطه شروع آن را کپی کنید.
• قبل از جاسازی یک فونت تجاری در فایل‌های تولید شده، مجوز فونت را بررسی کنید. فونت‌های باز مانند Inter، Roboto یا Noto را به‌طور کامل از این سوال اجتناب کنید.

با وجود resolver، خروجی در ویندوز، لینوکس و macOS یکسان به نظر می‌رسد.

ادغام، امضا و ایمن‌سازی فایل‌ها با PDFsharp 6

بسیاری از تیم‌ها هرگز یک سند را از ابتدا تولید نمی‌کنند. آن‌ها از کتابخانه برای چسباندن، مهر زدن یا قفل کردن فایل‌هایی که از قبل وجود دارند استفاده می‌کنند. ادغام چند خط است: هر منبع را در حالت واردات باز کنید و صفحات را روی آن کپی کنید.

csharp متغیر خروجی = new PdfDocument(); foreach (متغیر مسیر در 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");

تقسیم‌بندی همان حلقه‌ی معکوس است، یک فایل خروجی در هر صفحه یا محدوده. برای محافظت، document.SecuritySettings یک رمز عبور کاربر، یک رمز عبور مالک و پرچم‌های مجوز (چاپ، کپی متن و غیره) را دریافت می‌کند.

دو ویژگی که مدت‌ها درخواست شده بودند بالاخره در خط ۶.۲ قرار گرفتند:

• امضاهای دیجیتال مبتنی بر CMS. یک امضاکننده پیش‌فرض در یک مجموعه جداگانه PDFsharp.Cryptography ارائه می‌شود و شما می‌توانید با پیاده‌سازی IDigitalSigner، امضای خودتان را اضافه کنید. پشتیبانی از سرور Timestamp در .NET مدرن کار می‌کند اما در نسخه .NET Framework کار نمی‌کند.
• خروجی PDF/A برای بایگانی. اسناد رسمی آن را به عنوان «با برخی محدودیت‌ها» توصیف می‌کنند و هنوز در دست ساخت است، بنابراین قبل از اتکا به آن برای انطباق، نتیجه را با یک بررسی‌کننده PDF/A اعتبارسنجی کنید.

این نسخه همچنین گلیف‌های ایموجی رنگی و پیاده‌سازی مدیریت‌شده‌ی MD5 را به ارمغان آورد، که چه تحت قوانین FIPS و چه در Blazor اهمیت دارد.

مخزن PDFsharp، فورک‌های PdfSharpCore و نسخه‌های ۱.x

در گیت‌هاب عبارت PDFsharp را جستجو کنید، تعداد انگشت‌شماری پروژه با تقریباً همین نام پیدا خواهید کرد. تقصیر را گردن تاریخ بیندازید.

نسخه قدیمی ۱.x (۱.۵۰، ۱.۵۱) فقط روی .NET Framework اجرا می‌شد. وقتی .NET Core منتشر شد، مردم حوصله منتظر ماندن را نداشتند، بنابراین خودشان آن را پورت کردند. PdfSharpCore که توسط استفان استایگر شروع شد و بعداً توسط سایر انشعاب‌ها نیز مورد استفاده قرار گرفت، همانی است که اکثر مردم می‌شناسند. این نسخه GDI+ را حذف کرد و کد را سال‌ها قبل از انتشار رسمی روی لینوکس اجرا کرد.

سپس PDFsharp 6 از راه رسید: یک بازنویسی درست و حسابی روی دات‌نت مدرن با یک ساختار اصلی چند پلتفرمی رسمی. انشعاب‌ها بیشتر دلیل وجودی خود را از دست دادند.

خب، تاپیک «PdfSharp در مقابل PdfSharpCore» که مدام در ردیت نمایش داده می‌شود؟ پروژه جدید، بسته‌های رسمی. فقط در صورتی از یک انشعاب استفاده کنید که کد قدیمی از قبل به آن متکی باشد و مهاجرت در حال حاضر ارزش یک جهش سریع را نداشته باشد. و وقتی اسناد کم هستند، به مخزن نمونه‌های جداگانه empira بروید. پوشه‌ها و فایل‌های آن نمونه‌های قابل اجرا هستند که حدس زدن را آسان‌تر می‌کند.

آیا PDFsharp رایگان است؟ تغییرات مجوز در PDFsharp 6.5

در بیشتر دوران حیاتش، بله. تحت لیسانس MIT بود، که به معنی استفاده تجاری تقریباً بدون هیچ قید و شرطی است. هر نسخه‌ای تا نسخه ۶.۲.۴ و از جمله آن، هنوز هم همینطور است.

نسخه ۶.۵.۰ این وضعیت را تغییر داد. این کتابخانه اکنون دارای مجوز دوگانه است:

• AGPL (رایگان). شما می‌توانید آن را با فراخوانی PdfSharpLicense.SetAgplLicense() قبل از استفاده از کتابخانه فعال کنید. AGPL شما را ملزم می‌کند که کد منبع خود را در دسترس کاربران، از جمله کاربرانی که از طریق شبکه با نرم‌افزار شما تعامل دارند، قرار دهید، بنابراین برای SaaS متن‌باز مناسب نیست.
• مجوز تجاری. شما یک کلید مجوز از فروشنده می‌خرید و آن را با PdfSharpLicense.LoadLicense(...) بارگذاری می‌کنید. این کار الزامات AGPL را حذف می‌کند.

از نسخه ۶.۵.۰ به بعد، کد شما باید صریحاً یکی را انتخاب کند. پیش‌نمایش‌های نسخه ۷.۰ نیز به همین روش کار می‌کنند.

در عمل:

• پروژه‌های متن‌باز سازگار با AGPL می‌توانند به صورت رایگان از جدیدترین نسخه استفاده کنند.
• محصولات متن‌باز می‌توانند یا مجوز تجاری بخرند یا روی نسخه ۶.۲.x که تحت نظر MIT است، بمانند. ماندن در این وضعیت به معنای از دست دادن اصلاحات آینده است، بنابراین هزینه آن را صادقانه بسنجید.
• هر چه را که انتخاب می‌کنید، متن مجوز اصلی را بخوانید و از تیم حقوقی خود بخواهید آن را امضا کنند. این راهنما، مشاوره حقوقی نیست.

نقاط ضعف PDFsharp و ترکیب آن با چه مواردی

این کتابخانه کارش را به خوبی انجام می‌دهد. فقط کار کمی محدود است و در هر تاپیک انجمن، شکاف‌های مشابهی پیش می‌آید.

• تبدیل HTML به PDF وجود ندارد. PDFsharp HTML یا CSS را رندر نمی‌کند. یک افزونه‌ی انجمنی به نام HtmlRenderer.PdfSharp وجود دارد اما فقط از HTML 4.01 و CSS سطح ۲ پشتیبانی می‌کند، بنابراین طرح‌بندی‌های مدرن با flexbox یا grid دوام نخواهند آورد. تیم‌هایی که به قالب‌های HTML نیاز دارند، معمولاً به جای آن به سراغ یک رندرکننده‌ی مرورگر بدون سربرگ می‌روند.
• بدون جاوا اسکریپت. نمودارها یا محتوای ساخته شده در سمت کلاینت قابل ضبط نیستند.
• رندر تصاویر امکان‌پذیر نیست. PDFsharp نمی‌تواند یک صفحه PDF را برای تصاویر کوچک یا پیش‌نمایش به PNG تبدیل کند. برای این کار به یک رسترایزر جداگانه نیاز دارید.
• استخراج متن محدود. می‌توانید جریان محتوا را پیمایش کنید، اما هیچ API سطح بالایی وجود ندارد که متن تمیز با موقعیت‌ها را برگرداند. PdfPig، یک کتابخانه منبع باز جداگانه، به طور خاص برای خواندن و استخراج متن ساخته شده است.
• پشتیبانی جزئی از فرم. پر کردن فرم‌های ساده با AcroForm کار می‌کند؛ فرم‌های پیچیده با اسکریپت‌ها داستان دیگری دارند.
• جداول به MigraDoc نیاز دارند. با PDFsharp ساده، خودتان ارتفاع هر ردیف را محاسبه می‌کنید.

این موضوع آن را به یک انتخاب بد تبدیل نمی‌کند. اسناد مبتنی بر داده مانند فاکتورها، صورتحساب‌ها، برچسب‌ها و گواهینامه‌ها دقیقاً نقطه قوت آن هستند و حجم کمی را اشغال می‌کنند. کپی‌های پیکسلی بی‌نقص از صفحات وب اینطور نیستند.

PDFsharp برای فاکتورها و رسیدهای پرداخت رمزنگاری شده

رسیدها احتمالاً رایج‌ترین چیزی هستند که مردم با PDFsharp می‌سازند. رسیدهای کریپتو کمی پیچیده‌تر از رسیدهای کارت هستند. خبر خوب: به محض اینکه درگاه به وب‌هوک شما (یک فراخوانی HTTP که هنگام تغییر وضعیت پرداخت ارسال می‌شود) برسد، تمام داده‌ها را دارید. هیچ چیز اضافی برای جستجو وجود ندارد.

چیزی که من روی یکی از آنها می‌گذاشتم:

• شناسه سفارش یا فاکتور و جزئیات فروشنده
• مبلغ به صورت ارز دیجیتال و معادل فیات آن در لحظه پرداخت
• کوین و شبکه (برای مثال، USDT روی ترون در مقابل USDT روی اتریوم)
• هش تراکنش، تا مشتری بتواند آن را در یک کاوشگر بلوک تأیید کند
• آدرس کیف پول گیرنده کوتاه شده و زمان تأیید
• یک کد QR که به صفحه تراکنش یا فاکتور لینک می‌شود

برای هش‌ها و آدرس‌ها از مونواسپیس استفاده کنید. مشتریان با دقت به آنها نگاه می‌کنند، و در فونت Arial یک صفر و یک O بزرگ شبیه دوقلو به نظر می‌رسند. اگر هش خیلی پهن است، آن را بپوشانید؛ متن با اندازه ۶pt به کسی کمکی نمی‌کند. فونت‌ها را جاسازی کنید، فایل را همراه با سفارش ذخیره کنید و اگر حسابدارتان رسید خواست، آن را امضا کنید.

هیچ‌کدام از این‌ها شامل دریافت پول نمی‌شود. برای آن قطعه، شما یک درگاه مانند Plisio را وصل می‌کنید. این درگاه، بیت‌کوین، تتر و کلی سکه دیگر را دریافت می‌کند، فاکتور را صادر می‌کند و هر بار که وضعیت تغییر می‌کند، با نقطه پایانی شما تماس می‌گیرد. مسئول شما، محموله را به MigraDoc ارسال می‌کند و خریدار در حالی که هنوز در صفحه تشکر است، رسیدی با لوگوی شما دریافت می‌کند.

نتیجه‌گیری

من مدام به یک دلیل به PDFsharp برمی‌گردم: کوچک است و مزاحم کار نمی‌شود. نسخه Core هر جایی که .NET اجرا می‌شود، اجرا می‌شود و MigraDoc وقتی یک canvas کافی نباشد، کار طرح‌بندی را انجام می‌دهد. سه نکته را باید از همان ابتدا مشخص کنید: کدام نسخه، چگونه فونت‌ها بارگذاری می‌شوند، و حالا که نسخه ۶.۵ به 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.