Understanding Transport Agents (Part 2)

If you missed the first part in this article series please read Understanding Transport Agents (Part 1).


Managing Transport Agents


We are able to list, enable, disable or change Transport Agent priority.


To list all the transport Agents which are running on a server please look at Figure 06.


Figure 06: Listing all the Transport Agents


We can see more details for each Transport Agent by using the “| fl” after the Get-TransportAgent cmdlet (Figure 07). This will display information such as TransportAgentFactory and the DLL used by the Transport Agent.


Figure 07: More information about installed Transport Agents


To disable a Transport Agent, we can use the cmdlet Disable-Transport Agent, as shown in the Figure 08. When we disable a Transport Agent we have to confirm by typing Y when asked.


Figure 08: Disabling a Transport Agent


To enable a Transport Agent, we can use Enable-TransportAgent (Figure 09). Take a look at the Enabled column before and after the cmdlet.


Figure 09: Enabling a Transport Agent


Another important feature is the priority of Transport Agents. We can also change priority using the cmdlet called Set-TransportAgent, as shown in Figure 10. Check out the Priority before and after the cmdlet Set-TransportAgent.


Figure 10: Changing the Transport Agent priority


We can set any priority for any installed transport agents and for new Transport Agents added by third party applications. Using priority, we can control which agents will act on a message first. The lower numbered priority will be applied before the higher numbered priorities. Priority is utilized when we have two or more Transport Agents using the same SMTP Event. When we have different SMTP Events we have to follow the SMTP Event order not the priority.


One example: If we have priority 1 for an agent that uses the SMTP Event OnEndOfData and a priority of 2 to another Transport Agent that uses the SMTP Event OnConnect, the Transport Agent that is using OnConnect will run first, because OnConnect goes before OnEndOfData in the transport pipeline sequence.


Finally, we can see the Transport pipeline using the cmdlet Get-TransportPipeline, as shown in Figure 11.


Figure 11: SMTP Events and the agents related to them


Troubleshooting Transport agents


In some cases, we have to ensure that the agent is doing its job within a message. We can accomplish this using the Pipeline tracing feature which allows us to create an exact snapshot of a whole message before and after it encounters each transport agent. Each step of the process is kept in a directory for troubleshooting reasons.


To verify the usefulness of Pipeline tracing, we will create a transport rule at Edge level that adds text into the subject field. After that we are will use Pipeline tracing to track the Sender [email protected] so we can validate Transport Agent processes in the messages sent from [email protected]


To create Pipeline tracing, we can use the following cmdlet:


Set-TransportServer <server> -PipelineTracingEnabled:$true –PipelineTracingSenderAddress <smtp address or X500 address>




PipelineTracingEnabled: we are going to enable Pipeline tracing


PipelinetracingSenderAddress: for the users in the same site we can use either X500 address or SMTP and for external we use SMTP address.


In Figure 12 we can see the execution of the Set-TransportServer cmdlet. By default the directory where pipeline tracing generates the files is located under <Exchange Server directory installation>\TransportRoles\Logs\Pipeline Tracing\MessageSnapshots\<ID>\


Figure 12: Enabling Pipeline tracing for the sender [email protected]


In the above mentioned directory we can see all of the snapshots of the single message that has pipeline tracing enabled (Figure 13). Each file has information about Transport agents.


Figure 13: The directory where Pipeline tracing is saved


If we open any message within the directory using Notepad, we can see a header called X-Message-Snapshot-source that says which SMTP Event is being used and which Transport Agent is being applied on the message. We can see that the message sent from [email protected] for an internal user, received the Transport rule at Edge level when it was passing through the SMTP pipeline called OnEndofData in the Edge Transport Server, as shown in Figure 14.


Figure 14: The specific SMTP Event and the Transport Agent shown through pipeline tracing


After validation of the Transport Agent processes, you should turn off pipeline tracing, as shown in the Figure 15.


Figure 15: Disabling the Pipeline tracing using the Set-TransportServer cmdlet


Notes about pipeline tracing:



  • Pipeline tracing copies all the message content. For security reasons you should define a directory protected by ACLs only for authorized personnel.
  • Do not enable pipeline tracing for long periods of time, because there are a lot of verbose files that will be created and may cause disk space problems.
  • To find the X500 address for internal users, you can use the Message Tracking log file.
  • After disabling pipeline tracing, it is highly recommended that you delete all the information collected in that period.


Can I develop my own Transport Agent?


Yes, you can do that easily. It’s recommended to use Microsoft Visual Studio .NET 2005 to accomplish that. There is a sample on the MSDN web site that can be found at http://msdn2.microsoft.com/en-us/library/aa579185.aspx.


Note: Transport agents have full access to all messages that pass through them. That means that there are no restrictions on the transport agent’s behavior. If the Transport Agent is unstable or has security problems the Exchange Server may be affected. You must ensure that any Transport Agents have been fully tested and that they are reliable enough to run in a production environment.


Installing, removing, and enabling your own Transport Agent


After you create your own transport Agent, you need to compile your agent to a DLL (dynamic-link library). After you build the DLL, go to the server which will receive the new transport agent and follow these steps:


To install the Transport Agent use the cmdlet Install-TransportAgent, as follows:


Install-TransportAgent –Name <Name> –TransportAgentFactory “MyAgents.MyAgentFactory” –AssemblyPath <path>


Note: You cannot use the UNC path in the AssemblyPath in the Install-TransportAgent cmdlet.


To enable the new Transport Agent run this cmdlet:


Enable-TransportAgent –Name “SampleAgent”


To remove a previously installed Transport Agent use this syntax:


Uninstall-TransportAgent “SampleAgent”




In this article we’ve seen how to manage and troubleshoot Transport Agents. They will be utilized by various vendors in the near future, antivirus, reporting, etc, to add more functions to Exchange Server 2007.


More Information:


Developing Transport Agents


If you missed the first part in this article series please read Understanding Transport Agents (Part 1).

Leave a Comment

Your email address will not be published.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Scroll to Top