Documentation – Werken met OLM-bestanden

Net: OLM-bestanden openen

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

Aspose.Email voor .NET vertegenwoordigt een Outlook‑for‑Mac‑opslagbestand met de OlmStorage klasse. Dit artikel laat zien hoe u een OLM‑bestand opent vanaf een pad of een stream, en hoe u een bestand veilig laadt dat mogelijk beschadigd is.

Een OLM‑bestand openen

Een OLM‑bestand kan op twee manieren worden geopend:

gebruik van een constructor;
gebruik van de statische FromFile methode.

Er is een verschil in gedrag tussen deze twee benaderingen dat van invloed is op hoe de maphiërarchie wordt geïnitialiseerd. Zie Navigeren door OLM-mappen voor meer details.

De constructor gebruiken

Om een bestand te openen, roep de constructor van de OlmStorage klasse en geef de volledige bestandsnaam als argument door. Omdat OlmStorage implementeert IDisposable, wikkel deze in een using instructie zodat de onderliggende bestandshandle wordt vrijgegeven wanneer u klaar bent.

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

De statische FromFile‑methode gebruiken

Om een bestand te openen, gebruik de statische FromFile methode en de volledige bestandsnaam als argument doorgeven:

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

Een OLM‑bestand openen vanuit een stream

Wanneer de OLM‑gegevens niet afkomstig zijn van een lokaal pad – bijvoorbeeld wanneer ze worden ontvangen vanuit een database, een netwerkbron of cloudopslag – kunt u ze rechtstreeks openen vanuit een Stream. Gebruik de OlmStorage(Stream) constructor of de statische FromStream methode.

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

De statische methode werkt op dezelfde manier:

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

Houd de bron‑stream open zolang u toegang heeft tot de opslag. Het vrijgeven van de stream voordat u klaar bent met het lezen van mappen en berichten veroorzaakt leesfouten.

Een beschadigd OLM‑bestand openen

Als een bestand gedeeltelijk beschadigd kan zijn, kunt u toch zoveel mogelijk gegevens extraheren zonder bij de eerste fout te stoppen. Maak hiervoor de OlmStorage instantie met de OlmStorage(TraversalExceptionsCallback callback) constructor, laad vervolgens het bestand met de Load methode in plaats van FromFile.

De callback ontvangt de uitzonderingen die tijdens het laden en doorlopen worden gegenereerd, zodat u ze kunt loggen of negeren. De Load methode retourneert true als het bestand succesvol is geladen en doorlopen mogelijk is, en false als het bestand te beschadigd is om te doorlopen.

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

Voor een volledig voorbeeld van het extraheren van items uit een beschadigd bestand, zie OLM-berichten lezen en extraheren.

Net: Navigeren door OLM-mappen

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

Een OLM‑bestand organiseert zijn gegevens in een boom van mappen, elk weergegeven door een OlmFolder object. Dit artikel laat zien hoe u de maphiërarchie kunt doorlopen, een specifieke map op naam kunt ophalen, sub‑mappen kunt navigeren en mappaden kunt lezen.

De maphiërarchie ophalen

Zodra een bestand is geopend, krijg toegang tot de mapstructuur via de FolderHierarchy eigenschap. Deze eigenschap retourneert een lijst van OlmFolder objecten, elk vertegenwoordigt een bovenliggende map in het OLM‑bestand. Om dieper te verkennen, lees de SubFolders eigenschap van elke map, die de onderliggende mappen retourneert. Met deze twee leden kunt u de volledige hiërarchie doorlopen.

Het voorbeeld hieronder drukt alle mappen af in hiërarchische volgorde:

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 en de FromFile-methode

De manier waarop u het bestand opent beïnvloedt hoe FolderHierarchy zich:

Wanneer u het bestand opent met de constructor, gedraagt de FolderHierarchy eigenschap wordt automatisch geïnitialiseerd.
Wanneer u het bestand opent met de FromFile methode, FolderHierarchy is niet standaard geïnitialiseerd en retourneert null. Roep in dit geval de GetFolders methode expliciet aan om de hiërarchie te initialiseren en de lijst van mappen op te halen:

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

Een map op naam verkrijgen

