Documentation – العمل مع ملفات OLM

Net: فتح ملفات OLM

Mon, 01 Jan 0001 00:00:00 +0000

يمثل Aspose.Email لـ .NET ملف تخزين Outlook for Mac باستخدام OlmStorage فئة. يُظهر هذا المقال كيفية فتح ملف OLM من مسار أو تدفق، وكيفية تحميل ملف قد يكون تالفًا بأمان.

فتح ملف OLM

يمكن فتح ملف OLM بطريقتين:

باستخدام منشئ;
استخدام السكونية FromFile طريقة.

هناك فرق في السلوك بين هذين النهجين يؤثر على كيفية تهيئة هيكل المجلدات. راجع التنقل بين مجلدات OLM للتفاصيل.

استخدام المنشئ

لفتح ملف، استدعِ منشئ OlmStorage فئة ومرّر اسم الملف الكامل كوسيط. لأن OlmStorage تنفذ IDisposable, غلفه في using العبارة بحيث يتم تحرير مقبض الملف الأساسي عند الانتهاء.

var fileName = "MyStorage.olm";
using (var olm = new OlmStorage(fileName))
{
    // work with the storage
}

استخدام طريقة FromFile السكونية

لفتح ملف، استخدم السكونية FromFile طريقة ومرّر اسم الملف الكامل كوسيط:

var fileName = "MyStorage.olm";
using (var olm = OlmStorage.FromFile(fileName))
{
    // work with the storage
}

فتح ملف OLM من تدفق

عند عدم جلب بيانات OLM من مسار محلي - على سبيل المثال، إذا تم استلامها من قاعدة بيانات، أو مورد شبكة، أو تخزين سحابي - يمكنك فتحها مباشرة من Stream. استخدم OlmStorage(Stream) المنشئ أو السكونية FromStream طريقة.

using (var stream = File.OpenRead("MyStorage.olm"))
using (var olm = new OlmStorage(stream))
{
    // work with the storage
}

طريقة السكونية تعمل بنفس الطريقة:

using (var stream = File.OpenRead("MyStorage.olm"))
using (var olm = OlmStorage.FromStream(stream))
{
    // work with the storage
}

احتفظ بتدفق المصدر مفتوحًا طالما أنك تصل إلى التخزين. سيؤدي التخلص من التدفق قبل الانتهاء من قراءة المجلدات والرسائل إلى حدوث أخطاء قراءة.

فتح ملف OLM تالف

إذا كان الملف قد يكون تالفًا جزئيًا، لا يزال بإمكانك استخراج أكبر قدر ممكن من البيانات دون التوقف عند الخطأ الأول. للقيام بذلك، أنشئ الـ OlmStorage مثيل مع OlmStorage(TraversalExceptionsCallback callback) المنشئ، ثم حمّل الملف باستخدام Load طريقة بدلاً من FromFile.

تستقبل الدالة الارتجاع الاستثناءات التي حدثت أثناء التحميل والتصفح، بحيث يمكنك تسجيلها أو تجاهلها. الـ Load طريقة تُعيد true إذا تم تحميل الملف بنجاح وكان التجول ممكنًا، و false إذا كان الملف تالفًا جدًا بحيث لا يمكن تصفحه.

using (var olm = new OlmStorage((exception, id) =>
{
    // Exception handling code.
    Console.WriteLine($"Failed to process item '{id}': {exception.Message}");
}))
{
    if (olm.Load(fileName))
    {
        // The file was loaded and can be traversed.
        var folderHierarchy = olm.GetFolders();
    }
    else
    {
        Console.WriteLine("The OLM file is corrupted and cannot be traversed.");
    }
}

للحصول على مثال كامل لاستخراج العناصر من ملف تالف، راجع قراءة واستخراج رسائل OLM.

Net: التنقل بين مجلدات OLM

Mon, 01 Jan 0001 00:00:00 +0000

