Documentation – עבודה עם קבצי OLM

Net: פתיחת קובצי OLM

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

Aspose.Email for .NET מייצגת קובץ אחסון Outlook for Mac באמצעות OlmStorage מחלקה. מאמר זה מציג כיצד לפתוח קובץ OLM ממסלול או מ‑Stream, וכיצד לטעון קובץ שעשוי להיות פגום בצורה בטוחה.

פתיחת קובץ OLM

קובץ OLM ניתן לפתיחה בשתי דרכים:

שימוש בבנאי;
שימוש ב‑static FromFile שיטה.

קיימת הבדל בהתנהגות בין שתי הגישות שמשפיע על איך היררכיית התיקיות מאותחלת. ראה ניווט בתיקיות OLM לפרטים נוספים.

שימוש בבנאי

לפתיחת קובץ, קרא לבנאי של OlmStorage מחלקה והעבר את שם הקובץ המלא כארגומנט. משום ש‑ OlmStorage מיישמת IDisposable, עטוף אותו ב‑ using הצהרה כך שהידית הקובץ הבסיסית תישחרר כשסיימת.

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

שימוש במתודת ה‑Static FromFile

לפתיחת קובץ, השתמש ב‑static FromFile מתודה והעבר את שם הקובץ המלא כארגומנט:

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

פתיחת קובץ OLM מ‑Stream

כאשר נתוני OLM אינם מגיעים ממסלול מקומי – לדוגמה, הם מתקבלים ממסד נתונים, משאב רשת או אחסון בענן – ניתן לפתוח אותם ישירות מ‑ Stream. השתמש ב‑ OlmStorage(Stream) הקונסטרוקטור או ה‑static FromStream שיטה.

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

מתודת ה‑static פועלת באותו אופן:

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

המשך לאחוז את ה‑Stream המקורי פתוח כל עוד אתה ניגש לאחסון. סגירת ה‑Stream לפני שסיימת לקרוא תיקיות והודעות יגרום לשגיאות קריאה.

פתיחת קובץ OLM פגום

אם קובץ עלול להיות חלקית פגום, עדיין ניתן לחלץ את מירב הנתונים מבלי לעצור בשגיאה הראשונה. לשם כך, צור את ה‑ OlmStorage מופע עם ה‑ OlmStorage(TraversalExceptionsCallback callback) בנייה, ואז טען את הקובץ בעזרת ה‑ Load מתודה במקום ה‑ FromFile.

ה‑callback מקבל את החריגות שהתרחשו במהלך הטעינה והמעבר, ולכן ניתן לרשום אותן או להתעלם מהן. ה‑ 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 השיטה. העבר את שם התיקייה כפרמטר הראשון ובוליאני כפרמטר השני שמצביע אם יש להתעלם מרגישות לאותיות בחיפוש.

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) overload. בנה את השאילתה עם MailQueryBuilder.

הדוגמה שלהלן ממנה רק את ההודעות שהתקבלו במהלך שבעת הימים האחרונים והנושא שלהן מכיל את המילה "חשבונית":

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) overload. ה‑ 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 מספקת את מזהה הכניסה של ההודעה, וה‑overloaded 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);
    }
}

חילוץ פריטים באמצעות API של Traversal

אתה יכול לחלץ כל פריט מקובץ OLM – ככל האפשר – ללא זריקת חריגות, גם כאשר חלק מהנתונים בקובץ המקורי פגומים. כדי לעשות זאת, צור את ה‑ OlmStorage מופע עם ה‑ OlmStorage(TraversalExceptionsCallback callback) קונסטרקטור וטען את הקובץ עם ה‑ Load שיטה. קריאת‑חזור מגלה את חריגות הטעינה והמעבר.

ה Load השיטה מחזירה true אם הקובץ נטען בהצלחה והמעבר אפשרי, ו‑ false אם הקובץ פגום ואין אפשרות לעבור עליו. שים לב שכאשר עוברים על פריטים תיקיה‑ב‑תיקיה, אתה קורא ל‑storage‑ EnumerateMessages(OlmFolder folder) שיטה, שמעבירה את התיקייה כפרמטר.

הצעדים הם:

צור חדש OlmStorage מופע, עם קריאת‑שגיאה כמולשמת.
טען את קובץ ה-OLM על ידי קריאה ל- Load שיטה.
אם הקובץ נטען בהצלחה, קבל את היררכיית התיקיות על‑ידי קריאה ל‑ GetFolders.
חזרה רקורסיבית על כל תיקייה. עבור תיקיות שיש בהן הודעות, מנו אותן עם ה‑storage‑ 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 for .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, זמינה באמצעות שם ו‑ צבע, מיוצגת בפורמט הקסדצימלי;
ה 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 for Mac. קבצי OLM מאחסנים הודעות דואר, נתוני לוח שנה, אנשי קשר והגדרות יישום, ואינם נתמכים על‑ידי Outlook for Windows. כדי להעביר תיבת דואר מ‑Outlook for Mac ל‑Outlook for Windows, יש להמיר את קובץ ה‑OLM ל‑Outlook PST פורמט. Aspose.Email for .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 for Mac כאשר מוסיפים חשבון ומסנכרנים אותו עם שרת הדואר.