OutlookMessage Class

Definition

Namespace

Bodu.Formats.Outlook

Assembly

Bodu.Formats.Outlook.Msg.dll

Package

Bodu.Formats.Outlook.Msg 0.7.1

Source

OutlookMessage.Attachments.cs

Provides a disposable, read-only session over an Outlook message (.msg / MS-OXMSG), exposing every decoded MAPI property together with curated conveniences for the common message fields.

public sealed class OutlookMessage : IDisposable

Inheritance

object

OutlookMessage

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

A .msg file is an OLE2 compound file; opening a message opens the container through CompoundFile and decodes the root property stream eagerly, so the property surface is available without further I/O. The session owns the container and, unless the caller opts to leave it open, the source stream; dispose the message when reading is complete.

Every property is reachable through Properties; the scalar conveniences (Subject, SenderName, the time stamps, and the rest) are lazy views over that collection and return null when the underlying property is absent.

using Bodu.Formats.Outlook;

using var message = OutlookMessage.OpenRead("invoice.msg");

Console.WriteLine(message.Subject);
Console.WriteLine(message.SenderEmailAddress);

Properties

Attachments

Gets the attachments of the message, in storage-index order.

public IReadOnlyList<OutlookAttachment> Attachments { get; }

Property Value

IReadOnlyList<OutlookAttachment>

The attachment list; empty when the message declares no attachments.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

Thrown under strict validation when the attachment storages are inconsistent with the declared count.

BodyHtml

Gets the HTML body.

public string? BodyHtml { get; }

Property Value

string

The PidTagHtml payload decoded through the message's internet code page (falling back to the message code page), or the value verbatim when the writer stored it as a string; null when absent. The body is decoded once and the same instance returned thereafter.

Exceptions

ObjectDisposedException

The message has been disposed.

BodyRtf

Gets the RTF body, decompressed from PidTagRtfCompressed per MS-OXRTFCP.

public string? BodyRtf { get; }

Property Value

string

The RTF text, or null when the property is absent or DecompressRtf is disabled (the raw payload stays available through Properties). The body is decompressed once and the same instance returned thereafter.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

The compressed payload is malformed, fails its checksum, or decompresses beyond MaxDecompressedRtfBytes.

BodyText

Gets the plain-text body.

public string? BodyText { get; }

Property Value

string

The PidTagBody value, or null when absent.

EmbeddedDepth

Gets the embedded-message nesting depth of this session: zero for a message opened from a file or stream, one more for each level opened through OpenMessage().

public int EmbeddedDepth { get; }

Property Value

int

The nesting depth.

InternetMessageId

Gets the internet message identifier.

public string? InternetMessageId { get; }

Property Value

string

The PidTagInternetMessageId value, or null when absent.

MessageClass

Gets the message class (for example, IPM.Note).

public string? MessageClass { get; }

Property Value

string

The PidTagMessageClass value, or null when absent.

Properties

Gets every decoded MAPI property of the message.

public MapiPropertyCollection Properties { get; }

Property Value

MapiPropertyCollection

The tag-addressed property collection.

Exceptions

ObjectDisposedException

The message has been disposed.

ReceivedTime

Gets the time the message was delivered.

public DateTimeOffset? ReceivedTime { get; }

Property Value

DateTimeOffset?

The PidTagMessageDeliveryTime value, or null when absent.

Recipients

Gets the recipients of the message, in storage-index order.

public IReadOnlyList<OutlookRecipient> Recipients { get; }

Property Value

IReadOnlyList<OutlookRecipient>

The recipient list; empty when the message declares no recipients.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

Thrown under strict validation when the recipient storages are inconsistent with the declared count.

SenderEmailAddress

Gets the sender email address.

public string? SenderEmailAddress { get; }

Property Value

string

The PidTagSenderEmailAddress value, or null when absent.

SenderName

Gets the sender display name.

public string? SenderName { get; }

Property Value

string

The PidTagSenderName value, or null when absent.

