Documentation – Робота з файлами OLM

Net: Відкриття файлів OLM

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

Aspose.Email for .NET представляє файл сховища Outlook для 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 метод. Передайте назву папки як перший аргумент і булеве значення як другий аргумент, що вказує, чи слід ігнорувати регістр під час пошуку.

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 об’єкти. У цій статті охоплено всі ці операції.

Список повідомлень у папці

The 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

The 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 API

Ви можете витягнути кожен елемент з файлу OLM — наскільки це можливо — без кидання виключень, навіть якщо частина даних у вихідному файлі пошкоджена. Для цього створіть OlmStorage екземпляр з OlmStorage(TraversalExceptionsCallback callback) конструктор і завантажте файл за допомогою Load метод. Зворотний виклик відкриває виключення завантаження та обходу.

The 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 for .NET дозволяє перевіряти, скільки елементів містить OLM‑файл або папка, а також читати категорії Outlook — разом з їхніми кольорами — що збережені у файлі. У цій статті розглядаються обидва варіанти.

Перевірити, чи містить папка повідомлення

The 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);
    }
}

Отримати загальну кількість елементів у сховищі

The 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 у Outlook 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 під час додавання облікового запису та синхронізації з поштовим сервером.