تنظم ملفات OLM بياناتها في شجرة من المجلدات، كل منها ممثل بـ OlmFolder كائن. توضح هذه المقالة كيفية تعداد هيكل المجلد، استرجاع مجلد معين بالاسم، التنقل بين المجلدات الفرعية، وقراءة مسارات المجلدات.

استرجاع هيكل المجلد

بمجرد فتح الملف، وصل إلى هيكله الدليلي عبر FolderHierarchy خاصية. هذه الخاصية تُعيد قائمة بـ OlmFolder كائنات، كل منها يمثل دليلًا رئيسيًا في ملف OLM. لاستكشاف أعمق، اقرأ SubFolders خاصية كل مجلد، التي تُرجع مجلداته الفرعية. باستخدام هذين العضوين يمكنك استعراض الهيكل بالكامل.

المثال أدناه يطبع جميع المجلدات بترتيب هرمي:

using (var olm = new OlmStorage(fileName))
{
    PrintAllFolders(olm.FolderHierarchy, string.Empty);
}

private void PrintAllFolders(IEnumerable<OlmFolder> folderHierarchy, string indent)
{
    foreach (var folder in folderHierarchy)
    {
        Console.WriteLine($"{indent}{folder.Name}");
        PrintAllFolders(folder.SubFolders, indent + "-");
    }
}

FolderHierarchy وطريقة FromFile

الطريقة التي تفتح بها الملف تؤثر على كيفية FolderHierarchy يتصرف:

عند فتح الملف باستخدام المُنشئ، فإن FolderHierarchy الخاصية يتم تهيئتها تلقائيًا.
عند فتح الملف باستخدام FromFile طريقة, FolderHierarchy غير مهيأ افتراضيًا ويعيد null. في هذه الحالة، استدعِ GetFolders الطريقة صراحةً لتهيئة الهيكل واسترجاع قائمة الأدلة:

using (var olm = OlmStorage.FromFile(fileName))
{
    var folders = olm.GetFolders();
}

احصل على مجلد بالاسم

لاسترجاع مجلد واحد بالاسم، استدعِ GetFolder طريقة. مرر اسم المجلد كوسيطة أولى وBoolean كوسيطة ثانية تشير إلى ما إذا كان يجب تجاهل حالة الأحرف أثناء البحث.

using (var olm = OlmStorage.FromFile(fileName))
{
    // get the Inbox folder by name, ignoring case
    OlmFolder folder = olm.GetFolder("Inbox", true);
}

احصل على مجلد فرعي بالاسم

كل OlmFolder تتيح لك أيضًا تحديد موقع مجلد فرعي مباشرة باستخدام GetSubFolder طريقة. مرر اسم المجلد الفرعي وما إذا كان يجب تجاهل الحالات. هذا مفيد عندما تكون لديك بالفعل مجلد أصل وتريد الخوض فيه دون إعادة فحص الهيكل بالكامل.

using (var olm = OlmStorage.FromFile(fileName))
{
    OlmFolder inbox = olm.GetFolder("Inbox", true);

    // get a sub-folder of Inbox by name
    OlmFolder archive = inbox.GetSubFolder("Archive", true);

    if (archive != null)
    {
        Console.WriteLine($"Found sub-folder: {archive.Name}");
    }
}

استرجاع مسارات المجلدات

يمكنك قراءة المسار الكامل لأي مجلد عبر OlmFolder.Path خاصية. يطبع المقتطف التالي مسار كل مجلد في الملف:

using (var storage = new OlmStorage("SampleOLM.olm"))
{
    PrintPath(storage.FolderHierarchy);
}

public static void PrintPath(IEnumerable<OlmFolder> folders)
{
    foreach (OlmFolder folder in folders)
    {
        // print the current folder path
        Console.WriteLine(folder.Path);

        PrintPath(folder.SubFolders);
    }
}

Net: قراءة واستخراج رسائل OLM

Mon, 01 Jan 0001 00:00:00 +0000

