Documentation – 使用 OLM 文件

Net: 打开 OLM 文件

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

Aspose.Email for .NET 使用 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 对象。本文覆盖所有这些操作。

列出文件夹中的消息

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

使用遍历 API 提取项目

您可以尽可能地从 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 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 类别颜色

要处理 OLM 文件中存储的 Outlook 项目类别，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 for Mac 使用的数据库文件格式。OLM 文件存储电子邮件、日历数据、联系人和应用设置，但在 Windows 版 Outlook 中不受支持。要将邮箱从 Mac 版 Outlook 迁移到 Windows 版 Outlook，需要将 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 文件只能在 Mac 版 Outlook 中创建，当添加账户并与邮件服务器同步时生成。