ویژگی‌ها و عملکردها

ویژگی‌ها و عملکردها

این صفحه تمام ویژگی‌های اصلی Aspose.Email FOSS for .NET را با مثال‌های عملی C# پوشش می‌دهد.


خواندن فایل‌های MSG

فایل MSG را از مسیر یا جریان بارگذاری کنید و به تمام ویژگی‌های آن دسترسی پیدا کنید:

using System.IO;
using Aspose.Email.Foss.Msg;

using var stream = File.OpenRead("message.msg");
var message = MapiMessage.FromStream(stream);

Console.WriteLine(message.Subject);
Console.WriteLine(message.Body);
Console.WriteLine(message.HtmlBody);
Console.WriteLine(message.SenderName);
Console.WriteLine(message.SenderEmailAddress);
Console.WriteLine(message.MessageDeliveryTime);
Console.WriteLine(message.InternetMessageId);

از strict: false برای تجزیه‌گری ملایم فایل‌های MSG غیر استاندارد استفاده کنید:

var message = MapiMessage.FromFile("message.msg", strict: false);

ValidationIssues را بررسی کنید تا هر هشدار فرمت را بدون پرتاب مرور کنید:

foreach (var issue in message.ValidationIssues)
    Console.WriteLine($"Warning: {issue}");

ایجاد فایل‌های MSG

یک ایمیل کامل با MapiMessage.Create() بسازید و با Save() سریال‌سازی کنید:

using System.IO;
using Aspose.Email.Foss.Msg;

var message = MapiMessage.Create("Hello", "Body");
message.SenderName = "Alice";
message.SenderEmailAddress = "alice@example.com";
message.HtmlBody = "<p>Body</p>";
message.InternetMessageId = "<hello@example.com>";
message.MessageDeliveryTime = new DateTime(2024, 1, 2, 3, 4, 5, DateTimeKind.Utc);

message.AddRecipient("bob@example.com", "Bob");

using var output = File.Create("hello.msg");
message.Save(output);

Save() بدون آرگومان یک byte[] برمی‌گرداند. Save(path) مستقیماً به مسیر فایل می‌نویسد.


گیرندگان

دریافت‌کنندگان To، Cc و Bcc را با AddRecipient() اضافه کنید:

message.AddRecipient("alice@example.com", "Alice");
message.AddRecipient("bob@example.com", "Bob", MapiMessage.RecipientTypeCc);
message.AddRecipient("carol@example.com", "Carol", MapiMessage.RecipientTypeBcc);

تکرار گیرندگان از یک پیام بارگذاری‌شده:

foreach (var recipient in message.Recipients)
    Console.WriteLine($"{recipient.DisplayName} <{recipient.EmailAddress}>");

پیوست‌ها

پیوست‌های فایل یا جریان را با فراداده اضافه کنید:

// From byte array
message.AddAttachment("report.pdf", pdfBytes, "application/pdf");

// From stream
using var attachStream = File.OpenRead("photo.png");
message.AddAttachment("photo.png", attachStream, "image/png");

// Inline image with Content-ID
message.AddAttachment("logo.png", logoBytes, "image/png", contentId: "logo@cid");

خواندن پیوست‌ها از یک پیام بارگذاری‌شده:

foreach (var attachment in message.Attachments)
{
    Console.WriteLine($"Filename: {attachment.Filename}");
    Console.WriteLine($"MIME type: {attachment.MimeType}");
    Console.WriteLine($"Size: {attachment.Data.Length} bytes");
    File.WriteAllBytes(attachment.Filename!, attachment.Data);
}

پیوست‌های پیام توکار

یک MapiMessage را داخل دیگری پیوست کنید — که در زنجیره‌های ایمیل فوروارد شده رایج است:

using Aspose.Email.Foss.Msg;

var parent = MapiMessage.Create("Outer", "Parent body");
var child = MapiMessage.Create("Inner", "Child body");
child.SenderEmailAddress = "inner@example.com";
parent.AddEmbeddedMessageAttachment(child, "inner.msg");

parent.Save("outer.msg");

پیوست‌های پیام تعبیه‌شده را بخوانید:

var loaded = MapiMessage.FromFile("outer.msg");
foreach (var attachment in loaded.Attachments)
{
    if (attachment.IsEmbeddedMessage)
    {
        Console.WriteLine($"Embedded: {attachment.EmbeddedMessage!.Subject}");
    }
}

تبدیل EML و MIME

یک فایل RFC 5322 .eml را به یک MapiMessage برای ذخیره‌سازی سازگار با Outlook بارگذاری کنید:

using System.IO;
using Aspose.Email.Foss.Msg;

using var input = File.OpenRead("message.eml");
var message = MapiMessage.LoadFromEml(input);

using var msgOutput = File.Create("message.msg");
message.Save(msgOutput);

تبدیل به EML از یک فایل MSG:

var message = MapiMessage.FromFile("message.msg");
using var emlOutput = File.Create("roundtrip.eml");
message.SaveToEml(emlOutput);