بعد فتح ملف OLM وتحديد موقع مجلد، يمكنك سرد رسائله، قراءة معلومات مختصرة عن الرسالة، تصفية وتصفح المجلدات الكبيرة، واستخراج رسائل فردية كـ MapiMessage كائنات. يغطي هذا المقال جميع هذه العمليات.

قائمة الرسائل في مجلد

الـ OlmFolder الفئة توفر طريقتين للتكرار عبر الرسائل التي تحتويها:

EnumerateMessages يرجع OlmMessageInfo كائن في كل تكرار. هذا الكائن يحمل معلومات مختصرة عن الرسالة وهو الأكثر كفاءة لمسح مجلد.
EnumerateMapiMessages يرجع كامل MapiMessage الكائن في كل تكرار، مع تحميل جميع خصائص الرسالة.

استخدام EnumerateMessages

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);
    foreach (var messageInfo in folder.EnumerateMessages())
    {
        Console.WriteLine(messageInfo.Subject);
    }
}

استخدام EnumerateMapiMessages

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    foreach (var msg in folder.EnumerateMapiMessages())
    {
        // save the message in MSG format
        msg.Save($"{msg.Subject}.msg");
    }
}

قراءة معلومات الرسالة

كل OlmMessageInfo الكائن يعرّض مجموعة من الخصائص للقراءة فقط التي تصف الرسالة دون تحميل محتواها بالكامل. هذا هو الأكثر كفاءة لإنشاء عرض قائمة أو لتحديد الرسائل التي يجب استخراجها.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    foreach (OlmMessageInfo messageInfo in folder.EnumerateMessages())
    {
        Console.WriteLine($"Subject: {messageInfo.Subject}");
        Console.WriteLine($"From: {messageInfo.From}");
        Console.WriteLine($"To: {string.Join("; ", messageInfo.To)}");
        Console.WriteLine($"Date: {messageInfo.Date}");
        Console.WriteLine($"Modified: {messageInfo.ModifiedDate}");
        Console.WriteLine($"Has attachments: {messageInfo.HasAttachments}");
        Console.WriteLine($"Message class: {messageInfo.MessageClass}");
        Console.WriteLine(new string('-', 30));
    }
}

احصل على تاريخ تعديل الرسالة

تاريخ التعديل يمثل التاريخ والوقت الذي تم فيه تعديل رسالة OLM آخر مرة. استخدم OlmMessageInfo.ModifiedDate خاصية لقراءتها:

foreach (OlmMessageInfo messageInfo in inboxFolder.EnumerateMessages())
{
    DateTime modifiedDate = messageInfo.ModifiedDate;
}

تصفية الرسائل باستعلام

للمجلدات الكبيرة، يمكنك استرجاع الرسائل التي تطابق مجموعة من المعايير فقط بدلًا من التكرار على جميعها. مرّر MailQuery إلى الـ EnumerateMessages(MailQuery query) إصدار زائد. بنِ جملة الاستعلام باستخدام MailQueryBuilder.

المثال أدناه يعدد فقط الرسائل المستلمة خلال الأيام السبعة الأخيرة التي يحتوي موضوعها على كلمة "Invoice":

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    var builder = new MailQueryBuilder();
    builder.InternalDate.Since(DateTime.Now.AddDays(-7));
    builder.Subject.Contains("Invoice");
    MailQuery query = builder.GetQuery();

    foreach (var messageInfo in folder.EnumerateMessages(query))
    {
        Console.WriteLine(messageInfo.Subject);
    }
}

الصفحات عبر الرسائل

