Transport Agents
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.
Implementing a Transport Agent
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.
Requirements for Implementing a Transport Agent
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
- Microsoft.Exchange.Data.Transport.Smtp or Microsoft.Exchange.Data.Transport.Routing
In your agent, implement derived classes that inherit from these classes:
- SmtpReceiveAgentFactory
- SmtpReceiveAgent
If your classes do not inherit from these two classes, they must inherit from the following two classes:
- RoutingAgentFactory
- RoutingAgent
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.
Responding to Transport Events
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.
Transport Agent Implementation Example
The following example shows a minimal implementation of classes that derive from the SmtpReceiveAgentFactory and SmtpReceiveAgent classes.
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Exchange.Data.Transport;
using Microsoft.Exchange.Data.Transport.Smtp;
namespace MyAgents
{
public sealed class MyAgentFactory : SmtpReceiveAgentFactory
{
public override SmtpReceiveAgent CreateAgent(SmtpServer server)
{
return new MyAgent();
}
}
public class MyAgent : SmtpReceiveAgent
{
public MyAgent()
{
this.OnEndOfData += new EndOfDataEventHandler(MyEndOfDataHandler);
}
private void MyEndOfDataHandler (ReceiveMessageEventSource source, EndOfDataEventArgs e)
{
// The following line appends text to the subject of the message that caused the event.
e.MailItem.Message.Subject += " - this text appended by MyAgent";
}
}
}
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
Installing and Enabling an Agent
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.
Warning
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"