💡 مثال کامل کارآمد در GitHub موجود است: one-line-document-merge-and-split-dotnet

جایی که کارهای اسناد پشت‌دفتر واقعاً انجام می‌شوند

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

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

GroupDocs.Merger.LowCode یک بسته .NET است که یک کار مانند ترکیب، تقسیم یا حذف صفحه را به یک فراخوانی سازنده تبدیل می‌کند و از کلاس عمومی Merger که این کارها به آن نیازی ندارند، جدا می‌شود. هر یک از هفت محصول آن منبع و گزینه‌ها را در سازنده می‌گیرد، در C#، و فقط زمانی که Save فراخوانی شود اجرا می‌شود؛ شکل یکسانی دارد چه کار بر روی PDF باشد، چه سند Word یا ارائه PowerPoint.

چرا راه‌حل‌های کلی اینجا کار نمی‌کنند

تیم‌ها که با یکی از این کارها مواجه می‌شوند معمولاً قبل از استفاده از یک بسته متمرکز، یکی از سه کار زیر را انجام می‌دهند:

  • انجام کار به‌صورت دستی در یک ویرایشگر دسکتاپ: برای یک سند مناسب است، زمان‌بندی‌پذیر نیست و هیچ‌کس نمی‌خواهد یک گام دستی را در ساعت ۲ بامداد تأیید کند.
  • نوشتن اسکریپت یک‌بار برای APIهای فایل خام: تا زمانی که فرمت ورودی بعدی ظاهر شود کار می‌کند، و اسکریپت به همان کلاینت عمومی که می‌خواستید از آن دوری کنید تبدیل می‌شود.
  • استفاده از کلاس کامل Merger برای یک فراخوانی واحد: درست است، اما سطح API وسیع‌تری اضافه می‌کند که یک عملیات هرگز به آن نیاز ندارد.

GroupDocs.Merger.LowCode دقیقاً برای این شکاف آخر وجود دارد: یک فراخوانی برای هر عملیات، بدون نیاز به یادگیری چیز دیگری ابتدا.


راه‌حل: GroupDocs.Merger.LowCode برای خطوط لوله پشت‌دفتر

GroupDocs.Merger.LowCode هفت محصول تک‌منظوره را پشت این شکل «سازنده‑ سپس‑Save» می‌پوشاند. JoinPdf و JoinDocx یک سند را به سند دیگر اضافه می‌کنند؛ JoinPptx همین کار را برای ارائه‌ها انجام می‌دهد؛ SplitPdf، SplitDocx و SplitPptx صفحات یا اسلایدهای انتخاب‌شده را به فایل‌های جداگانه می‌کشند؛ RemovePagesPdf صفحات را بدون دست‌کاری منبع حذف می‌کند. هر یک از هفت محصول منبع را به‌صورت مسیر یا جریان می‌پذیرند و قبل از نوشتن، منبع و هر فایلی که دریافت می‌کند را نسبت به فرمت خود بررسی می‌کند، بنابراین یک خط لوله هرگز نیازی به حدس زدن دلیل خروجی نادرست ندارد.

برای دنبال کردن پیاده‌سازی زیر، به موارد زیر نیاز دارید:

  • .NET 6.0 یا بالاتر (پروژه‌ی این نمونه هدف net8.0 است)
  • بسته GroupDocs.Merger.LowCode جداگانه از NuGet
  • یک مجوز موقت، اگر می‌خواهید خروجی را بدون محدودیت‌های ارزیابی که در ادامه توضیح داده می‌شود، ببینید
dotnet add package GroupDocs.Merger.LowCode

این بسته به‌صورت جداگانه در NuGet از کتابخانه‌ی اصلی GroupDocs.Merger موجود است.


پیاده‌سازی گام به گام کار «Reporting‑Pack»

در اینجا شکل کلی هفت محصول را می‌بینید که با مثال ترکیب صفحه‌ی پوشش به یک PDF ماهانه توضیح داده می‌شود.

گام ۱: تعیین منبع محصول

