Documentation – Trabalhando com Arquivos OLM

Net: Abrindo Arquivos OLM

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

Aspose.Email para .NET representa um arquivo de armazenamento Outlook for Mac com o OlmStorage classe. Este artigo mostra como abrir um arquivo OLM a partir de um caminho ou de um stream, e como carregar com segurança um arquivo que pode estar corrompido.

Abrir um Arquivo OLM

Um arquivo OLM pode ser aberto de duas maneiras:

usando um construtor;
usando o estático FromFile método.

Há uma diferença de comportamento entre essas duas abordagens que afeta como a hierarquia de pastas é inicializada. Consulte Navegando nas Pastas OLM para detalhes.

Usando o Construtor

Para abrir um arquivo, chame o construtor da OlmStorage classe e passe o nome completo do arquivo como argumento. Porque OlmStorage implementa IDisposable, envolva‑o em um using declaração para que o manipulador de arquivo subjacente seja liberado quando terminar.

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

Usando o Método Estático FromFile

Para abrir um arquivo, use o estático FromFile método e passar o nome completo do arquivo como argumento:

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

Abrir um Arquivo OLM a partir de um Stream

Quando os dados OLM não vêm de um caminho local — por exemplo, são recebidos de um banco de dados, de um recurso de rede ou de um armazenamento na nuvem — você pode abri‑los diretamente de um Stream. Use o OlmStorage(Stream) construtor ou o estático FromStream método.

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

O método estático funciona da mesma forma:

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

Mantenha o stream de origem aberto enquanto você acessar o armazenamento. Dispor o stream antes de terminar a leitura de pastas e mensagens causará erros de leitura.

Abrir um Arquivo OLM Corrompido

Se um arquivo pode estar parcialmente corrompido, ainda é possível extrair o máximo de dados possível sem parar no primeiro erro. Para isso, crie o OlmStorage instância com o OlmStorage(TraversalExceptionsCallback callback) construtor, então carregue o arquivo com o Load método em vez do FromFile.

O callback recebe as exceções geradas durante o carregamento e a travessia, permitindo que você registre ou ignore‑as. O Load método retorna true se o arquivo foi carregado com sucesso e a travessia for possível, e false se o arquivo estiver muito corrompido para percorrer.

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

Para um exemplo completo de extração de itens de um arquivo corrompido, veja Lendo e Extraindo Mensagens OLM.

Net: Navegando nas Pastas OLM

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

Um arquivo OLM organiza seus dados em uma árvore de pastas, cada uma representada por um OlmFolder objeto. Este artigo mostra como enumerar a hierarquia de pastas, recuperar uma pasta específica por nome, navegar entre subpastas e ler caminhos de pastas.

Recuperar a Hierarquia de Pastas

Uma vez que o arquivo está aberto, acesse sua estrutura de diretórios através da FolderHierarchy propriedade. Esta propriedade retorna uma lista de OlmFolder objetos, cada um representando um diretório de nível superior no arquivo OLM. Para explorar mais a fundo, leia o SubFolders propriedade de cada pasta, que retorna suas subdiretórios. Usando esses dois membros você pode percorrer toda a hierarquia.

O exemplo abaixo imprime todas as pastas em ordem hierárquica:

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 e o Método FromFile

A forma como você abre o arquivo afeta como FolderHierarchy comporta-se:

Ao abrir o arquivo com o construtor, o FolderHierarchy propriedade é inicializada automaticamente.
Ao abrir o arquivo com o FromFile método, FolderHierarchy não é inicializado por padrão e retorna null. Nesse caso, chame o GetFolders método explicitamente para inicializar a hierarquia e recuperar a lista de diretórios:

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

Obter uma Pasta por Nome

Para recuperar uma única pasta por nome, chame o GetFolder método. Passe o nome da pasta como primeiro argumento e um booleano como segundo argumento que indica se a diferenciação de maiúsculas/minúsculas deve ser ignorada durante a busca.

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