عندما يحتوي مجلد على عدد كبير من الرسائل، يمكنك قراءتها على دفعات باستخدام EnumerateMessages(int skip, int count) إصدار زائد. الـ skip المعلمة هي عدد الرسائل التي يجب تخطيها، و count هو عدد الرسائل المراد إرجاعها.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    const int pageSize = 50;
    int pageIndex = 0;

    while (true)
    {
        var page = folder.EnumerateMessages(pageIndex * pageSize, pageSize).ToList();
        if (page.Count == 0)
        {
            break;
        }

        foreach (var messageInfo in page)
        {
            Console.WriteLine(messageInfo.Subject);
        }

        pageIndex++;
    }
}

استخراج رسالة كـ MapiMessage

الـ OlmStorage class يوفر الـ ExtractMapiMessage طريقة، التي تستخرج كامل MapiMessage من OlmMessageInfo كائن. هذا مفيد عندما تقوم بمسح مجلد أولًا باستخدام EnumerateMessages ثم استخرج فقط الرسائل التي تحتاجها فعليًا.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    foreach (var messageInfo in folder.EnumerateMessages())
    {
        if (messageInfo.Date.Date == DateTime.Today)
        {
            // extract today's messages from Inbox
            var msg = olm.ExtractMapiMessage(messageInfo);
            msg.Save($"{msg.Subject}.msg");
        }
    }
}

استخراج رسائل حسب المعرف

أحيانًا تحتاج إلى استخراج رسائل محددة بمعرفاتها. على سبيل المثال، يمكن لتطبيق أن يخزن المعرفات في قاعدة بيانات ويستخرج رسالة عند الطلب بدلًا من تجول التخزين بالكامل في كل مرة. الـ EntryId خاصية من OlmMessageInfo توفر معرف إدخال الرسالة، وتُحمَّل الزاوية المتعددة ExtractMapiMessage(string id) طريقة تسترجع الرسالة وفقًا لهذا المعرف.

using (var olm = OlmStorage.FromFile(fileName))
{
    var olmFolder = olm.GetFolder("Inbox", true);

    foreach (OlmMessageInfo msgInfo in olmFolder.EnumerateMessages())
    {
        // store msgInfo.EntryId somewhere, then later:
        MapiMessage msg = olm.ExtractMapiMessage(msgInfo.EntryId);
    }
}

استخراج العناصر باستخدام واجهة برمجة تطبيقات Traversal

يمكنك استخراج كل عنصر من ملف OLM - بقدر الإمكان - دون رمي استثناءات، حتى عندما يكون بعض البيانات في الملف الأصلي تالفًا. للقيام بذلك، أنشئ OlmStorage مثيل مع OlmStorage(TraversalExceptionsCallback callback) المُنشئ وحمّل الملف باستخدام Load طريقة. يُظهر رد النداء استثناءات التحميل والتجول.

الـ Load طريقة تُعيد true إذا تم تحميل الملف بنجاح وكان التجول ممكنًا، و false إذا كان الملف تالفًا ولا يمكن التجول فيه. لاحظ أنه عند تجول العناصر مجلدًا بمجلد، تستدعي EnumerateMessages(OlmFolder folder) طريقة، مع تمرير المجلد كوسيط.

الخطوات هي:

إنشاء جديد OlmStorage مثيل، مع تمرير دالة رد نداء لمعالجة الاستثناءات.
حمِّل ملف OLM باستدعاء Load طريقة.
إذا تم تحميل الملف بنجاح، احصل على هيكل المجلدات عبر استدعاء GetFolders.
تكرار كل مجلد بشكل متكرر. للمجلدات التي تحتوي على رسائل، عدها باستخدام EnumerateMessages طريقة ومعالجة كل منها.
التكرار داخل أي مجلدات فرعية.

using (var olm = new OlmStorage((exception, id) => { /* Exception handling code. */ }))
{
    if (olm.Load(fileName))
    {
        var folderHierarchy = olm.GetFolders();
        ExtractItems(olm, folderHierarchy);
    }
}

private static void ExtractItems(OlmStorage olm, IEnumerable<OlmFolder> folders)
{
    foreach (var folder in folders)
    {
        if (folder.HasMessages)
        {
            Console.WriteLine(folder);

            foreach (var msg in olm.EnumerateMessages(folder))
            {
                Console.WriteLine(msg.Subject);
            }
        }

        ExtractItems(olm, folder.SubFolders);
    }
}