سازنده‌ی JoinPdf سند منبع، تمام فایل‌های اضافه‌شونده و یک نمونه‌ی JoinOptions را می‌گیرد؛ هنوز چیزی اجرا نمی‌شود.

var join = new JoinPdf("report.pdf", new[] { "appendix.pdf" }, new JoinOptions());

گام ۲: تعیین مسیر خروجی

Save(outputPath) جایی است که کار واقعاً ذخیره می‌شود. یک مسیر نسبی نسبت به پوشه‌ی کاری فعلی فرآیند حل می‌شود و Save در صورت عدم وجود پوشه خروجی، آن را ایجاد می‌کند، بنابراین یک خط لوله که در هر اجرا به پوشه‌ی ماه جدید می‌نویسد نیازی به گام جداگانه برای ایجاد پوشه ندارد.

string outputPath = "output/monthly/report-with-appendix.pdf";

چرا این برای یک کار بدون نظارت مهم است:

  • مسیر تحت کنترل شما: مسیر خروجی را از تنظیمات یا پارامتر کار بسازید، هرگز مستقیم از ورودی‌های اعتبارسنجی‌نشده استفاده نکنید؛ Save در صورت مسیر null یا خالی ArgumentNullException می‌اندازد.
  • پوشه‌ای که ایجاد می‌کند: یک کار زمان‌بندی‌شده که در هر اجرا به مقصد جدید می‌نویسد، نیازی به گام جداگانه «اطمینان از وجود پوشه» ندارد.

گام ۳: اجرا و دریافت نتیجه

فراخوانی Save بلافاصله ترکیب را انجام می‌دهد؛ گام ساخت‑ سپس‑اجرا جداگانه‌ای وجود ندارد.

join.Save(outputPath);
var sizeInBytes = new FileInfo(outputPath).Length;

در اجرای ما بر روی فایل‌های نمونه، این فراخوانی یک PDF دو صفحه‌ای report.pdf را به یک PDF دو صفحه‌ای appendix.pdf متصل کرد و فایل ۴ صفحه‌ای، ۲۵۷۹۸۷ بایتی report-with-appendix.pdf تولید شد.

گام ۴: بازگرداندن نتیجه به خط لوله

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

if (sizeInBytes == 0)
{
    throw new InvalidOperationException("Join produced an empty file.");
}

آیا GroupDocs.Merger.LowCode می‌تواند به‌جای مسیر فایل، یک Stream بگیرد؟

بله، در سمت ورودی. هر یک از هفت محصول منبع را به‌صورت Stream در همان موقعیتی که مسیر فایل می‌آمد می‌پذیرند، که وقتی ورودی کار از ذخیره‌سازی Blob یا صف می‌آید مفید است. Save همچنان نتیجه را به یک رشته‌ی مسیر خروجی می‌نویسد؛ استریم کردن خروجی خود به‌صورت مستقل در کلاس کامل Merger باقی می‌ماند.


جریان کاری واقعی: رد کردن فایلی قبل از رسیدن به آرشیو

یک تیم قراردادها که اصلاح‌نامه‌ها را به توافق‌نامه‌های امضا شده اضافه می‌کند نمی‌تواند ریسک پذیرش هر فایلی که به صندوق ورودی می‌رسد را بپذیرد؛ یک اصلاح‌نامه‌ی .docx که به‌صورت اشتباه در کنار یک ترکیب PDF قرار گیرد، ورودی خراب به آرشیو می‌دهد. JoinPdf منبع و هر فایلی که اضافه می‌شود را نسبت به فرمت PDF بررسی می‌کند و در لحظه‌ای که یکی از آن‌ها مطابقت نداشته باشد FileTypeNotSupportedException را پرتاب می‌کند.

try
{
    new JoinPdf("report.pdf", new[] { "contract.docx" }, new JoinOptions())
        .Save("output/mixed.pdf");
}
catch (FileTypeNotSupportedException exception)
{
    Console.WriteLine(exception.Message);
}

