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 instance с OlmStorage(TraversalExceptionsCallback callback) конструктора, затем загрузите файл с помощью Load вместо FromFile.

Обратный вызов получает исключения, возникшие во время загрузки и обхода, поэтому их можно журналировать или игнорировать. Метод Load method возвращает 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 object. В этой статье показано, как перечислить иерархию папок, получить конкретную папку по имени, перемещаться по подпапкам и читать пути папок.

Получить иерархию папок

После открытия файла доступ к структуре каталогов осуществляется через FolderHierarchy свойству. Это свойство возвращает список OlmFolder объекты, каждый из которых представляет корневой каталог в файле OLM. Чтобы зайти глубже, прочитайте SubFolders property каждой папки, который возвращает её подпапки. Используя эти два члена, можно пройти всю иерархию.

Пример ниже выводит все папки в иерархическом порядке:

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 behaves:

Когда вы открываете файл через конструктор, FolderHierarchy property инициализируется автоматически.
Когда вы открываете файл с помощью FromFile метод, FolderHierarchy по умолчанию не инициализируется и возвращает null. В этом случае вызовите GetFolders method явно, чтобы инициализировать иерархию и получить список каталогов:

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

Получить папку по имени

Чтобы получить одну папку по имени, вызовите GetFolder method. Передайте имя папки в качестве первого аргумента и логическое значение во втором аргументе, указывающее, следует ли игнорировать регистр при поиске.

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

Получить подпапку по имени

Each OlmFolder также позволяет напрямую находить дочернюю папку с помощью GetSubFolder method. Передайте имя подпапки и укажите, следует ли игнорировать регистр. Это полезно, когда у вас уже есть родительская папка и вы хотите спуститься вниз по иерархии без повторного сканирования всей структуры.

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 property. В следующем фрагменте кода выводится путь каждой папки в файле:

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

Чтение информации о сообщении

Each 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 property to read it:

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

Фильтровать сообщения запросом

Для больших папок можно получать только те сообщения, которые соответствуют набору критериев, вместо перебора всех. Передайте MailQuery к EnumerateMessages(MailQuery query) overload. Build the query with a 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) overload. The skip parameter is the number of messages to bypass, and count is the number of messages to return.

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 method, который извлекает полное MapiMessage from an OlmMessageInfo object. Это полезно, когда вы сначала сканируете папку с помощью 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");
        }
    }
}

Извлечь сообщения по идентификатору

Иногда нужно извлечь выбранные сообщения по их идентификаторам. Например, приложение может хранить идентификаторы в базе данных и извлекать сообщение по требованию, вместо полного обхода хранилища каждый раз. The EntryId свойство OlmMessageInfo provides the message entry identifier, and the overloaded ExtractMapiMessage(string id) method извлекает сообщение по этому идентификатору.

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 instance с OlmStorage(TraversalExceptionsCallback callback) constructor и загрузите файл с помощью Load method. Обратный вызов раскрывает исключения загрузки и обхода.

Этот Load method возвращает true если файл загружен успешно и обход возможен, и false если файл повреждён и обход невозможен. Учтите, что при обходе элементов папка за папкой вы вызываете EnumerateMessages(OlmFolder folder) method, передавая папку в качестве аргумента.

Шаги таковы:

Создать новый OlmStorage instance, передавая обратный вызов для обработки исключений.
Загрузите файл OLM, вызвав Load метод.
Если файл загружается успешно, получите иерархию папок, вызвав GetFolders.
Рекурсивно перебрать каждую папку. Для папок, содержащих сообщения, перечислите их с помощью EnumerateMessages method and process each one.
Рекурсивно проходить любые подпапки.

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 предлагает:

the OlmItemCategory класс — представляет категорию элемента Outlook, доступную по её Name и связанные Цвет, представленный в шестнадцатеричном формате;
the 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 метод.
Implement a GetContainerClass method, который сопоставляет класс сообщения с соответствующим классом папки (контейнера), так что каждая папка создаётся с правильным типом в PST.
Implement an AddToPst method, который рекурсивно читает каждую папку и её сообщения из файла OLM — используя EnumerateMapiMessages - и добавляет их в PST в том же порядке, используя AddSubFolder и AddMessage methods of 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 method:

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 method:

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 при добавлении учётной записи и синхронизации с почтовым сервером.