Reading and modifying messages in the Exchange 2013 transport pipeline
Learn about the .NET Framework classes you can use in your Exchange 2013 transport agents to read, write, and modify messages.
Applies to: Exchange Server 2013
- Classes used to read, write, or modify messages
- Encoders namespace
- iCalendar namespace
- MIME namespace
- TextConverters namespace
- Tnef namespace
- vCard namespace
As messages pass through the transport pipeline, your transport agent can read, write, and convert message content between different data formats. For example, you can read and write MIME data, identify incoming messages that are in Uuencoded or Quoted-printable (qp) format, and then convert them to a standard used by your organization, or read and then save calendar or contact information associated with incoming messages.
You can also identify content that poses a security threat and move or delete the content or the messages that contain them; for example, by removing links in an HTML message.
This article provides information about the .NET Framework classes that you can use to read, write, and modify messages.
Caution
Many of the properties and parameters in the content conversion APIs allow values large enough to cause performance problems, including denial of service. When you use the content conversion APIs in a transport agent, you should implement limits on the property and parameter value sizes you support when reading or writing in order to limit resource consumption by your agent.
Classes used to read, write, or modify messages
The following table lists the .NET Framework classes that you can use to read, write, and modify email messages.
.NET Framework message processing namespaces
| .NET Framework namespace | Classes |
|---|---|
| Microsoft.Exchange.Data.Mime.Encoders |
Contains classes for in-memory encoding and decoding, an encoder stream class that accepts one of the encoder or decoder classes contained in an associated enumeration, and the ByteEncoder base class and ByteEncoderException exception class for the encoders and decoders. |
| Microsoft.Exchange.Data.ContentTypes.iCalendar |
Contains types that enable you to read and write data streams that contain calendar information. Includes a calendar reader and writer, an exception object, a recurrence object, and structures and enumerations that help you return property information about calendar items. |
| Microsoft.Exchange.Data.Mime |
Contains classes, structures, enumerations, and delegates that you can use to create, read, write, traverse, encode, and decode MIME data. Includes a stream-based reader and writer that gives you forward-only read and write access to MIME data streams, as well as DOM-based methods and classes you can use on MIME documents. |
| Microsoft.Exchange.Data.TextConverters |
Contains classes, structures, enumerations, and delegates that allow you to read and write a data stream and perform conversions between specific data types; for example, HTML to Rich Text Format (RTF). Text converters enable you to change the format of a document stream from one form to another as well as selectively remove elements of a document that might pose a security risk. |
| Microsoft.Exchange.Data.ContentTypes.Tnef |
Contains a forward-only stream reader and writer, an exception class, and structures and enumerations that facilitate reading and writing Transport Neutral Encapsulation Format (TNEF) data. |
| Microsoft.Exchange.Data.ContentTypes.vCard |
Contains a forward-only stream reader and writer, an exception class, and structures and enumerations that facilitate reading and writing vCard-formatted contact data. |
Encoders namespace
The Encoders namespace contains classes for in-memory encoding and decoding. These inherit from the ByteEncoder base class. Classes encode and decode for Base64, BinHex, Quoted-printable (qp), and Unix-to-Unix (Uu). The following classes are used for in-memory encoding and decoding:
The encoders and decoders inherit from the ByteEncoder base class and use the ByteEncoderException exception class for error handling.
Additionally, the namespace contains the MacBinaryHeader class, which identifies MacBinary encoded files and reads their associated file header.
Finally, the EncoderStream class performs a conversion on a data stream instead of an in-memory object. This class accepts one of the encoder or decoder classes and either reads or writes according to the associated EncoderStreamAccess enumeration.
iCalendar namespace
The iCalendar namespace provides a forward-only reader and writer for iCalendar data, in addition to supporting structures and classes for creating, accessing, and modifying iCalendar streams.
The CalendarReader and CalendarWriter classes are used to read and write iCalendar stream data.
The CalendarReader takes a readable Stream as an argument to its constructors. You can then use the ReadFirstChildComponent, ReadNextSiblingComponent, and ReadNextComponent methods to sequentially access the iCalendar components in the data stream. Based on the value that you have set for the ComplianceMode property, errors in the iCalendar stream will cause an exception to be thrown or will cause the ComplianceStatus property to be set to a value other than Compliant. You can check this property to discover any issues with incoming iCalendar data.
The CalendarWriter class takes a writable Stream as an argument to its constructors.
MIME namespace
The MIME namespace provides classes that enable you to create, access, and modify MIME documents. You can work with MIME documents by using either a stream-based or DOM-based method.
MimeDocument class and the MIME DOM
The MimeDocument class enables DOM access to a MIME document. Use objects of this type when you have the available memory to load a whole DOM and you must have random access to the headers and content of the message.
You load data into a MimeDocument object by using the GetLoadStream or Load methods. You can then walk the DOM hierarchy and create, modify, or remove MIME data. After you have modified the MIME data, you can write it to a stream by using one of the WriteTo methods.
The following figure shows the structure of data within a MimeDocument object.
Figure 1. Structure of MimeDocument objects
MimeReader and MimeWriter classes and stream-based MIME parsing
The MimeReader and MimeWriter classes enable forward-only access to MIME streams. Use these classes when you do not have to change the MIME data that requires data that has already been read or written. For example, if you want to print messages that fit a predefined format, the MimeWriter class might be ideal.
The MimeDocument class encapsulates a DOM. The MimeReader and MimeWriter classes represent state computers. Their states change based on the input received and the methods called. Figures 2 through 5 are simplified state transition diagrams that show, for the MimeReader object, which methods are valid to call from each state and the state that will result.
To use these diagrams, follow the arrows from one state to the next, noting the method calls or return values that cause the state to change. For example, in the first diagram, assume that you are at the start of the stream that belongs to the MimeReader that you have created. To get to the Part Headers state, call one of ReadNextPart or ReadFirstChildPart, in that order. If there are headers (that is, if the MIME is well-formed), you will enter into the Part Headers state. Otherwise, an exception will be thrown.
Figure 2. Simplified state transition diagram for MimeReader objects
Note
Figures 3, 4, and 5 expand on states shown in each of the previous diagrams.
Figure 3. Expansion of Part Headers state from Figure 2
Figure 4. Expansion of Header state from Figure 3 when a parameter has been encountered in a header
Note
The state represented by Figure 5 is recursive in that, if an address group is encountered, you can use the GroupRecipientReader property to read the addresses in the group.
Figure 5. Expansion of Header state from Figure 3 when an address or address group is encountered
Figures 6 and 7 show simplified state transition diagrams for the MimeWriter object.
Note
Figure 7 expands on the Part Headers state shown in Figure 6.
Figure 6. Simplified state transition diagram for MimeWriter objects
Figure 7. Expansion of Part Headers state from Figure 6
TextConverters namespace
The TextConverters namespace contains types that support the conversion of the contents of email messages. These types can perform code page conversion, remove HTML that is not secure, and perform other transformations on email message bodies. The Microsoft.Exchange.Data.TextConverters namespace includes the following classes that derive from the TextConverter abstract class:
These text converters enable you to change the format of a document stream or to remove elements that are not secure from an HTML document. These classes can be used by themselves to perform a conversion by using a single call to one of the Convert methods in the TextConverter base class, or they can be passed to a constructor of the converter, which uses it to perform converted reads or writes.
The functionality inherited from the base class is useful for performing conversions when you have sufficient space to store the original document and its converted output, or when you want to store the results of the conversion. The Convert method takes input and output streams, text readers, or text writers, and converts the content of the input to the associated output.
Also included in the namespace are the following text reader, writer, and stream classes:
ConverterReader — Derived from System.IO.TextReader.
ConverterWriter — Derived from System.IO.TextWriter.
ConverterStream — Derived from System.IO.Stream.
These are used to perform conversions when you do not have room to store the original or its converted output, when you receive the input from or send the output to a stream, or when you want the output only for indexing or search purposes and therefore do not want to store the result of a conversion.
Tnef namespace
The Tnef namespace contains classes and types that enable forward-only stream-based reading and writing of TNEF data. TNEF is a data format that is used to encapsulate MAPI properties for clients that cannot interpret MAPI.
The TnefReader and TnefWriter classes provide the core functionality in the Microsoft.Exchange.Data.ContentTypes.Tnef namespace.
The TnefReader class takes a readable stream as an argument to its constructors. You then use the ReadNextAttribute method to sequentially read the attributes in the TNEF stream. After you have read an attribute, you can access information about the attribute by using any of the read-only properties on the TnefReader object, in addition to getting a TnefPropertyReader to read the current property. You can also directly access the current attribute by using the ReadAttributeRawValue method.
The TnefWriter class takes a writable Stream as an argument to its constructors. The TnefWriter class provides multiple ways in which to write data to this stream.
vCard namespace
The vCard namespace contains classes, structures, and enumerations used to read and write contact information contained in an email message that is in the vCard data format. The namespace contains a contact reader and writer, an exception class, a property reader, a parameter reader, and supporting enumerations that allow you to read vCard data associated with an email message.