More .NET libraries
-
Rebex Mail Pack
IMAP, MS Graph, EWS, POP3, SMTP, MIME, S/MIME, MSG
-
Rebex Total Pack
All Rebex .NET libraries together
Back to feature list...
MAPI properties
This API is provided by Rebex.Msg.dll
assembly.
MAPI property IDs
Outlook .MSG files contain three kinds of MAPI properties:
- Tagged properties - identified by a tag (
MsgPropertyTag
enum). - Numerical named properties - with numerical identifier (
MsgPropertyId
andMsgPropertySet
enums). - String named properties - with string identifier (
string
andMsgPropertySet
enum).
// load an MsgMessage
// ...
// display all MAPI properties of the MSG message
foreach (MsgProperty prop in message.Properties)
{
switch (prop.Kind)
{
case MsgPropertyKind.Tagged:
Console.WriteLine("Tagged: {0}", prop.Tag);
break;
case MsgPropertyKind.NumericalNamed:
Console.WriteLine("Numerical: {0}", prop.Id);
break;
case MsgPropertyKind.StringNamed:
Console.WriteLine("String: {0}", prop.Name);
break;
}
}
// get a 'Tagged' property
MsgProperty subject = message.Properties[MsgPropertyTag.Subject];
// get a 'Numerical-named' property
MsgProperty account = message.Properties[MsgPropertyId.InternetAccountName];
// get a 'String-named' property
MsgProperty contentType = message.Properties["content-type"];
' load an MsgMessage
' ...
' display all MAPI properties of the MSG message
For Each prop As MsgProperty In message.Properties
Select Case prop.Kind
Case MsgPropertyKind.Tagged
Console.WriteLine("Tagged: {0}", prop.Tag)
Case MsgPropertyKind.NumericalNamed
Console.WriteLine("Numerical: {0}", prop.Id)
Case MsgPropertyKind.StringNamed
Console.WriteLine("String: {0}", prop.Name)
End Select
Next
' get a 'Tagged' property
Dim subject As MsgProperty = message.Properties(MsgPropertyTag.Subject)
' get a 'Numerical-named' property
Dim account As MsgProperty = message.Properties(MsgPropertyId.InternetAccountName)
' get a 'String-named' property
Dim contentType As MsgProperty = message.Properties("content-type")
MsgPropertySet
in addition to their primary identifiers (MsgPropertyId
or string
).
However, it is uncommon for a MSG message to contain more than one property identified by the same primary identifier from two different property sets.
Therefore, the API is simplified to address properties by the primary identifier only.
In case there are more properties using the same primary identifier, only a property from one property set is returned.
MAPI property data types
MAPI properties are of various data types defined by MsgPropertyDataType
enum
(which corresponds to [MS-OXCDATA] specification).
The particular data type of a MAPI property can be determined using MsgProperty.DataType
property.
MsgProperty.Value
returns and accepts an instance of object
,
but it can be safely casted to a strongly-typed value based on MsgProperty.DataType
property.
When setting MsgProperty.Value
the type of the value must correspond to the type specified by MsgProperty.DataType
property.
MsgPropertyCollection.SetValue<T>()
method as shown in
Getting and setting values section.
// load an MsgMessage
// ...
// get the 'Subject' property
MsgProperty subjectProp = message.Properties[MsgPropertyTag.Subject];
if (subjectProp == null)
throw new InvalidDataException("Subject not found.");
// get the property value based on its data type
string subject;
switch (subjectProp.DataType)
{
case MsgPropertyDataType.String:
case MsgPropertyDataType.String8:
subject = (string)subjectProp.Value;
break;
case MsgPropertyDataType.Binary:
subject = Encoding.UTF8.GetString((byte[])subjectProp.Value);
break;
default:
throw new InvalidDataException("Subject data format is unknown.");
}
' load an MsgMessage
' ...
' get the 'Subject' property
Dim subjectProp As MsgProperty = message.Properties(MsgPropertyTag.Subject)
If subjectProp Is Nothing Then
Throw New InvalidDataException("Subject not found.")
End If
' get the property value based on its data type
Dim subject As String
Select Case subjectProp.DataType
Case MsgPropertyDataType.String, MsgPropertyDataType.String8
subject = CStr(subjectProp.Value)
Case MsgPropertyDataType.Binary
subject = Encoding.UTF8.GetString(CType(subjectProp.Value, Byte()))
Case Else
Throw New InvalidDataException("Subject data format is unknown.")
End Select
Getting and setting values
To add, update or delete a MAPI property, use MsgPropertyCollection.SetValue<T>()
method.
To delete a property, specify the value
argument of null
(Nothing
in VB.NET).
To read a value of a MAPI property, use one of the three methods:
MsgPropertyCollection.GetValue<T>(identifier)
- fails if the property does not exist or has data type other than specified by the generic type parameter<T>
.MsgPropertyCollection.GetValue<T>(identifier, defaultValue)
- returnsdefaultValue
if the property does not exist, but still fails if data type is mismatched.-
MsgPropertyCollection.TryGetValue<T>(identifier, out value)
- safely assigns thevalue
argument and returnstrue
; returnsfalse
if thevalue
argument cannot be assigned (either the property does not exists or data type is mismatched).
// load an MsgMessage
// ...
// get the value of 'Subject' property
string subject = message.Properties.GetValue<string>(MsgPropertyTag.Subject);
// set a new 'Subject' property value
message.Properties.SetValue(MsgPropertyTag.Subject, "New subject");
' load an MsgMessage
' ...
' get the value of 'Subject' property
Dim subject As String = message.Properties.GetValue(Of String)(MsgPropertyTag.Subject)
' set a new 'Subject' property value
message.Properties.SetValue(MsgPropertyTag.Subject, "New subject")
Back to feature list...