Net: عد العناصر والعمل مع الفئات

Mon, 01 Jan 0001 00:00:00 +0000

بعيدًا عن قراءة الرسائل الفردية، يتيح Aspose.Email لـ .NET فحص عدد العناصر التي يحتويها ملف OLM أو مجلد، وقراءة فئات Outlook - بما في ذلك ألوانها - المخزنة في الملف. يغطي هذا المقال كلا الأمرين.

تحقق مما إذا كان المجلد يحتوي على رسائل

الـ OlmFolder.HasMessages الخاصية تشير إلى ما إذا كان المجلد يحتوي على أي رسائل، و OlmFolder.MessageCount الخاصية تُرجع عدد العناصر.

using (var olm = OlmStorage.FromFile(fileName))
{
    var folder = olm.GetFolder("Inbox", true);

    if (folder.HasMessages)
    {
        Console.WriteLine($"Message count: {folder.MessageCount}");
    }
}

عدد العناصر في كل مجلد

استخدم الـ OlmFolder.MessageCount خاصية تُبلغ عن عدد العناصر في كل مجلد من الملف:

using (var storage = new OlmStorage("SampleOLM.olm"))
{
    PrintMessageCount(storage.FolderHierarchy);
}

public static void PrintMessageCount(IEnumerable<OlmFolder> folders)
{
    foreach (OlmFolder folder in folders)
    {
        Console.WriteLine($"Message Count [{folder.Name}]: {folder.MessageCount}");

        PrintMessageCount(folder.SubFolders);
    }
}

الحصول على إجمالي عدد العناصر في التخزين

الـ OlmStorage الفئة لديها GetTotalItemsCount() طريقة تُرجع العدد الكلي لعناصر الرسائل الموجودة في التخزين الكامل للـ OLM:

using (var olm = new OlmStorage("storage.olm"))
{
    var count = olm.GetTotalItemsCount();
    Console.WriteLine($"Total items: {count}");
}

استرجاع ألوان فئات Outlook

للعمل مع فئات عناصر Outlook المخزنة في ملف OLM، تقدم Aspose.Email:

ال OlmItemCategory فئة - تمثل فئة عنصر Outlook، متاحة عبر Name والمربوط اللون, ممثلة بصيغة سداسية عشرية;
ال GetCategories() طريقة الـ OlmStorage فئة - تسترد قائمة الفئات المستخدمة في التخزين.

العينة التالية تسرد كل فئة مستخدمة في التخزين مع لونها:

using (var olm = OlmStorage.FromFile("storage.olm"))
{
    var categories = olm.GetCategories();

    foreach (var category in categories)
    {
        Console.WriteLine($"Category name: {category.Name}");

        // Color is represented as a hexadecimal value: #rrggbb
        Console.WriteLine($"Category color: {category.Color}");
    }
}

الحصول على لون فئة الرسالة

يمكنك مطابقة الفئات المعينة لرسالة معينة مع قائمة فئات التخزين لتحديد لون كل فئة. المثال أدناه يقرأ فئات كل رسالة في مجلد ويطبع لون كل منها:

using (var olm = OlmStorage.FromFile("storage.olm"))
{
    var categories = olm.GetCategories();
    var folder = olm.GetFolder("Inbox", true);

    foreach (var msg in folder.EnumerateMapiMessages())
    {
        if (msg.Categories != null)
        {
            foreach (var msgCategory in msg.Categories)
            {
                Console.WriteLine($"Category name: {msgCategory}");

                var category = categories
                    .FirstOrDefault(c => c.Name.Equals(msgCategory, StringComparison.OrdinalIgnoreCase));

                Console.WriteLine(category != null
                    ? $"Category color: {category.Color}"
                    : "Category color: Not found");
            }
        }
    }
}

