Documentation – Travailler avec les fichiers OLM

Net: Ouverture des fichiers OLM

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

Aspose.Email pour .NET représente un fichier de stockage Outlook for Mac avec le OlmStorage classe. Cet article montre comment ouvrir un fichier OLM depuis un chemin ou un flux, et comment charger en toute sécurité un fichier qui pourrait être corrompu.

Ouvrir un fichier OLM

Un fichier OLM peut être ouvert de deux manières :

en utilisant un constructeur ;
en utilisant le statique FromFile méthode.

Il y a une différence de comportement entre ces deux approches qui affecte la façon dont la hiérarchie des dossiers est initialisée. Voir Navigation dans les dossiers OLM pour plus de détails.

Utilisation du constructeur

Pour ouvrir un fichier, appelez le constructeur de la OlmStorage classe et passez le nom complet du fichier en argument. Parce que OlmStorage implémente IDisposable, encapsulez‑le dans un using instruction afin que le gestionnaire de fichier sous‑jacent soit libéré une fois terminé.

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

Utilisation de la méthode statique FromFile

Pour ouvrir un fichier, utilisez le statique FromFile méthode et passez le nom complet du fichier en argument :

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

Ouvrir un fichier OLM depuis un flux

Lorsque les données OLM ne proviennent pas d’un chemin local – par exemple, qu’elles sont reçues d’une base de données, d’une ressource réseau ou d’un stockage cloud – vous pouvez les ouvrir directement depuis un Stream. Utilisez le OlmStorage(Stream) constructeur ou le statique FromStream méthode.

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

La méthode statique fonctionne de la même manière :

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

Conservez le flux source ouvert tant que vous accédez au stockage. Disposer du flux avant d’avoir fini de lire les dossiers et les messages entraînera des erreurs de lecture.

Ouvrir un fichier OLM corrompu

Si un fichier peut être partiellement corrompu, vous pouvez toujours extraire autant de données que possible sans vous arrêter à la première erreur. Pour ce faire, créez le OlmStorage instance avec le OlmStorage(TraversalExceptionsCallback callback) constructeur, puis chargez le fichier avec le Load méthode au lieu du FromFile.

Le rappel reçoit les exceptions levées pendant le chargement et le parcours, vous permettant de les consigner ou de les ignorer. Le Load méthode renvoie true si le fichier a été chargé avec succès et que la traversée est possible, et false si le fichier est trop corrompu pour être parcouru.

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

Pour un exemple complet d’extraction d’éléments d’un fichier corrompu, voir Lecture et extraction des messages OLM.

Net: Navigation dans les dossiers OLM

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

Un fichier OLM organise ses données en un arbre de dossiers, chacun représenté par un OlmFolder objet. Cet article montre comment énumérer la hiérarchie des dossiers, récupérer un dossier spécifique par son nom, naviguer dans les sous‑dossiers et lire les chemins des dossiers.

Récupérer la hiérarchie de dossiers

Une fois le fichier ouvert, accédez à sa structure de répertoires via le FolderHierarchy propriété. Cette propriété renvoie une liste de OlmFolder objets, chacun représentant un répertoire de niveau supérieur dans le fichier OLM. Pour explorer plus profondément, lisez le SubFolders propriété de chaque dossier, qui renvoie ses sous‑répertoires. En utilisant ces deux membres, vous pouvez parcourir toute la hiérarchie.

L’exemple ci‑dessous imprime tous les dossiers dans l’ordre hiérarchique :

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 et la méthode FromFile

La façon dont vous ouvrez le fichier affecte la manière dont FolderHierarchy se comporte :

Lorsque vous ouvrez le fichier avec le constructeur, le FolderHierarchy propriété est initialisée automatiquement.
Lorsque vous ouvrez le fichier avec le FromFile méthode, FolderHierarchy n’est pas initialisé par défaut et renvoie null. Dans ce cas, appelez le GetFolders méthode explicitement pour initialiser la hiérarchie et récupérer la liste des répertoires :

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

Obtenir un dossier par nom