SentTime

Gets the time the message was submitted by the sending client.

public DateTimeOffset? SentTime { get; }

Property Value

DateTimeOffset?

The PidTagClientSubmitTime value, or null when absent.

Subject

Gets the message subject, with the MAPI subject-prefix marker removed when a writer stored one.

public string? Subject { get; }

Property Value

string

The normalized PidTagSubject value, or null when absent; the stored value remains available through Properties.

TransportMessageHeaders

Gets the transport message headers.

public string? TransportMessageHeaders { get; }

Property Value

string

The PidTagTransportMessageHeaders value, or null when absent.

Methods

Dispose()

Releases the container and, unless it was left open, the source stream. Disposing a nested message obtained from an attachment is a no-op - the root session owns the container, and the nested session's decoded properties stay readable until the root is disposed, after which every nested session throws ObjectDisposedException as well.

public void Dispose()

IsMsgFile(Stream)

Determines whether a stream carries an Outlook message: an OLE2 compound file whose root storage holds the message property stream.

public static bool IsMsgFile(Stream stream)

Parameters

stream Stream

The readable, seekable stream to sniff; its position is restored before returning.

Returns

bool

true when the stream looks like a .msg file.

Remarks

The check does not require the conventional root class identifier - real-world writers frequently omit it - so the presence of the __properties_version1.0 stream is the discriminator.

Exceptions

ArgumentNullException

Thrown if stream is null.

Open(Stream, OutlookMessageReaderOptions, bool)

Opens a message from a stream with explicit options.

public static OutlookMessage Open(Stream stream, OutlookMessageReaderOptions options, bool leaveOpen = false)

Parameters

stream Stream

The readable, seekable source stream positioned at the container start.

options OutlookMessageReaderOptions

The reader options.

leaveOpen bool

true to leave the stream open when the message is disposed.

Returns

OutlookMessage

The opened message session.

Exceptions

ArgumentNullException

Thrown if stream or options is null.

OutlookMsgFormatException

The stream is not a compound file, the container is malformed, or the message is not valid.

OpenRead(Stream, bool)

Opens a message from a stream with default options.

public static OutlookMessage OpenRead(Stream stream, bool leaveOpen = false)

Parameters

stream Stream

The readable, seekable source stream positioned at the container start.

leaveOpen bool

true to leave the stream open when the message is disposed.

Returns

OutlookMessage

The opened message session.

Exceptions

ArgumentNullException

Thrown if stream is null.

OutlookMsgFormatException

The stream is not a compound file or not a valid message.

OpenRead(string)

Opens a message from a file path.

public static OutlookMessage OpenRead(string path)

Parameters

path string

The path of the .msg file.

Returns

OutlookMessage

The opened message session.

Exceptions

ArgumentNullException

Thrown if path is null.

OutlookMsgFormatException

The file is not a compound file or not a valid message.

TryGetNamedPropertyId(MapiNamedProperty, out ushort)

Attempts to resolve the property identifier a named property maps to in this message.

public bool TryGetNamedPropertyId(MapiNamedProperty name, out ushort id)

Parameters

name MapiNamedProperty

The named-property identity.

id ushort

When this method returns true, the file-specific identifier (at or above 0x8000) the name maps to; combine it with the expected MapiPropertyType to address Properties.

Returns

bool

true when the message maps the name.

Exceptions

ObjectDisposedException

The message has been disposed.

TryGetPropertyName(MapiPropertyTag, out MapiNamedProperty)

Attempts to resolve the named-property identity behind a property tag.

public bool TryGetPropertyName(MapiPropertyTag tag, out MapiNamedProperty name)

Parameters

tag MapiPropertyTag

A tag whose identifier is in the named range (at or above 0x8000).

name MapiNamedProperty

When this method returns true, the identity.

Returns

bool

true when the message maps the tag's identifier.

Exceptions

ObjectDisposedException

The message has been disposed.

Applies to

Product	Versions
.NET	8, 10