Om een enkele map op naam op te halen, roep de GetFolder methode. Geef de mapnaam als eerste argument en een boolean als tweede argument die aangeeft of hoofdletter‑gevoeligheid tijdens het zoeken moet worden genegeerd.

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

Een onderliggende map op naam verkrijgen

Elke OlmFolder maakt ook dat u een onderliggende map direct kunt vinden met de GetSubFolder methode. Geef de onderliggende mapnaam op en of hoofdlettergevoeligheid moet worden genegeerd. Dit is handig wanneer u al een bovenliggende map bezit en verder wilt gaan zonder de volledige hiërarchie opnieuw te scannen.

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

Mappaden ophalen

U kunt het volledige pad van elke map lezen via de OlmFolder.Path eigenschap. Het volgende fragment drukt het pad van elke map in het bestand af:

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-berichten lezen en extraheren

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

Nadat u een OLM‑bestand hebt geopend en een map hebt gevonden, kunt u de berichten ervan weergeven, korte berichtinformatie lezen, grote mappen filteren en pagina’s doorbladeren, en individuele berichten extraheren als MapiMessage objecten. Dit artikel behandelt al deze bewerkingen.

Berichten in een map weergeven

De OlmFolder klasse biedt twee manieren om over de berichten te itereren die het bevat:

EnumerateMessages geeft een OlmMessageInfo object bij elke iteratie. Dit object bevat korte informatie over het bericht en is de meest efficiënte manier om een map te scannen.
EnumerateMapiMessages geeft een volledige MapiMessage object bij elke iteratie, met alle eigenschappen van het bericht geladen.

EnumerateMessages gebruiken

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

EnumerateMapiMessages gebruiken

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

Berichtinformatie lezen

Elke OlmMessageInfo object biedt een reeks alleen-lezen eigenschappen die een bericht beschrijven zonder de volledige inhoud te laden. Dit is de meest efficiënte manier om een lijstweergave te bouwen of om te beslissen welke berichten moeten worden geëxtraheerd.

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

De gewijzigde datum van een bericht ophalen

De gewijzigde datum vertegenwoordigt de datum en tijd waarop het OLM‑bericht voor het laatst is aangepast. Gebruik de OlmMessageInfo.ModifiedDate eigenschap om deze te lezen:

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

Berichten filteren met een query

Voor grote mappen kunt u alleen de berichten ophalen die aan een criteria‑set voldoen in plaats van alles te doorlopen. Geef een MailQuery naar de EnumerateMessages(MailQuery query) overload. Bouw de query met een MailQueryBuilder.

Het voorbeeld hieronder enumerateert alleen de berichten die in de afgelopen zeven dagen zijn ontvangen en waarvan het onderwerp het woord "Factuur" bevat:

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

Door berichten bladeren

Wanneer een map een groot aantal berichten bevat, kunt u ze in batches lezen met de EnumerateMessages(int skip, int count) overload. De skip parameter is het aantal berichten dat moet worden overgeslagen, en count is het aantal berichten dat moet worden geretourneerd.

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

Een bericht extraheren als MapiMessage

De OlmStorage class biedt de ExtractMapiMessage methode, die een volledige MapiMessage van een OlmMessageInfo object. Dit is nuttig wanneer u eerst een map scant met EnumerateMessages en vervolgens alleen de berichten extraheren die u daadwerkelijk nodig heeft.

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

Berichten extraheren op identifier

Soms moet u geselecteerde berichten extraheren via hun identifiers. Bijvoorbeeld, een applicatie kan identifiers in een database opslaan en een bericht op aanvraag extraheren in plaats van elke keer de volledige opslag te doorlopen. De EntryId eigenschap van OlmMessageInfo biedt de bericht‑entry‑identifier, en de overladen ExtractMapiMessage(string id) methode haalt het bericht op via die identifier.

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

Items extraheren met de Traversal‑API

U kunt elk item uit een OLM‑bestand extraheren – zo veel mogelijk – zonder uitzonderingen te gooien, zelfs wanneer sommige gegevens in het originele bestand corrupt zijn. Maak hiervoor de OlmStorage instantie met de OlmStorage(TraversalExceptionsCallback callback) constructor en laad het bestand met de Load methode. De callback maakt de laad‑ en doorloop‑uitzonderingen bekend.