LoadFromEml() همچنین یک مسیر string یا byte[] را می‌پذیرد. SaveToEml() بدون آرگومان‌ها یک byte[] برمی‌گرداند. موضوع، بدنه، بدنه HTML، فرستنده، دریافت‌کنندگان و تمام پیوست‌ها (از جمله تصاویر درون‌خطی با Content-ID) در طول تبدیل کامل EML ↔ MSG حفظ می‌شوند.


دسترسی به ویژگی MAPI

MapiPropertyCollection دسترسی نوعی به ویژگی‌های MAPI را از طریق SetProperty() و
GetPropertyValue() فراهم می‌کند. برای ویژگی‌های استاندارد از مقادیر enum CommonMessagePropertyId استفاده کنید:

using Aspose.Email.Foss.Msg;

var message = MapiMessage.FromFile("sample.msg");

// Named convenience properties
Console.WriteLine(message.Subject);
Console.WriteLine(message.SenderName);
Console.WriteLine(message.MessageDeliveryTime);

// Iterate all MAPI property keys
foreach (var key in message.IterPropertyKeys())
    Console.WriteLine($"0x{(ushort)key.PropertyId:X4} / {key.PropertyType}");

دسترسی به کانتینر CFB

فایل‌های MSG آوتلوک بر پایه فرمت Compound File Binary (CFB) ساخته شده‌اند. CfbReader درخت کامل دایرکتوری را برای بازرسی و استخراج داده‌ها نمایش می‌دهد:

using System.Text;
using Aspose.Email.Foss.Cfb;

using var reader = CfbReader.FromFile("message.msg");

// Iterate all top-level children
foreach (var entry in reader.IterChildren(CfbConstants.RootStreamId))
    Console.WriteLine($"{(entry.IsStorage() ? "Storage" : "Stream")}: {entry.Name}");

// Navigate to a specific stream by path
var entry2 = reader.ResolvePath(["__substg1.0_0037001E"]);
if (entry2 is not null)
{
    var data = reader.GetStreamData(entry2.StreamId);
    Console.WriteLine(Encoding.Unicode.GetString(data));
}

ساخت و سریال‌سازی یک سند CFB از ابتدا با CfbWriter:

using System.Text;
using Aspose.Email.Foss.Cfb;

var document = new CfbDocument();
document.Root.AddStream(new CfbStream("Notes", Encoding.UTF8.GetBytes("hello")));
var storage = document.Root.AddStorage(new CfbStorage("DataStore"));
storage.AddStream(new CfbStream("Payload", Encoding.UTF8.GetBytes("content")));

byte[] bytes = CfbWriter.ToBytes(document);
File.WriteAllBytes("output.cfb", bytes);

نکات و بهترین شیوه‌ها

  • از using یا Dispose() بر روی MapiMessage و CfbReader برای آزادسازی دستگیره‌های فایل استفاده کنید
  • پس از بارگذاری، message.ValidationIssues را بررسی کنید تا قالب‌بندی غیر استاندارد MSG را شناسایی کنید
  • پارامتر strict در FromFile() / FromStream() تحمل خطا را کنترل می‌کند — برای تجزیهٔ ملایم فایل‌های سیستم‌های شخص ثالث از strict: false استفاده کنید
  • MapiMessage.Create() به‌طور پیش‌فرض پیام‌های رشته‌ای یونیکد تولید می‌کند؛ برای سازگاری با ANSI قدیمی unicodeStrings: false را تنظیم کنید
  • SaveToEml() بدون آرگومان byte[] را برمی‌گرداند — برای جریان‌های کاری در حافظه مناسب است

مشکلات رایج

مشکلدلیلراه‌حل
CfbException هنگام بارگذاریفایل CFB/MSG معتبر نیستتأیید کنید که فایل یک Outlook MSG است
Body خالی پس از بارگذاریبدنه فقط به صورت HTML ذخیره شده استبه جای آن message.HtmlBody را بررسی کنید
۰ پیوست پس از LoadFromEmlEML هیچ بخش Content-Disposition: attachment نداردبخش‌های درون‌خطی (فقط Content-ID) همچنین در Attachments ظاهر می‌شوند

API خلاصه مرجع

کلاستوضیح
MapiMessageنمایش سطح بالا از پیام MSG
MapiAttachmentپیوست یا پیام توکار در یک MapiMessage
MapiRecipientگیرنده در یک MapiMessage
MapiPropertyورودی تک‌تایی ویژگی MAPI
MapiPropertyCollectionکیسه ویژگی MAPI با نوع
CommonMessagePropertyIdشمارشگر شناسه‌های استاندارد ویژگی MAPI
MsgReaderخواننده ساختار MSG سطح پایین
MsgWriterنویسنده ساختار MSG سطح پایین
CfbReaderخوانندهٔ مخزن باینری CFB
CfbWriterنویسندهٔ مخزن باینری CFB
CfbDocumentسند CFB در حافظه برای ساخت
CfbStorageگرهٔ ذخیره‌سازی در سند CFB
CfbStreamگرهٔ جریان در سند CFB
 فارسی