Pour récupérer un seul dossier par son nom, appelez le GetFolder méthode. Passez le nom du dossier comme premier argument et un booléen comme deuxième argument qui indique si la casse doit être ignorée pendant la recherche.

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

Obtenir un sous‑dossier par nom

Chaque OlmFolder permet également de localiser directement un sous‑dossier avec le GetSubFolder méthode. Passez le nom du sous‑dossier et indiquez si la casse doit être ignorée. Ceci est utile lorsque vous avez déjà un dossier parent et que vous voulez descendre sans re‑scanner toute la hiérarchie.

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

Récupérer les chemins de dossiers

Vous pouvez lire le chemin complet de n’importe quel dossier via le OlmFolder.Path propriété. Le fragment suivant imprime le chemin de chaque dossier dans le fichier :

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: Lecture et extraction des messages OLM

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

Après avoir ouvert un fichier OLM et localisé un dossier, vous pouvez lister ses messages, lire les informations courtes des messages, filtrer et paginer de grands dossiers, et extraire des messages individuels en tant que MapiMessage objets. Cet article couvre toutes ces opérations.

Lister les messages dans un dossier

Le OlmFolder classe fournit deux façons d’itérer sur les messages qu’elle contient :

EnumerateMessages renvoie un(e) OlmMessageInfo objet à chaque itération. Cet objet contient des informations courtes sur le message et constitue le moyen le plus efficace de parcourir un dossier.
EnumerateMapiMessages renvoie un(e) complet(e) MapiMessage objet à chaque itération, avec toutes les propriétés du message chargées.

Utilisation de EnumerateMessages

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

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

Lire les informations du message

Chaque OlmMessageInfo l’objet expose un ensemble de propriétés en lecture seule qui décrivent un message sans charger son contenu complet. C’est la façon la plus efficace de créer une vue liste ou de décider quels messages extraire.

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

Obtenir la date de modification d’un message

La date de modification représente la date et l’heure auxquelles le message OLM a été modifié pour la dernière fois. Utilisez le OlmMessageInfo.ModifiedDate propriété pour le lire :

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

Filtrer les messages avec une requête

Pour les grands dossiers, vous pouvez récupérer uniquement les messages correspondant à un ensemble de critères au lieu d’itérer sur tout. Passez un MailQuery vers le EnumerateMessages(MailQuery query) surcharge. Construisez la requête avec un MailQueryBuilder.

L’exemple ci‑dessous énumère uniquement les messages reçus au cours des sept derniers jours dont l’objet contient le mot « 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);
    }
}

Paginer les messages

Lorsqu’un dossier contient un grand nombre de messages, vous pouvez les lire par lots avec le EnumerateMessages(int skip, int count) surcharge. Le skip le paramètre est le nombre de messages à ignorer, et count est le nombre de messages à renvoyer.

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

Extraire un message en tant que MapiMessage

Le OlmStorage classe fournit le ExtractMapiMessage méthode, qui extrait un MapiMessage à partir d’un OlmMessageInfo objet. Ceci est utile lorsque vous scannez d’abord un dossier avec EnumerateMessages et ensuite extraire uniquement les messages dont vous avez réellement besoin.

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

Extraire les messages par identifiant

Parfois vous devez extraire des messages sélectionnés par leurs identifiants. Par exemple, une application peut stocker les identifiants dans une base de données et extraire un message à la demande au lieu de parcourir tout le stockage à chaque fois. Le EntryId propriété de OlmMessageInfo fournit l’identifiant d’entrée du message, et la surcharge ExtractMapiMessage(string id) méthode récupère le message par cet identifiant.

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

Extraire les éléments à l’aide de l’API de traversée

Vous pouvez extraire chaque élément d’un fichier OLM - autant que possible - sans lever d’exceptions, même lorsque certaines données du fichier original sont corrompues. Pour ce faire, créez le OlmStorage instance avec le OlmStorage(TraversalExceptionsCallback callback) constructeur et chargez le fichier avec le Load méthode. Le rappel expose les exceptions de chargement et de traversée.