در اجرای نمونه، که مسیرها از پوشه‌ی resources ساخته می‌شوند، پیام به این شکل بود: Input format does not match the expected format 'PDF'; the joined file 'resources\contract.docx' is 'Microsoft Word Open XML Document (.docx)'.

کار بالا هرگز output/mixed.pdf را نمی‌نویسد وقتی استثنا پرتاب می‌شود، بنابراین یک خط لوله قرارداد می‌تواند آن پیام را مستقیماً به هر سیستم هشدار یا صف تیکت که قبلاً استفاده می‌کند بفرستد، به‌جای اینکه روزها بعد متوجه ورودی خراب آرشیو شود.


سایر سناریوهای پشت‌دفتر که این الگو در آن‌ها مناسب است

پس از اینکه ترکیب بالا کار کرد، همان شکل «سازنده‑ سپس‑Save» می‌تواند چندین کار مختلف که یک پشت‌دفتر به‌صورت زمان‌بندی‌شده اجرا می‌کند را پوشش دهد:

  • حذف صفحه قبل از خروج سند از ساختمان: RemovePagesPdf صفحات انتخاب‌شده را حذف می‌کند و فایل جدیدی می‌نویسد بدون دست‌کاری منبع، بنابراین منبع اصلی برای حسابرسی پس از ارسال نسخه‌ی اصلاح‌شده در دسترس می‌ماند. در اجرای ما، حذف صفحه‌ی ۲ از report.pdf منجر به تولید فایل ۱ صفحه‌ای، ۸۶۶۴۷ بایتی report-without-page-2.pdf شد و report.pdf بدون تغییر باقی ماند.
  • تقسیم یک ارائه برای یک ذینفع: SplitPptx اسلایدهای درخواست‌شده را به فایل‌های جداگانه می‌کشد؛ نام فایل‌ها با توکن {0} در الگوی خروجی یا، در صورت عدم وجود توکن، با شماره‌ی افزوده‌شده در همان پوشه ساخته می‌شود، همان الگویی که SplitPdf برای تقسیم صفحات PDF استفاده می‌کند.
  • ادغام اسناد Word به‌جای PDF: JoinDocx دقیقاً همان شکل «سازنده‑ سپس‑Save» را که JoinPdf دارد دنبال می‌کند و سند اضافه‌شده را پس از آخرین صفحه منبع قرار می‌دهد.

بدون مجوز، هر یک از این اجراها در حالت ارزیابی هستند. در اجرای بدون مجوز ما، خروجی‌های PDF و Word ترکیب‌شده به ۳ صفحه هر کدام کاهش یافت، اگرچه تمام شش خروجی نمونه هنوز تولید شدند؛ قبل از اجرای خودکار در تولید، با License.Set یک مجوز اعمال کنید.


شروع کار در خط لوله پشت‌دفتر شما

شما اکنون یک الگوی ادغام اسناد کم‌کد دارید که از ابتدا تا انتها کار می‌کند، به‌علاوه اثبات اینکه بررسی فرمت در هر فراخوانی انجام می‌شود. در ادامه می‌توانید این مسیرها را دنبال کنید:

  • مشاهده تصویر کلی: راهنمای use‑case guide هر یک از شش عملیات نمونه را به‌صورت گام به گام توضیح می‌دهد و شامل یک FAQ کامل است.
  • عمق بیشتر وقتی کار گسترش می‌یابد: full GroupDocs.Merger API امکانات بیشتری نسبت به این الگو دارد، به‌خصوص وقتی خط لوله از یک عملیات فراتر می‌رود.
  • مرور کد: complete sample on GitHub شامل تمام فایل‌های ورودی استفاده‌شده در بالا است.
  • نصب: installation page بسته جداگانه و چارچوب‌های هدف پشتیبانی‌شده را توضیح می‌دهد.
  • حذف محدودیت‌های ارزیابی: قبل از استفاده در تولید، یک مجوز موقت دریافت کنید.
  • سوالات: support forum جایی است که تیم به سوالات پیاده‌سازی پاسخ می‌دهد.

منابع