💡 مثال کامل کارآمد در GitHub موجود است: convert-email-and-attachments-to-pdf-dotnet
تبدیل ایمیل به PDF یک جریان کاری GroupDocs.Conversion برای .NET است که یک پیام Outlook و پیوستهای آن را به یک یا چند فایل PDF تبدیل میکند بدون اینکه یک پیوست دیگری را بازنویسی کند یا یک فایل پشتیبانینشده کل فرآیند را خراب کند. این کار روتین دستی «صادرات‑و‑تغییر نام» را با چند خط کد جایگزین میکند که برای هر آیتم میداند از کجا آمده و آیا بهطور کامل تبدیل شده است یا نه.
روش قدیمی دردناک بود
تصور کنید یک صندوق پشتیبانی وجود دارد که هر ایمیل مورد هر پرونده دو یا
سه پیوست دارد – یک گزارش اینجا، یک اسکرینشات آنجا، گاهی یک فرمت فایلی
که هیچکس در تیم آن را نمیشناسد. این وضعیت عجیب نیست. بایگانی کردن
آن پرونده به این معناست که پیام را باز کنید،
هر پیوست را بهصورت دستی ذخیره کنید، پیوستهایی که تداخل دارند را
بهدلیل اینکه دو سیستم هر دو فایلی به نام report.csv صادر کردهاند
تغییر نام دهید، و امیدوار باشید که هیچکدام از این مجموعهها فرمت
فایلی نباشد که نمایشگر PDF شما نتواند آن را باز کند. اگر این کار را
پنجاه بار در هفته انجام دهید، «صادرات سریع» به کندترین بخش کار تبدیل
میشود و بخشی که بیشترین احتمال شتابزدن دارد، دقیقاً زمانی است که
خطاها رخ میدهند.
انجام این کار بهصورت دستی فقط زمان نمیگیرد – اینجاست که فایلها بهصورت
بیصدا گم میشوند. دو پیوست با نام یکسان report.csv را بدون تغییر
نام در همان پوشه ذخیره کنید و ذخیره دوم، اولین را بازنویسی میکند؛
هیچکس متوجه نمیشود تا زمانی که اعداد ماه سپتامبر پیدا نشوند. یک پیام
با حتی یک پیوست در فرمتایی که هیچکس مبدلکنندهای برای آن ندارد میتواند
کل صادرات را متوقف کند تا کسی تصمیم بگیرد چه کاری با آن انجام دهد.
هزینه واقعی انجام این کار بهصورت دستی: یک پیوست که تغییر نام داده و بازنویسی شده است خطایی نمیاندازد – فقط بهصورت بیصدا ناپدید میشود و فایل پرونده کامل بهنظر میرسد تا زمانی که کسی به دادههای موجود در آن نیاز پیدا کند.
راه بهتر
GroupDocs.Conversion برای .NET این کار را به چند خط کد تبدیل میکند. نیازی
به تغییر نام دستی نیست. کلاس EmailLoadOptions کنترل میکند که آیا
پیام، پیوستها یا هر دو تبدیل شوند، و یک callback SaveContext هر آیتم
خروجی را به اندازهای توصیف میکند که دو پیوست با نام report.csv هرگز
بههم نمیخورند و یک پیوست بدون مسیر به PDF هرگز بقیه اجرا را متوقف
نمیکند. هر فراخوانی به این callback ItemIndex (یک شمارش پیوسته که از 1
شروع میشود)، HierarchyLevel (0 برای پیام، 1 برای پیوست) و
SourceFileName (نام فایل اصلی) را گزارش میدهد، که برای ساخت یک نام
خروجی بدون تداخل کافی است بدون اینکه bookkeeping اضافی نوشته شود.
قبل از شروع، به موارد زیر نیاز دارید:
- .NET SDK 8.0 یا بالاتر
- GroupDocs.Conversion برای .NET 26.10.0 (دریافت یک مجوز موقت برای حذف محدودیتهای ارزیابی)
- یک پیام Outlook
.msgیا.emlبرای تبدیل
نصب با یک فرمان:
dotnet add package GroupDocs.Conversion --version 26.10.0
روش جدید: تبدیل یک پیام و پیوستهای آن
در اینجا همان کار با GroupDocs.Conversion چگونه بهنظر میرسد. مثال زیر یک پیام Outlook و هر یک از پیوستهای آن را به PDF جداگانه تبدیل میکند، با نامهای فایلی که هرگز تداخل ندارند.
گام 1 - تصمیمگیری دربارهٔ آنچه باید تبدیل شود
EmailLoadOptions.ConvertOwner و ConvertOwned بهصورت مستقل پیام و
پیامهای پیوستشده را روشن یا خاموش میکنند؛ Depth (پیشفرض 2) محدوده
دنبال کردن پیوستهای تو در تو را تعیین میکند.
// Convert the message itself and every attachment it carries
var loadOptions = new EmailLoadOptions
{
ConvertOwner = true,
ConvertOwned = true,
Depth = 2
};
گام 2 - نامگذاری هر خروجی از SaveContext
به Converter.Convert یک callback SaveContext بدهید بهجای مسیر خروجی ثابت.
این callback برای هر آیتم یک بار اجرا میشود و ItemIndex برای هر آیتم
منحصر بهفرد است حتی وقتی دو پیوست نام یکسانی دارند.
using (var converter = new Converter(messagePath, (LoadContext _) => loadOptions))
{
converter.Convert((SaveContext item) =>
{
// ItemIndex is 1 for the message, then counts up per attachment
string name = $"{item.ItemIndex:D2}-{item.SourceFileName}.pdf";
return File.Create(Path.Combine(outputFolder, name));
}, new PdfConvertOptions());
}
گام 3 - مدیریت پیوستهایی که مسیر PDF ندارند
همهٔ پیوستها نمیتوانند به PDF تبدیل شوند. SaveContext.TargetFormat
را با FileType.Unknown مقایسه کنید و آن آیتم را تحت نام خودش ذخیره کنید
بهجای تبدیل.
converter.Convert((SaveContext item) =>
{
bool passedThrough = item.TargetFormat == FileType.Unknown;
string baseName = $"{item.ItemIndex:D2}-{item.SourceFileName}";
string name = passedThrough
? baseName
: $"{baseName}.{item.TargetFormat.Extension}";
return File.Create(Path.Combine(outputFolder, name));
}, new PdfConvertOptions());
این کد را روی یک ایمیل پشتیبانی نمونهای که دو پیوست با نام report.csv
و یک پیوست در فرمت پشتیبانینشده دارد، اجرا کنید. سه PDF تولید میشود:
پیام و هر دو گزارش CSV. فایل پشتیبانینشده نیز بدون تغییر ذخیره میشود –
آن را در کنار اصلی باز کنید و هر یک از 32 بایت آن دقیقاً مطابق است.
چگونه از بازنویسی پیوستهایی که نام یکسان دارند جلوگیری کنم؟
یک نام فایل بهتنهایی نمیتواند کلید ایمنی برای خروجی باشد، زیرا دو
پیوست میتوانند دقیقاً همان نام را داشته باشند. SaveContext.ItemIndex
را همراه با SaveContext.SourceFileName در نام ترکیب کنید و دو پیوست
با نام report.csv دیگر برای همان اسلات دیسک رقابت نمیکنند؛ هر کدام
پیشوند صفر‑پد شدهٔ خود را دریافت میکند (02- و 03- در نمونه، پس از
01- پیام) و فایل خود را دارد، هر نامی که منبع استفاده کرده باشد.
مقایسهٔ کناربهکنار: قبل vs. بعد
| قبل (دستی) | بعد (GroupDocs.Conversion) | |
|---|---|---|
| زمان | چند دقیقه برای هر پیام، بهصورت دستی | چند خط کد، هر تعداد پیام |
| نامهای تکراری | بهصورت بیصدا بازنویسی میشوند | جداگانه نگهداشته میشوند با ItemIndex |
| پیوست پشتیبانینشده | کل تبدیل را خراب میکند (پیش از 26.10) | تحت نام خودش ذخیره میشود، اجرا ادامه مییابد |
| خروجی | هر چیزی که نمایشگر PDF شما میتوانست ذخیره کند | PDFهای ساختار یافته که میتوانید بایگانی یا ایندکس کنید |
ایمیل پشتیبانی نمونه از این ترکیب دقیقاً ساخته شده است: دو خروجی CSV ماهانه با همان نام، و یک فایل ضبط که هیچ مبدلگری آن را تشخیص نمیدهد.
مثال واقعی: بایگانی موارد پشتیبانی
یک تیم پشتیبانی هر مورد مشتری را بهصورت ایمیل با یک یا چند پیوست
جدولی ثبت میکند و سیستم ردیابی موارد نیاز دارد هر پیوست بهصورت PDF
قابل جستجوی جداگانهای بایگانی شود، جدا از پیام. اجرای پیام از طریق
KeepAttachmentsWithoutPdfRoute برای هر مورد ورودی، پیام و پیوستهای آن
را به مجموعهای شمارهدار از فایلها تبدیل میکند، بهطوری که هیچ پیوستی
هرگز دیگری را بازنویسی نمیکند حتی وقتی دو گزارش نام یکسان دارند.
یک ایمیل مورد با دو خروجی ماهانه report.csv و یک فایل ضبط در فرمت
بدون مبدل، بهصورت چهار فایل خروجی میشود: پیام، هر دو گزارش CSV بهصورت
PDF، و فایل ضبط تحت نام خودش ذخیره میشود – هیچچیزی حذف نمیشود، هیچچیزی
ادغام نمیشود، هیچچیزی بهصورت بیصدا بازنویسی نمیشود.
// One call per case e-mail - no manual export, no renamed duplicates
int kept = KeepAttachmentsWithoutPdfRoute(caseMessagePath, caseOutputFolder);
دیگر کارهایی که میتوانید با GroupDocs.Conversion برای .NET انجام دهید
فراتر از جداسازی پیام از پیوستها، EmailLoadOptions بخشهای بیشتری از
پیام را پوشش میدهد:
- قابلیت مشاهده فیلدها: نمایش یا مخفی کردن سرصفحه و خطوط
From،To،CcوBccآن باDisplayHeaderو گزینههای مرتبطDisplay*(CcوBccبهصورت پیشفرض مخفی هستند). - سرصفحههای بومیسازیشده: هر
EmailFieldرا به یک عنوان متفاوت باFieldTextMapنگاشت کنید، برای مثالSubjectوAttachmentsرا به زبان دیگری ترجمه کنید. - قالببندی تاریخ: خط
Sentمطابق فرهنگ ماشینی که تبدیل را اجرا میکند، وTimeZoneOffsetافست UTC مورد استفاده برای تاریخهای پیام را تنظیم میکند. - خروجی فقط پیام: وقتی PDF فقط نیاز به جایگزینی پیام دارد،
ConvertOwnedرا بهfalseتنظیم کنید، در حالی که نامهای پیوست همچنان در سرصفحه برای مرجع لیست میشوند.
مرجع کامل EmailLoadOptions reference را برای هر گزینه ببینید.
نتیجهگیری
کاری که قبلاً به معنای باز کردن پیام، ذخیرهٔ پیوستها بهصورت دستی و
دوبارهچک کردن برای تکرارهای بازنویسی شده بود، اکنون تنها به یک
callback SaveContext و چند خط کد نیاز دارد. GroupDocs.Conversion برای
.NET به هر آیتم خروجی – پیام و هر پیوست – نامی میدهد که هرگز تداخل
نمیکند و پیوستی که مسیر PDF ندارد را نگه میدارد بهجای اینکه اجرا را
متوقف کند. همان سه بلوک سازنده – ConvertOwner، ConvertOwned و
callback SaveContext – از یک PDF خلاصهٔ تکتکه تا یک تجزیهٔ کامل و
ایمن از پیام و تمام پیوستهای آن مقیاس مییابند، بنابراین میتوانید
بهصورت کوچک شروع کنید و بهتدریج به جریان کاری کامل گسترش یابید همانطور
که صندوق ورودی شما نیاز دارد.
آمادهاید تا جریان کاری ایمیل‑به‑PDF خود را خودکار کنید؟
- یک مجوز موقت رایگان امتحان کنید
- بررسی کنید تبدیل هر پیوست ایمیل به فرمت خروجی متفاوت
- مطالعه کنید مرجع کامل EmailLoadOptions reference
- نگاهی بیندازید به پروژهٔ نمونه در GitHub