Obter uma Subpasta por Nome

Cada OlmFolder também permite localizar uma subpasta diretamente com o GetSubFolder método. Passe o nome da subpasta e se a diferenciação de maiúsculas/minúsculas deve ser ignorada. Isso é útil quando você já possui uma pasta pai e deseja aprofundar sem reescanear toda a hierarquia.

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

Recuperar Caminhos de Pastas

Você pode ler o caminho completo de qualquer pasta através da OlmFolder.Path propriedade. O trecho a seguir imprime o caminho de cada pasta no arquivo:

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: Lendo e Extraindo Mensagens OLM

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

Depois de abrir um arquivo OLM e localizar uma pasta, você pode listar suas mensagens, ler informações resumidas das mensagens, filtrar e paginar pastas grandes e extrair mensagens individuais como MapiMessage objetos. Este artigo cobre todas essas operações.

Listar Mensagens em uma Pasta

O OlmFolder classe fornece duas maneiras de iterar sobre as mensagens que contém:

EnumerateMessages retorna um OlmMessageInfo objeto a cada iteração. Este objeto contém informações resumidas sobre a mensagem e é a maneira mais eficiente de percorrer uma pasta.
EnumerateMapiMessages retorna um MapiMessage objeto a cada iteração, com todas as propriedades da mensagem carregadas.

Usando EnumerateMessages

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

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

Ler Informações da Mensagem

Cada OlmMessageInfo objeto expõe um conjunto de propriedades somente leitura que descrevem uma mensagem sem carregar seu conteúdo completo. Esta é a maneira mais eficiente de construir uma visualização de lista ou decidir quais mensagens extrair.

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

Obter a Data de Modificação de uma Mensagem

A data de modificação representa a data e hora em que a mensagem OLM foi modificada pela última vez. Use o OlmMessageInfo.ModifiedDate propriedade para lê-la:

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

Filtrar Mensagens com uma Consulta

Para pastas grandes, você pode recuperar somente as mensagens que correspondam a um conjunto de critérios em vez de iterar sobre tudo. Passe um MailQuery para o EnumerateMessages(MailQuery query) sobrecarga. Construa a consulta com um MailQueryBuilder.

O exemplo abaixo enumera apenas as mensagens recebidas nos últimos sete dias cujo assunto contém a palavra "Fatura":

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

Paginar Mensagens

Quando uma pasta contém um grande número de mensagens, você pode lê-las em lotes com o EnumerateMessages(int skip, int count) sobrecarga. O skip parâmetro é o número de mensagens a pular, e count é o número de mensagens a serem retornadas.

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++;
    }
}

Extrair uma Mensagem como MapiMessage

O OlmStorage classe fornece o ExtractMapiMessage método, que extrai um MapiMessage de um OlmMessageInfo objeto. Isso é útil quando você primeiro escaneia uma pasta com EnumerateMessages e então extrair apenas as mensagens que você realmente precisa.

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

Extrair Mensagens por Identificador

Às vezes você precisa extrair mensagens selecionadas por seus identificadores. Por exemplo, uma aplicação pode armazenar identificadores em um banco de dados e extrair uma mensagem sob demanda em vez de percorrer todo o armazenamento a cada vez. O EntryId propriedade de OlmMessageInfo fornece o identificador da entrada da mensagem, e o sobrecarregado ExtractMapiMessage(string id) método recupera a mensagem por aquele identificador.

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

Extrair Itens Usando a API de Travessia

Você pode extrair cada item de um arquivo OLM - tanto quanto possível - sem gerar exceções, mesmo quando alguns dados no arquivo original estão corrompidos. Para isso, crie o OlmStorage instância com o OlmStorage(TraversalExceptionsCallback callback) construtor e carregue o arquivo com o Load método. O retorno de chamada expõe as exceções de carregamento e travessia.

