This is a wrap-up of an older post that had originally been published on my former website.
Even though that this post focusses on Exchange 2010 transport agents, you will get an understand on what is required to create an Exchange 2013/2016 aka Version 15 transport agent.
Writing your own transport agent for Exchange 2010 is not really complicated. With a Visual Studio C# Class project you are ready to go.
The follow picture shows the Visual Studio Solution as it has been used for the Message Modifier Solution.
Besides the C# class the solution contains the following Powershell script to simplify development and deployment:
The transport agent intercepts a message from a given sender address and performs the following actions:
// AttachmentModify // ---------------------------------------------------------- // Example for intercepting email messages in an Exchange 2010 transport queue // // The example intercepts messages sent from a configurable email address(es) // and checks the mail message for attachments have filename in to format // // WORKBOOK_{GUID} // // Changing the filename of the attachments makes it easier for the information worker // to identify the reports in the emails and in the file system as well. // Copyright (c) Thomas Stensitzki // ---------------------------------------------------------- using System; using System.Collections.Generic; using System.Diagnostics; using System.Globalization; using System.IO; using System.Reflection; using System.Text; using System.Text.RegularExpressions; using System.Threading; using System.Xml; // the lovely Exchange using Microsoft.Exchange.Data.Transport; using Microsoft.Exchange.Data.Transport.Smtp; using Microsoft.Exchange.Data.Transport.Email; using Microsoft.Exchange.Data.Transport.Routing; namespace SFTools.Messaging.AttachmentModify { #region Message Modifier Factory /// <summary> /// Message Modifier Factory /// </summary> public class MessageModifierFactory : RoutingAgentFactory { /// <summary> /// Instance of our transport agent configuration /// This is for a later implementation /// </summary> private MessageModifierConfig messageModifierConfig = new MessageModifierConfig(); /// <summary> /// Returns an instance of the agent /// </summary> /// <param name="server">The SMTP Server</param> /// <returns>The Transport Agent</returns> public override RoutingAgent CreateAgent(SmtpServer server) { return new MessageModifier(messageModifierConfig); } } #endregion #region Message Modifier Routing Agent /// <summary> /// The Message Modifier Routing Agent for modifying an email message /// </summary> public class MessageModifier : RoutingAgent { // The agent uses the fileLock object to synchronize access to the log file private object fileLock = new object(); /// <summary> /// The current MailItem the transport agent is handling /// </summary> private MailItem mailItem; /// <summary> /// This context to allow Exchange to continue processing a message /// </summary> private AgentAsyncContext agentAsyncContext; /// <summary> /// Transport agent configuration /// </summary> private MessageModifierConfig messageModifierConfig; /// <summary> /// Constructor for the MessageModifier class /// </summary> /// <param name="messageModifierConfig">Transport Agent configuration</param> public MessageModifier(MessageModifierConfig messageModifierConfig) { // Set configuration this.messageModifierConfig = messageModifierConfig; // Register an OnRoutedMessage event handler this.OnRoutedMessage += OnRoutedMessageHandler; } /// <summary> /// Event handler for OnRoutedMessage event /// </summary> /// <param name="source">Routed Message Event Source</param> /// <param name="args">Queued Message Event Arguments</param> void OnRoutedMessageHandler(RoutedMessageEventSource source, QueuedMessageEventArgs args) { lock (fileLock) { try { this.mailItem = args.MailItem; this.agentAsyncContext = this.GetAgentAsyncContext(); // Get the folder for accessing the config file string dllDir = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location); // Fetch the from address from the current mail item RoutingAddress fromAddress = this.mailItem.FromAddress; Boolean boWorkbookFound = false; // We just want to modifiy subjects when we modified an attachement first #region External Receive Connector Example // CHeck first, if the mail item does have a ReceiveConnectorName property first to prevent ugly things to happen if (mailItem.Properties.ContainsKey("Microsoft.Exchange.Transport.ReceiveConnectorName")) { // This is just an example, if you want to do something with a mail item which has been received via a named external receive connector if (mailItem.Properties["Microsoft.Exchange.Transport.ReceiveConnectorName"].ToString().ToLower() == "externalreceiveconnectorname") { // do something fancy with the email } } #endregion RoutingAddress catchAddress; // Check, if we have any email addresses configured to look for if (this.messageModifierConfig.AddressMap.Count > 0) { // Now lets check, if the sender address can be found in the dictionary if (this.messageModifierConfig.AddressMap.TryGetValue(fromAddress.ToString().ToLower(), out catchAddress)) { // Sender address found, now check if we have attachments to handle if (this.mailItem.Message.Attachments.Count != 0) { // Get all attachments AttachmentCollection attachments = this.mailItem.Message.Attachments; // Modify each attachment for (int count = 0; count < this.mailItem.Message.Attachments.Count; count++) { // Get attachment Attachment attachment = this.mailItem.Message.Attachments[count]; // We will only transform attachments which start with "WORKBOOK_" if (attachment.FileName.StartsWith("WORKBOOK_")) { // Create a new filename for the attachment // [MODIFIED SUBJECT]-[NUMBER].[FILEEXTENSION] String newFileName = MakeValidFileName(string.Format("{0}-{1}{2}", ModifiySubject(this.mailItem.Message.Subject.Trim()), count + 1, Path.GetExtension(attachment.FileName))); // Change the filename of the attachment this.mailItem.Message.Attachments[count].FileName = newFileName; // Yes we have changed the attachment. Therefore we want to change the subject as well. boWorkbookFound = true; } } // Have changed any attachments? if (boWorkbookFound) { // Then let's change the subject as well this.mailItem.Message.Subject = ModifiySubject(this.mailItem.Message.Subject); } } } } } catch (System.IO.IOException ex) { // oops Debug.WriteLine(ex.ToString()); this.agentAsyncContext.Complete(); } finally { // We are done this.agentAsyncContext.Complete(); } } // Return to pipeline return; } /// <summary> /// Build a new subject, if the first 10 chars of the original subject are a valid date. /// We muste transform the de-DE format dd.MM.yyyy to yyyyMMdd for better sortability in the email client. /// </summary> /// <param name="MessageSubject">The original subject string</param> /// <returns>The modified subject string, if modification was possible</returns> private static string ModifiySubject(string MessageSubject) { string newSubject = String.Empty; if (MessageSubject.Length >= 10) { string dateCheck = MessageSubject.Substring(0, 10); DateTime dt = new DateTime(); try { // Check if we can parse the datetime if (DateTime.TryParse(dateCheck, out dt)) { // lets fetch the subject starting at the 10th character string subjectRight = MessageSubject.Substring(10).Trim(); // build a new subject newSubject = string.Format("{0:yyyyMMdd} {1}", dt, subjectRight); } } finally { // do nothing } } return newSubject; } /// <summary> /// Replace invalid filename chars with an underscore /// </summary> /// <param name="name">The filename to be checked</param> /// <returns>The sanitized filename</returns> private static string MakeValidFileName(string name) { string invalidChars = Regex.Escape(new string(Path.GetInvalidFileNameChars())); string invalidRegExStr = string.Format(@"[{0}]+", invalidChars); return Regex.Replace(name, invalidRegExStr, "_"); } } #endregion #region Message Modifier Configuration /// <summary> /// Message Modifier Configuration class /// </summary> public class MessageModifierConfig { /// <summary> /// The name of the configuration file. /// </summary> private static readonly string configFileName = "SFTools.MessageModify.Config.xml"; /// <summary> /// Point out the directory with the configuration file (= assembly location) /// </summary> private string configDirectory; /// <summary> /// The filesystem watcher to monitor configuration file updates. /// </summary> private FileSystemWatcher configFileWatcher; /// <summary> /// The from address /// </summary> private Dictionary<string, RoutingAddress> addressMap; /// <summary> /// Whether reloading is ongoing /// </summary> private int reLoading = 0; /// <summary> /// The mapping between domain to catchall address. /// </summary> public Dictionary<string, RoutingAddress> AddressMap { get { return this.addressMap; } } /// <summary> /// Constructor /// </summary> public MessageModifierConfig() { // Setup a file system watcher to monitor the configuration file this.configDirectory = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location); this.configFileWatcher = new FileSystemWatcher(this.configDirectory); this.configFileWatcher.NotifyFilter = NotifyFilters.LastWrite; this.configFileWatcher.Filter = configFileName; this.configFileWatcher.Changed += new FileSystemEventHandler(this.OnChanged); // Create an initially empty map this.addressMap = new Dictionary<string, RoutingAddress>(); // Load the configuration this.Load(); // Now start monitoring this.configFileWatcher.EnableRaisingEvents = true; } /// <summary> /// Configuration changed handler. /// </summary> /// <param name="source">Event source.</param> /// <param name="e">Event arguments.</param> private void OnChanged(object source, FileSystemEventArgs e) { // Ignore if load ongoing if (Interlocked.CompareExchange(ref this.reLoading, 1, 0) != 0) { Trace.WriteLine("load ongoing: ignore"); return; } // (Re) Load the configuration this.Load(); // Reset the reload indicator this.reLoading = 0; } /// <summary> /// Load the configuration file. If any errors occur, does nothing. /// </summary> private void Load() { // Load the configuration XmlDocument doc = new XmlDocument(); bool docLoaded = false; string fileName = Path.Combine(this.configDirectory, MessageModifierConfig.configFileName); try { doc.Load(fileName); docLoaded = true; } catch (FileNotFoundException) { Trace.WriteLine("Configuration file not found: {0}", fileName); } catch (XmlException e) { Trace.WriteLine("XML error: {0}", e.Message); } catch (IOException e) { Trace.WriteLine("IO error: {0}", e.Message); } // If a failure occured, ignore and simply return if (!docLoaded || doc.FirstChild == null) { Trace.WriteLine("Configuration error: either no file or an XML error"); return; } // Create a dictionary to hold the mappings Dictionary<string, RoutingAddress> map = new Dictionary<string, RoutingAddress>(100); // Track whether there are invalid entries bool invalidEntries = false; // Validate all entries and load into a dictionary foreach (XmlNode node in doc.FirstChild.ChildNodes) { if (string.Compare(node.Name, "domain", true, CultureInfo.InvariantCulture) != 0) { continue; } XmlAttribute domain = node.Attributes["name"]; XmlAttribute address = node.Attributes["address"]; // Validate the data if (domain == null || address == null) { invalidEntries = true; Trace.WriteLine("Reject configuration due to an incomplete entry. (Either or both domain and address missing.)"); break; } if (!RoutingAddress.IsValidAddress(address.Value)) { invalidEntries = true; Trace.WriteLine(String.Format("Reject configuration due to an invalid address ({0}).", address)); break; } // Add the new entry string lowerDomain = domain.Value.ToLower(); map[lowerDomain] = new RoutingAddress(address.Value); Trace.WriteLine(String.Format("Added entry ({0} -> {1})", lowerDomain, address.Value)); } // If there are no invalid entries, swap in the map if (!invalidEntries) { Interlocked.Exchange<Dictionary<string, RoutingAddress>>(ref this.addressMap, map); Trace.WriteLine("Accepted configuration"); } } } #endregion }
I came across an interesting issue when setting up a new Exchange 2013 server in an Exchange organization having the cmdlet extension agent enabled.
As mentioned in my last post Exchange setup checks for the existence of the ScriptingAgentConfig.xml file when agent extenstion is enabled in the Exchange organization. It turned out that this ist not only true when you install an Exchange update using /mode:update, but as well when installing a new Exchange server using /mode:install.
The following error occurs when Exchange Management Tools are provisioned.
Configuring Microsoft Exchange Server Preparing Setup COMPLETED Stopping Services COMPLETED Copying Exchange Files COMPLETED Language Files COMPLETED Restoring Services COMPLETED Language Configuration COMPLETED Exchange Management Tools FAILED The following error was generated when "$error.Clear(); Set-WERRegistryMarkers; " was run: "Microsoft.Exchange.Provisioning.ProvisioningBrokerException: Provisioning layer initialization failed: '"Scripting Agent initialization failed: "File is not found: 'C:\Program File s\Microsoft\Exchange Server\V15\Bin\CmdletExtensionAgents\ScriptingAgentConfig.xml'.""' ---> Microso ft.Exchange.Provisioning.ProvisioningException: "Scripting Agent initialization failed: "File is not found: 'C:\Program Files\Microsoft\Exchange Server\V15\Bin\CmdletExtensionAgents\ScriptingAgentConf ig.xml'."" ---> System.IO.FileNotFoundException: "File is not found: 'C:\Program Files\Microsoft\Exc hange Server\V15\Bin\CmdletExtensionAgents\ScriptingAgentConfig.xml'." at Microsoft.Exchange.ProvisioningAgent.ScriptingAgentConfiguration.Initialize(String xmlConfigPa th) at Microsoft.Exchange.ProvisioningAgent.ScriptingAgentConfiguration..ctor(String xmlConfigPath) --- End of inner exception stack trace --- at Microsoft.Exchange.ProvisioningAgent.ScriptingAgentConfiguration..ctor(String xmlConfigPath) at Microsoft.Exchange.ProvisioningAgent.ScriptingAgentClassFactory.get_Configuration() at Microsoft.Exchange.ProvisioningAgent.ScriptingAgentClassFactory.GetSupportedCmdlets() at Microsoft.Exchange.Provisioning.ProvisioningBroker.BuildHandlerLookupTable(CmdletExtensionAgen t[] enabledAgents, Exception& ex) --- End of inner exception stack trace --- at Microsoft.Exchange.Provisioning.ProvisioningLayer.GetProvisioningHandlersImpl(Task task) at Microsoft.Exchange.Provisioning.ProvisioningLayer.GetProvisioningHandlers(Task task) at Microsoft.Exchange.Configuration.Tasks.Task.<BeginProcessing>b__4() at Microsoft.Exchange.Configuration.Tasks.Task.InvokeNonRetryableFunc(Action func, Boolean termin atePipelineIfFailed)".
As expected a fresh Exchange install contains the sample file only. The following screenshot shows the Exchange Management Shell and the releated folder in the background.
The only solution currently known to me is to disable the cmdlet extension agent until the setup of the new Exchange server has finished.
Disable-CmdletExtensionAgent "Scripting Agent"
Having the cmdlet extension agent disabled the setup finishes without any issues. Don't forget to copy the cmdlet extension Xml file to the newly built server and to enable the cmdlet extension agent again.
Enable-CmdletExtensionAgent "Scripting Agent"
You need assistance with your Exchange Server setup? You have questions about your Exchange Server infrastructure and going hybrid? You are interested in what Exchange Server 2016 has to offer for your environment?
Contact me at thomas@mcsmemail.de Follow at https://twitter.com/stensitzki
The use of Exchange Edge Transport Servers requires the synchronization of user and configuration data from internal Exchange Servers to the Edge Transport Servers. The synchronization utilizes secure LDAP (EdgeSync) to transmit the data securely and is based on an Edge Subscription.
When you create a new Edge Subscription on your internal Exchange Servers by importing the Edge Subscription XML-file, establishing the EdgeSync-connection might fail.
You will find the following error in the application event log of the internal Exchange Server:
Log Name: Application Source: MSExchange EdgeSync Event ID: 1035 Task Category: Synchronization Level: Error Keywords: Classic Description: EdgeSync failed to synchronize because it only supports Cryptographic API certificates. The local Hub Transport server's default certificate with thumbprint XYZ isn't a CAPI certificate. To set a CAPI certificate as the default certificate, use the Enable-ExchangeCertificate cmdlet with the Services parameter using the value of SMTP.
The private key of the current Exchange Transport default certificate of the internal Exchange servers uses a CNG private key. EdgeSync requires a CAPI1 based private key.
This problem occurs primarily when using an Enterprise Certificate Authority using certificate templates with individual template settings.
Get-TransportService | ft Name,InternalTransportCertificateThumbprint
certutil -v -store my > cert.txt
If both attribute are of the value 0, the certificate if a CNG certificate.
The section might look like this:
Unique container name: XYZ Provider = Microsoft Software Key Storage Provider ProviderType = 0 Flags = 20 (32) CRYPT_MACHINE_KEYSET -- 20 (32) KeySpec = 0 -- XCN_AT_NONE
Use OpenSSL to convert the CNG certificate to a CAPI1 certificate.
Using OpenSSL requires the download of the Windows release of OpenSSL. I recommend to not install the software on the Exchange Server but a separate Windows server or your administrative desktop system. Additionally, you need the certificate with its private key as a PFX-file.
Use the following steps to convert the CNG certificate to a CAPI1 certificate.
openssl pkcs12 -in CERT.pfx -out cert.pem -nodes
openssl pkcs12 -export -in cert.pem -out NEWCERT.pfx
The new PFX-file is now a CAPI1 certificate. The new certificate has the same thumbprint. Now you must replace the current certificate used by Exchange Server with the new certificate.
Replacing the certificate requires a downtime of each Exchange Server requiring the certificate replacement. This is due to the requirement to remove the CNG certificate first, following the import of the CAPI1 certificate. Afterward, you need to enable the required Exchange services.
Get-ExchangeCertificate -Server SERVERNAME
# It is mandatory to answer the query for replacing the default certificate with YES Enable-ExchangeCertificate -Thumbprint THUMBPRINT -Services SMTP # Restart the transport service Restart-Service MSExchangeTransport
# It is mandatory to answer the query for replacing the default certificate with YES Enable-ExchangeCertificate -Thumbprint NEWCERTTHUMBPRINT -Services SMTP # Restart the transport service Restart-Service MSExchangeTransport
Now, that you updated the local Exchange Servers there is one more step that needs to be checked on the Edge Transport Servers.
Edge Transport Servers are not domain-joined and therefore do not receive any GPO-based configuration. Each required configuration must be performed locally. To ensure that the default transport certificate of the internal Exchange servers can be used for cryptographic operations we must ensure that the certificate chain of that certificate is present in the certificate store of Edge Transport servers.
Take a look at the certificate chain of the converted CAPI1 certificate and import the Root-CA and Subordinate-CA certificates into the Edge Transport servers local certificate store. You must ensure that the certificates are placed into appropriate stores:
Next, you create a new Edge Subscription on your Edge Transport server and create a new subscription for the Active Directory site on the internal Exchange Server. The internal Exchange Servers are now able to establish an EdgeSync connection and encrypting the data transferred to the Edge Transport servers.
When you receive the TLS certificate as PFX/PKCS12 file, you import the certificate and the private key. The import process itself defines the priavte key Crypto Provider. Using the following command line you ensure that the import process suses the legacy crypto provider.
certutil -csp "Microsoft RSA SChannel Cryptographic Provider" -importpfx my MYCERTpfx
Enjoy Exchange Server and Edge Transport!
Are you located in Germany, Austria, or Switzerland? Join the Exchange User Group DACH to collaborate with other Exchange enthusiasts. Follow us on Twitter @exusg, join on Meetup, or visit our website.
You are not able to list public folders in a co-existence scenario with Exchange Server 2007 and Exchange Server 2010/2013 using the Exchange 2007 EMS or EMC.
When you try to execute Get-PublicFolder you receive the following error:
Get-PublicFolder " There is no existing PublicFolder that matches the following Identity: '\'. Please make sure that you specified the correct PublicFolder Identity and that you have the necessary permissions to view PublicFolder.
This might happen after you have removed the first Exchange 2007 mailbox server, but not the last Exchange 2007 mailbox server.
Exchange Server 2007 uses the Exchange System Attendant to access the public folder store and fails if the System Attendant discovery in Active Directory does not provide a proper configuration.
KB 2621350 describes the discovery process:
There two annoying things about these steps
The magic System Attendant mailbox has been removed from Exchange 2010. But the System Attendent configuration node does still exist in the Active Directory Configuration Partition for compatibility reasons. The configured attributes of the System Attendant entry vary depending on the version of the installed Exchange Server.
In regards to the public folder issue, we need to focus on the following:
To fix the public folder access issue for Exchange Server 2007, set the homeMDB and homeMTA attributes. Set the Exchange System Attendant attributes to appropriate values for your Exchange servers.
Repeat steps 4 to 8 for each Exchange 2013 server in your environment.
Repeat steps 4 to 13 for each Exchange 2010 server in your environment.
Wait for Active Directory replication and retry to access the public folders using Get-PublicFolder in an Exchange Server 2007 Management Shell.
It might be required to restart the Exchange 2007 Information Store and System Attendant service of the Exchange 2007 server in question
Use an administrative PowerShell
Restart-Service MSExchangeIS Restart-Service MSExchangeSA
I haven’t noticed any issues in production environments so far. If you encounter any issues in your environment, feel free to leave a comment.
Do you need assistance with your Exchange Server setup? You have questions about your Exchange Server infrastructure and going hybrid? You are interested in what Exchange Server 2016 has to offer for your environment?
When you've enabled the Exchange scripting agent extension agents, it is required to copy the configuration file to each Exchange server. Paul Cunningham's script helps you to achive this goal pretty easily.
But if you have installed the Exchange 2013 Management Tools on additonal servers, these servers are not fetched using the Get-ExchangeServer cmdlet. But when you install a Cumulative Update the existence of the extension agent config file is checked. And this even on a server having only the Exchange Management Tools installed.
Therefore the following PowerShell code provides an easy and simple way to add additonal server having the Exchange 2013+ Management Tools installed (aka Admin Servers, Monitoring Servers, Job Servers, etc.). The script uses a filter to select Exchange 2013 servers only, as the script has been extended in an environment having still active Exchange 2007 servers.
The following PowerShell snippet displays only the changes, which need to be added to Paul's original script starting row 68.
# Original PowerShell code # $exchangeservers = Get-ExchangeServer # Select all Exchange 2013 servers only, restrict properties to Name and AdminDisplayName $exchangeservers = Get-ExchangeServer | ?{$_.AdminDisplayVersion -like "Version 15.0*"} | Select Name, AdminDisplayVersion # Add additional servers as needed $manualServers = @() # Copy and modify as needed $manualServers += (New-Object PSObject -Property @{Name="EXSRV2010";AdminDisplayVersion="Version 14"}) $manualServers += (New-Object PSObject -Property @{Name="EXSRV2013-01";AdminDisplayVersion="Version 15"}) $manualServers += (New-Object PSObject -Property @{Name="EXSRV2013-02";AdminDisplayVersion="Version 15"}) # Combine arrays $exchangeservers = $exchangeservers + $manualServers # End Modification $report = @() [string]$date = Get-Date -F yyyyMMdd-HHmmss
Enjoy extending the Exchange PowerShell cmdlets.
Questions? Just leave a comment.
The script sends a given number of test emails to a configured SMTP host for test purposes (primarily Exchange queues, transport agents, or anti-virus engines).
Do not forget to adjust script variables to suit your local Exchange infrastructure.
# EXAMPLE 1 # Send 10 normal emails .\Send-TestMail.ps1 -Normal -MessageCount 10 # EXAMPLE 2 # Send an Eicar test email .\Send-TestMail.ps1 -Eicar
This script copies a single receive connector from a source Exchange Server to a single target Exchange server or all other Exchange servers.
The primary purposes of this script are:
Find the most recent full documentation at GitHub.
Copy Exchange 2013/2016 receive connector RC2 from server MBX01 to server MBX2
.\Copy-ReceiveConnector.ps1 -SourceServer MBX01 -ConnectorName RC2 ` -TargetServer MBX2 -DomainController MYDC1.mcsmemail.de
Copy Exchange 2013/2016 receive connector RC2 from server MBX01 to all other Exchange 2013 servers
.\Copy-ReceiveConnector.ps1 -SourceServer MBX01 -ConnectorName RC1 ` -CopyToAllOther -DomainController MYDC1.mcsmemail.de
Copy Exchange 2013/2016 receive connector relay from Exchange 2007 server MBX2007 to Exchange 2013 server MBX01 and reset network bindings
.\Copy-ReceiveConnector.ps1 -SourceServer MBX2007 -ConnectorName "relay" ` -TargetServer MBX01 -MoveToFrontend -ResetBindings ` -DomainController MYDC1.mcsmemail.de
Additional credits go to Jeffery Land, https://jefferyland.wordpress.com