Transport Agents
Microsoft Exchange Server 2010 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 TNEF or MIME 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 running Exchange 2010 that has the Edge Transport or the Hub Transport server role installed
The Microsoft .NET Framework 2.0 SDK
We also recommend that you install Microsoft Visual Studio 2008. You can implement transport agents by using either Microsoft Visual Basic .NET or C#.
Requirements for Implementing a Transport Agent
The three agent types that are available are SMTP receive agents, routing agents, and delivery 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 the following:
In your code, reference the Microsoft.Exchange.Data.Transport namespace. Add a reference to the namespace specific to the type of transport agent you are implementing. The following table lists the namespace to reference for each type of transport agent.
Agent Type |
Namespace |
|---|---|
SMTP Receive |
|
Routing |
|
Delivery |
In your agent, implement derived classes that inherit the respective factory and agent base classes for the type of agent that you are implementing. The following table lists the classes from which to derive for each agent type.
Agent Type |
Factory Base Class |
Agent Base Class |
|---|---|---|
SMTP Receive |
||
Routing |
||
Delivery |
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, RoutingAgent, and DeliveryAgent 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 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 2010 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 2010. 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"