Net: تحويل OLM إلى PST

Mon, 01 Jan 0001 00:00:00 +0000

OLM هو تنسيق ملف قاعدة بيانات يستخدمه Microsoft Outlook لـ Mac. تخزن ملفات OLM رسائل البريد الإلكتروني، بيانات التقويم، جهات الاتصال وإعدادات التطبيق، ولا يدعمها Outlook لـ Windows. لتقنيل صندوق بريد من Outlook لـ Mac إلى Outlook لـ Windows، تحتاج إلى تحويل ملف OLM إلى PST الصيغة. يتيح Aspose.Email لـ .NET القيام بذلك عبر الكود، دون الحاجة إلى تثبيت Microsoft Outlook.

كيف يعمل التحويل

لتحويل ملف OLM إلى PST، اتبع الخطوات التالية:

إنشاء مثيل من الـ OlmStorage فئة لفتح ملف OLM المصدر.
إنشاء ملف PST جديد باستخدام PersonalStorage.Create طريقة.
تنفيذ GetContainerClass طريقة تربط فئة الرسالة بفئة المجلد (الحاوية) المقابلة، بحيث يُنشأ كل مجلد بالنوع الصحيح في PST.
تنفيذ AddToPst طريقة تقرأ كل مجلد ورسائله من ملف OLM بشكل متكرر - باستخدام EnumerateMapiMessages - وتضيفها إلى PST بنفس الترتيب، باستخدام AddSubFolder و AddMessage طرق الـ FolderInfo.

عينة شفرة

يعرض المقتطف التالي كيفية تحويل ملف OLM إلى PST.

طريقة Main

// create an instance of OlmStorage class to open the source OLM
using (var olm = new OlmStorage("my.olm"))
// create a new PST file
using (var pst = PersonalStorage.Create("my.pst", FileFormatVersion.Unicode))
{
    // recursively read each folder and its messages
    // and add them to the PST in the same order
    foreach (var olmFolder in olm.FolderHierarchy)
    {
        AddToPst(pst.RootFolder, olmFolder);
    }
}

طريقة GetContainerClass:

public string GetContainerClass(string messageClass)
{
    if (messageClass.StartsWith("IPM.Contact") || messageClass.StartsWith("IPM.DistList"))
    {
        return "IPF.Contact";
    }

    if (messageClass.StartsWith("IPM.StickyNote"))
    {
        return "IPF.StickyNote";
    }

    if (messageClass.StartsWith("IPM.Activity"))
    {
        return "IPF.Journal";
    }

    if (messageClass.StartsWith("IPM.Task"))
    {
        return "IPF.Task";
    }

    if (messageClass.StartsWith("IPM.Appointment") || messageClass.StartsWith("IPM.Schedule.meeting"))
    {
        return "IPF.Appointment";
    }

    return "IPF.Note";
}

طريقة AddToPst:

public void AddToPst(FolderInfo pstFolder, OlmFolder olmFolder)
{
    FolderInfo pstSubFolder = pstFolder.GetSubFolder(olmFolder.Name);

    foreach (var msg in olmFolder.EnumerateMapiMessages())
    {
        if (pstSubFolder == null)
        {
            pstSubFolder = pstFolder.AddSubFolder(olmFolder.Name, GetContainerClass(msg.MessageClass));
        }

        pstSubFolder.AddMessage(msg);
    }

    if (pstSubFolder == null)
    {
        pstSubFolder = pstFolder.AddSubFolder(olmFolder.Name);
    }

    foreach (var olmSubFolder in olmFolder.SubFolders)
    {
        AddToPst(pstSubFolder, olmSubFolder);
    }
}

التحويل في الاتجاه المعاكس (من PST إلى OLM) غير مدعوم، لأن ملف OLM يُنشأ دائمًا بواسطة Outlook لـ Mac عند إضافة حساب ومزامنته مع خادم البريد.