Topic Last Modified: 2009-07-15
Microsoft Exchange Server 2007 provides a class library based on the Microsoft .NET Framework that enables you to implement transport agents that programmatically examine and take action on transport events. These agents can read and change message contents during these events. The classes in the Microsoft.Exchange.Data.Transport.Email namespace provide easy access to common e-mail elements. For direct access to Transport Neutral Encapsulation Format (TNEF) or MIME Encapsulation of Aggregate HTML Documents (MHTML) message contents, use the TnefReader, TnefWriter, MimeReader, MimeWriter, and MimeDocument classes.
The following are the prerequisites that are required for you to implement an agent:
A computer that is running Exchange 2007 that has the Edge Transport or the Hub Transport server role installed
Microsoft .NET Framework 2.0 software development kit (SDK)
We also recommend that you install Microsoft Visual Studio .NET 2005 or later.
The two agent types that are available are receive agents and routing agents. Each agent type defines a specific set of events that are available in the context in which they run. For more information about those events, see SmtpReceiveAgent and RoutingAgent.
In your code, reference the following namespaces:
Microsoft.Exchange.Data.Transport.Smtp or Microsoft.Exchange.Data.Transport.Routing
In your agent, implement derived classes that inherit from these classes:
If your classes do not inherit from these two classes, they must inherit from the following two classes:
These agent factory and agent classes provide base properties and methods for accessing transport events and messages. Implement derived classes in your agent that inherit from these classes. In the agent factory derived class, override the CreateAgent method so that it returns a new instance of your agent class.
The SmtpReceiveAgent and RoutingAgent classes define delegates that enable you to handle transport events and extend transport behavior. Arguments that are passed to the events can contain an instance of the EmailMessage object, which you can use to change the properties and contents of the underlying message. Not all message information is available in each event. You must determine from the information that is available in each event which event is best for your agent to handle for optimal performance.
The following example shows a minimal implementation of classes that derive from the SmtpReceiveAgentFactory and SmtpReceiveAgent classes.
Imports System Imports System.Collections.Generic Imports System.Text Imports Microsoft.Exchange.Data.Transport Imports Microsoft.Exchange.Data.Transport.Smtp Namespace MyAgents NotInheritable Class MyAgentFactory Inherits SmtpReceiveAgentFactory Public Overrides Function CreateAgent(ByVal server as SmtpServer) As SmtpReceiveAgent Return New MyAgent End Function End Class Public Class MyAgent Inherits SmtpReceiveAgent Private Sub MyEndOfDataHandler(ByVal source As ReceiveMessageEventSource, ByVal e As EndOfDataEventArgs) Handles Me.OnEndOfData ' The following line appends text to the subject of the message that caused the event. e.MailItem.Message.Subject &= e.MailItem.Message.Subject + " - this text appended by MyAgent" End Sub End Class End Namespace
After you compile your agent to a dynamic-link library (DLL), you must install and enable the agent on your development Exchange server. In the Exchange Management Shell, use the Install-TransportAgent command to install your agent, and the Enable-TransportAgent command to enable your agent.
|Transport agents have full access to all e-mail messages that they encounter. Exchange 2007 does not restrict the behavior of a transport agent. Transport agents that are unstable or that contain security flaws may affect the stability and security of Exchange 2007. Therefore, you must only install transport agents that you fully trust and that have been fully tested.|
When you use the Install-TransportAgent cmdlet to install an agent, the Exchange Management Shell keeps a lock on the assembly. To release the lock on the assembly, you must close the instance of the management shell that you used to install the agent. You will be unable to update the assembly until you release the lock.
The following example shows you how to use the Exchange Management Shell to install and enable an agent named MyAgent by using a class derived from SmtpReceiveAgentFactory named MyAgents.MyAgentFactory.
Install-TransportAgent -Name "MyCustomAgent" -TransportAgentFactory "MyAgents.MyAgentFactory" -AssemblyPath "C:\myagents\MyAgent.dll"
This example names the agent MyCustomAgent on the server on which the agent is installed. The following example shows you how to enable the agent named MyCustomAgent.
Enable-TransportAgent -Name "MyCustomAgent"