Le Load méthode renvoie true si le fichier a été chargé avec succès et que la traversée est possible, et false si le fichier est corrompu et qu’aucune traversée n’est possible. Notez que lors du parcours des éléments dossier par dossier, vous appelez le EnumerateMessages(OlmFolder folder) méthode, en passant le dossier comme argument.

Les étapes sont :

Créer un nouveau OlmStorage instance, en passant une fonction de rappel de gestion des exceptions.
Chargez le fichier OLM en appelant le Load méthode.
Si le fichier se charge correctement, obtenez la hiérarchie des dossiers en appelant GetFolders.
Itérer récursivement sur chaque dossier. Pour les dossiers contenant des messages, les énumérer avec le EnumerateMessages méthode et traiter chacun d’eux.
Parcourir récursivement tous les sous‑dossiers.

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: Comptage des éléments et travail avec les catégories

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

Au-delà de la lecture de messages individuels, Aspose.Email pour .NET vous permet d’inspecter le nombre d’éléments qu’un fichier OLM ou un dossier contient et de lire les catégories Outlook – y compris leurs couleurs – stockées dans le fichier. Cet article couvre les deux.

Vérifier si un dossier contient des messages

Le OlmFolder.HasMessages propriété indique si un dossier contient des messages, et le OlmFolder.MessageCount propriété qui renvoie combien.

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

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

Compter les éléments dans chaque dossier

Utilisez le OlmFolder.MessageCount propriété pour indiquer le nombre d’éléments dans chaque dossier du fichier :

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

Obtenir le nombre total d’éléments dans le stockage

Le OlmStorage la classe possède un GetTotalItemsCount() méthode qui renvoie le nombre total d’éléments de messages contenus dans tout le stockage OLM :

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

Récupérer les couleurs des catégories Outlook

Pour travailler avec les catégories d’éléments Outlook stockées dans un fichier OLM, Aspose.Email propose :

le OlmItemCategory classe – représente une catégorie d’élément Outlook, disponible via son Name et associée Couleur, représentée au format hexadécimal ;
le GetCategories() méthode du OlmStorage classe – récupère la liste des catégories utilisées dans le stockage.

L’exemple suivant liste chaque catégorie utilisée dans le stockage avec sa couleur :

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

Obtenir la couleur de la catégorie d’un message

Vous pouvez faire correspondre les catégories attribuées à un message particulier avec la liste de catégories du stockage pour résoudre la couleur de chaque catégorie. L’exemple ci‑dessous lit les catégories de chaque message d’un dossier et affiche la couleur de chacune :

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: Conversion OLM en PST

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

OLM est un format de fichier de base de données utilisé par Microsoft Outlook pour Mac. Les fichiers OLM stockent les messages électroniques, les données de calendrier, les contacts et les paramètres de l’application, et ne sont pas pris en charge par Outlook pour Windows. Pour migrer une boîte aux lettres d’Outlook pour Mac vers Outlook pour Windows, vous devez convertir le fichier OLM au format Outlook PST format. Aspose.Email pour .NET vous permet de faire cela par code, sans Outlook installé.

Comment la conversion fonctionne

Pour convertir un fichier OLM en PST, suivez ces étapes :

Créez une instance de la OlmStorage classe pour ouvrir le fichier OLM source.
Créez un nouveau fichier PST avec le PersonalStorage.Create méthode.
Implémenter un GetContainerClass méthode qui fait correspondre une classe de message à la classe de dossier (conteneur) correspondante, afin que chaque dossier soit créé avec le type correct dans le PST.
Implémenter un AddToPst méthode qui lit récursivement chaque dossier et ses messages depuis le fichier OLM - en utilisant EnumerateMapiMessages - et les ajoute au PST dans le même ordre, en utilisant le AddSubFolder et AddMessage méthodes de FolderInfo.

Exemple de code

Le code suivant montre comment convertir un fichier OLM en PST.

Méthode 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éthode 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éthode 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 conversion dans le sens inverse (PST vers OLM) n’est pas prise en charge, car un fichier OLM est toujours créé par Outlook pour Mac lorsqu’un compte est ajouté et synchronisé avec le serveur de messagerie.