Documentation – Trabajando con archivos OLM

Net: Apertura de archivos OLM

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

Aspose.Email para .NET representa un archivo de almacenamiento de Outlook para Mac con el OlmStorage clase. Este artículo muestra cómo abrir un archivo OLM desde una ruta o un stream, y cómo cargar de forma segura un archivo que pueda estar dañado.

Abrir un Archivo OLM

Un archivo OLM puede abrirse de dos maneras:

usando un constructor;
usando el estático FromFile método.

Existe una diferencia de comportamiento entre estos dos enfoques que afecta cómo se inicializa la jerarquía de carpetas. Vea Navegando carpetas OLM para más detalles.

Usando el Constructor

Para abrir un archivo, llame al constructor de la OlmStorage clase y pase el nombre completo del archivo como argumento. Debido a que OlmStorage implementa IDisposable, envuélvalo en un using sentencia para que el manejador subyacente del archivo se libere cuando termine.

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

Usando el Método Estático FromFile

Para abrir un archivo, use el estático FromFile método y pasar el nombre completo del archivo como argumento:

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

Abrir un Archivo OLM desde un Stream

Cuando los datos OLM no provienen de una ruta local —por ejemplo, se reciben de una base de datos, un recurso de red o almacenamiento en la nube— puede abrirlos directamente desde un Stream. Use el OlmStorage(Stream) constructor o el estático FromStream método.

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

El método estático funciona de la misma manera:

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

Mantenga abierto el stream de origen mientras accede al almacenamiento. Disponer del stream antes de terminar de leer carpetas y mensajes provocará errores de lectura.

Abrir un Archivo OLM Corrupto

Si un archivo puede estar parcialmente dañado, aún puede extraer la mayor cantidad de datos posible sin detenerse en el primer error. Para ello, cree el OlmStorage instancia con el OlmStorage(TraversalExceptionsCallback callback) constructor, luego cargue el archivo con el Load método en lugar del FromFile.

La devolución de llamada recibe las excepciones generadas durante la carga y el recorrido, por lo que puede registrarlas o ignorarlas. El Load método devuelve true si el archivo se cargó correctamente y es posible el recorrido, y false si el archivo está demasiado dañado para recorrerlo.

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 un ejemplo completo de extracción de elementos de un archivo dañado, vea Lectura y extracción de mensajes OLM.

Net: Navegando carpetas OLM

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

Un archivo OLM organiza sus datos en un árbol de carpetas, cada una representada por un OlmFolder objeto. Este artículo muestra cómo enumerar la jerarquía de carpetas, recuperar una carpeta específica por nombre, navegar subcarpetas y leer rutas de carpetas.

Recuperar la Jerarquía de Carpetas

Una vez que el archivo está abierto, acceda a su estructura de directorios a través de la FolderHierarchy propiedad. Esta propiedad devuelve una lista de OlmFolder objetos, cada uno representando un directorio de nivel superior en el archivo OLM. Para explorar más a fondo, lea el SubFolders propiedad de cada carpeta, que devuelve sus subdirectorios. Usando estos dos miembros puede recorrer toda la jerarquía.

El ejemplo a continuación imprime todas las carpetas en orden jerárquico:

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 y el Método FromFile

La forma en que abre el archivo afecta cómo FolderHierarchy se comporta:

Cuando abre el archivo con el constructor, el FolderHierarchy propiedad se inicializa automáticamente.
Cuando abre el archivo con el FromFile método, FolderHierarchy no está inicializado por defecto y devuelve null. En este caso, llame al GetFolders método explícitamente para inicializar la jerarquía y recuperar la lista de directorios:

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

Obtener una Carpeta por Nombre

Para recuperar una sola carpeta por nombre, llame al GetFolder método. Pase el nombre de la carpeta como primer argumento y un booleano como segundo argumento que indica si se debe ignorar mayúsculas/minúsculas durante la búsqueda.

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

Obtener una Subcarpeta por Nombre

Cada OlmFolder también le permite localizar una carpeta hija directamente con el GetSubFolder método. Pase el nombre de la subcarpeta y si se debe ignorar mayúsculas/minúsculas. Esto es útil cuando ya posee una carpeta padre y desea profundizar sin volver a escanear toda la jerarquía.

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 Rutas de Carpetas

Puede leer la ruta completa de cualquier carpeta a través del OlmFolder.Path propiedad. El siguiente fragmento imprime la ruta de cada carpeta en el archivo:

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: Lectura y extracción de mensajes OLM

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

Después de abrir un archivo OLM y localizar una carpeta, puede listar sus mensajes, leer información breve de los mensajes, filtrar y paginar carpetas grandes, y extraer mensajes individuales como MapiMessage objetos. Este artículo cubre todas estas operaciones.

Listar Mensajes en una Carpeta

El OlmFolder clase que proporciona dos formas de iterar sobre los mensajes que contiene:

EnumerateMessages devuelve un OlmMessageInfo objeto en cada iteración. Este objeto contiene información breve del mensaje y es la forma más eficiente de escanear una carpeta.
EnumerateMapiMessages devuelve un completo MapiMessage objeto en cada iteración, con todas las propiedades del mensaje cargadas.

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

Leer Información del Mensaje

Cada OlmMessageInfo el objeto expone un conjunto de propiedades de solo lectura que describen un mensaje sin cargar su contenido completo. Esta es la forma más eficiente de crear una vista de lista o decidir qué mensajes extraer.

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

Obtener la Fecha Modificada de un Mensaje

La fecha modificada representa la fecha y hora en que el mensaje OLM se modificó por última vez. Use el OlmMessageInfo.ModifiedDate propiedad para leerla:

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

Filtrar Mensajes con una Consulta