O Load método retorna true se o arquivo foi carregado com sucesso e a travessia for possível, e false se o arquivo estiver corrompido e nenhuma travessia for possível. Observe que ao percorrer itens pasta por pasta, você chama o EnumerateMessages(OlmFolder folder) método, passando a pasta como argumento.

Os passos são:

Criar um novo OlmStorage instância, passando um retorno de chamada de tratamento de exceções.
Carregue o arquivo OLM chamando o Load método.
Se o arquivo for carregado com sucesso, obtenha a hierarquia de pastas chamando GetFolders.
Iterar recursivamente sobre cada pasta. Para pastas que contêm mensagens, enumere-as com o EnumerateMessages método e processe cada uma.
Percorrer recursivamente quaisquer subpastas.

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: Contando Itens e Trabalhando com Categorias

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

Além de ler mensagens individuais, o Aspose.Email para .NET permite inspecionar quantos itens um arquivo OLM ou uma pasta contém e ler as categorias do Outlook — incluindo suas cores — que estão armazenadas no arquivo. Este artigo cobre ambos.

Verificar Se uma Pasta Possui Mensagens

O OlmFolder.HasMessages propriedade indica se uma pasta contém alguma mensagem, e o OlmFolder.MessageCount propriedade retorna quantos.

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

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

Contar Itens em Cada Pasta

Use o OlmFolder.MessageCount propriedade para relatar o número de itens em cada pasta do arquivo:

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

Obter o Número Total de Itens no Armazenamento

O OlmStorage classe tem um GetTotalItemsCount() método que retorna o número total de itens de mensagem contidos em todo o armazenamento OLM:

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

Recuperar cores de categorias do Outlook

Para trabalhar com as categorias de itens do Outlook armazenadas em um arquivo OLM, o Aspose.Email oferece:

o OlmItemCategory classe - representa uma categoria de item do Outlook, disponível por sua Nome e associada Cor, representadas em formato hexadecimal;
o GetCategories() método do OlmStorage classe - recupera a lista de categorias usadas no armazenamento.

O exemplo a seguir lista todas as categorias usadas no armazenamento junto com suas cores:

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

Obter a Cor da Categoria de uma Mensagem

Você pode comparar as categorias atribuídas a uma mensagem específica com a lista de categorias do armazenamento para resolver a cor de cada categoria. O exemplo abaixo lê as categorias de cada mensagem em uma pasta e imprime a cor de cada uma:

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: Convertendo OLM para PST

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

OLM é um formato de arquivo de banco de dados usado pelo Microsoft Outlook para Mac. Arquivos OLM armazenam mensagens de email, dados de calendário, contatos e configurações de aplicação, e não são suportados pelo Outlook para Windows. Para migrar uma caixa de correio do Outlook para Mac para o Outlook para Windows, você precisa converter o arquivo OLM para o Outlook PST formato. Aspose.Email para .NET permite fazer isso em código, sem precisar do Microsoft Outlook instalado.

Como a Conversão Funciona

Para converter um arquivo OLM para PST, siga estes passos:

Crie uma instância do OlmStorage classe para abrir o arquivo OLM de origem.
Crie um novo arquivo PST com o PersonalStorage.Create método.
Implementar um GetContainerClass método que mapeia uma classe de mensagem para a classe de pasta (contêiner) correspondente, de modo que cada pasta seja criada com o tipo correto no PST.
Implementar um AddToPst método que lê recursivamente cada pasta e suas mensagens do arquivo OLM - usando EnumerateMapiMessages - e os adiciona ao PST na mesma ordem, usando o AddSubFolder e AddMessage métodos de FolderInfo.

Exemplo de Código

O código a seguir mostra como converter um arquivo OLM para PST.

Método 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);
    }
}

Método 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";
}

Método 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);
    }
}

Conversão no sentido oposto (PST para OLM) não é suportada, porque um arquivo OLM é sempre criado pelo Outlook para Mac quando uma conta é adicionada e sincronizada com o servidor de email.