De Load methode retourneert true als het bestand succesvol is geladen en doorlopen mogelijk is, en false als het bestand corrupt is en doorlopen niet mogelijk is. Merk op dat wanneer u items map voor map doorloopt, u de opslag‑ EnumerateMessages(OlmFolder folder) methode, waarbij de map als argument wordt doorgegeven.

De stappen zijn:

Maak een nieuwe OlmStorage instantie, met een callback voor foutafhandeling.
Laad het OLM‑bestand door de Load methode.
Als het bestand succesvol wordt geladen, verkrijg dan de maphiërarchie door te roepen GetFolders.
Loop recursief door elke map. Voor mappen die berichten bevatten, tel ze op met de opslag‑ EnumerateMessages methode en verwerk elk ervan.
Recurseer in eventuele onderliggende mappen.

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: Items tellen en werken met categorieën

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

Naast het lezen van individuele berichten, stelt Aspose.Email voor .NET u in staat te inspecteren hoeveel items een OLM‑bestand of een map bevat en de Outlook‑categorieën – inclusief hun kleuren – die in het bestand zijn opgeslagen te lezen. Dit artikel behandelt beide.

Controleren of een map berichten bevat

De OlmFolder.HasMessages eigenschap geeft aan of een map berichten bevat, en de OlmFolder.MessageCount eigenschap retourneert hoeveel.

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

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

Aantal items in elke map tellen

Gebruik de OlmFolder.MessageCount eigenschap om het aantal items in elke map van het bestand te rapporteren:

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

Het totale aantal items in de opslag ophalen

De OlmStorage klasse heeft een GetTotalItemsCount() methode die het totale aantal berichtitems in de gehele OLM‑opslag retourneert:

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

Outlook‑categori kleuren ophalen

Om met de Outlook‑itemcategorieën die in een OLM‑bestand zijn opgeslagen te werken, biedt Aspose.Email:

de OlmItemCategory klasse – vertegenwoordigt een Outlook‑itemcategorie, beschikbaar via zijn Name en bijbehorende Kleur, weergegeven in hexadecimale notatie;
de GetCategories() methode van de OlmStorage klasse – haalt de lijst met categorieën op die in de opslag worden gebruikt.

Het volgende voorbeeld somt elke categorie op die in de opslag wordt gebruikt, samen met de bijbehorende kleur:

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

De kleur van een berichtcategorie ophalen

U kunt de categorieën die aan een bepaald bericht zijn toegewezen vergelijken met de categorielijst van de opslag om de kleur van elke categorie op te lossen. Het voorbeeld hieronder leest de categorieën van elk bericht in een map en drukt de kleur ervan af:

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 naar PST converteren

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

OLM is een database‑bestandformaat dat door Microsoft Outlook voor Mac wordt gebruikt. OLM‑bestanden slaan e‑mailberichten, agenda‑data, contacten en applicatie‑instellingen op, en worden niet ondersteund door Outlook voor Windows. Om een postvak van Outlook voor Mac naar Outlook voor Windows te migreren, moet u het OLM‑bestand naar het Outlook PST formaat. Aspose.Email voor .NET laat u dit in code doen, zonder Microsoft Outlook geïnstalleerd te hebben.

Hoe de conversie werkt

Om een OLM‑bestand naar PST te converteren, volg deze stappen:

Maak een instantie van de OlmStorage klasse om het bron‑OLM‑bestand te openen.
Maak een nieuw PST‑bestand met de PersonalStorage.Create methode.
Implementeer een GetContainerClass methode die een berichtklasse aan de bijbehorende map‑ (container‑)klasse koppelt, zodat elke map in de PST met het juiste type wordt aangemaakt.
Implementeer een AddToPst methode die recursief elke map en de bijbehorende berichten uit het OLM‑bestand leest – met behulp van EnumerateMapiMessages - en voegt ze toe aan de PST in dezelfde volgorde, met behulp van de AddSubFolder en AddMessage methoden van FolderInfo.

Codevoorbeeld

De volgende code toont hoe een OLM‑bestand naar PST kan worden geconverteerd.

Main‑methode:

// 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-methode:

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

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

De conversie in de tegenovergestelde richting (PST naar OLM) wordt niet ondersteund, omdat een OLM‑bestand altijd wordt aangemaakt door Outlook voor Mac wanneer een account wordt toegevoegd en gesynchroniseerd met de mailserver.