Para carpetas grandes, puede recuperar solo los mensajes que coincidan con un conjunto de criterios en lugar de iterar todo. Pase un MailQuery al EnumerateMessages(MailQuery query) sobrecarga. Construya la consulta con un MailQueryBuilder.

El ejemplo a continuación enumera solo los mensajes recibidos durante los últimos siete días cuyo asunto contiene la palabra "Factura":

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 Mensajes

Cuando una carpeta contiene una gran cantidad de mensajes, puede leerlos en lotes con el EnumerateMessages(int skip, int count) sobrecarga. El skip el parámetro es el número de mensajes a omitir, y count es el número de mensajes a devolver.

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

Extraer un Mensaje como MapiMessage

El OlmStorage class proporciona el ExtractMapiMessage método, que extrae un MapiMessage desde un OlmMessageInfo objeto. Esto es útil cuando primero escanea una carpeta con EnumerateMessages y luego extraer solo los mensajes que realmente necesita.

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

Extraer Mensajes por Identificador

A veces necesita extraer mensajes seleccionados por sus identificadores. Por ejemplo, una aplicación puede almacenar identificadores en una base de datos y extraer un mensaje bajo demanda en lugar de recorrer todo el almacenamiento cada vez. El EntryId propiedad de OlmMessageInfo proporciona el identificador de entrada del mensaje, y el sobrecargado ExtractMapiMessage(string id) método recupera el mensaje por ese 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);
    }
}

Extraer Elementos Usando la API de Recorrido

Puede extraer cada elemento de un archivo OLM - en la medida de lo posible - sin lanzar excepciones, incluso cuando algunos datos del archivo original están corruptos. Para ello, cree el OlmStorage instancia con el OlmStorage(TraversalExceptionsCallback callback) constructor y cargue el archivo con el Load método. La devolución de llamada expone las excepciones de carga y recorrido.

El Load método devuelve true si el archivo se cargó correctamente y es posible el recorrido, y false si el archivo está corrupto y no es posible recorrerlo. Tenga en cuenta que al recorrer los elementos carpeta por carpeta, llama al EnumerateMessages(OlmFolder folder) método, pasando la carpeta como argumento.

Los pasos son:

Crear un nuevo OlmStorage instancia, pasando una función de devolución de llamada para manejo de excepciones.
Carga el archivo OLM llamando al Load método.
Si el archivo se carga correctamente, obtenga la jerarquía de carpetas llamando a GetFolders.
Itere recursivamente sobre cada carpeta. Para carpetas que tienen mensajes, enumérelos con el EnumerateMessages método y procese cada una.
Recorra recursivamente cualquier subcarpeta.

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 elementos y trabajando con categorías

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

Más allá de leer mensajes individuales, Aspose.Email para .NET le permite inspeccionar cuántos elementos contiene un archivo OLM o una carpeta y leer las categorías de Outlook —incluidos sus colores— que se almacenan en el archivo. Este artículo cubre ambos.

Verificar si una Carpeta Tiene Mensajes

El OlmFolder.HasMessages propiedad que indica si una carpeta contiene mensajes, y el OlmFolder.MessageCount propiedad que devuelve cuántos.

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

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

Contar Elementos en Cada Carpeta

Utilice el OlmFolder.MessageCount propiedad para informar la cantidad de elementos en cada carpeta del archivo:

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

Obtener el Número Total de Elementos en el Almacenamiento

El OlmStorage la clase tiene un GetTotalItemsCount() método que devuelve el número total de elementos de mensaje contenidos en todo el almacenamiento OLM:

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

Recuperar colores de categorías de Outlook

Para trabajar con las categorías de elementos de Outlook almacenadas en un archivo OLM, Aspose.Email ofrece:

el OlmItemCategory clase - representa una categoría de elemento de Outlook, disponible por su Name y asociado Color, representado en formato hexadecimal;
el GetCategories() método del OlmStorage clase - recupera la lista de categorías usadas en el almacenamiento.

El siguiente ejemplo enumera cada categoría utilizada en el almacenamiento junto con su color:

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

Obtener el Color de la Categoría de un Mensaje

Puede comparar las categorías asignadas a un mensaje particular con la lista de categorías del almacenamiento para resolver el color de cada categoría. El ejemplo a continuación lee las categorías de cada mensaje en una carpeta y muestra el color de cada una:

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: Conversión de OLM a PST

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

OLM es un formato de archivo de base de datos usado por Microsoft Outlook para Mac. Los archivos OLM almacenan mensajes de correo, datos de calendario, contactos y configuraciones de la aplicación, y no son compatibles con Outlook para Windows. Para migrar un buzón de Outlook para Mac a Outlook para Windows, necesita convertir el archivo OLM al Outlook PST formato. Aspose.Email para .NET le permite hacer esto en código, sin que Microsoft Outlook esté instalado.

Cómo Funciona la Conversión

Para convertir un archivo OLM a PST, siga estos pasos:

Cree una instancia de la OlmStorage clase para abrir el archivo OLM de origen.
Crea un nuevo archivo PST con el PersonalStorage.Create método.
Implemente un GetContainerClass método que asigna una clase de mensaje a la clase de carpeta (contenedor) correspondiente, de modo que cada carpeta se cree con el tipo correcto en el PST.
Implemente un AddToPst método que lee recursivamente cada carpeta y sus mensajes del archivo OLM - usando EnumerateMapiMessages - y los agrega al PST en el mismo orden, usando el AddSubFolder y AddMessage métodos de FolderInfo.

Ejemplo de Código

El siguiente código muestra cómo convertir un archivo OLM a 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);
    }
}

La conversión en la dirección opuesta (PST a OLM) no es compatible, porque un archivo OLM siempre lo crea Outlook para Mac cuando se agrega una cuenta y se sincroniza con el servidor de correo.