QueuedMessageEventSource.ExpandRecipients method

When overridden in a derived class, the ExpandRecipients method splits a MailItem into two branches, removing recipients from and adding recipients to one of the copies of the MailItem.

Namespace:  Microsoft.Exchange.Data.Transport.Routing
Assembly:  Microsoft.Exchange.Data.Transport (in Microsoft.Exchange.Data.Transport.dll)

Syntax

'Declaration
Public MustOverride Sub ExpandRecipients ( _
    recipientExpansionInfo As IList(Of RecipientExpansionInfo) _
)
'Usage
Dim instance As QueuedMessageEventSource
Dim recipientExpansionInfo As IList(Of RecipientExpansionInfo)

instance.ExpandRecipients(recipientExpansionInfo)

public abstract void ExpandRecipients(
    IList<RecipientExpansionInfo> recipientExpansionInfo
)

Parameters

• recipientExpansionInfo
  Type: System.Collections.Generic.IList<RecipientExpansionInfo>

  An array that contains one or more RecipientExpansionInfo structures that contain the recipient or recipients to remove and the recipient or recipients to add.

Remarks

The ExpandRecipients method forks the message that is specified by the mailItem parameter into two copies. The first copy of the message, the current thread, contains the EnvelopeRecipient that is specified in the Addresses property of each structure that is specified in the recipientExpansionInfo parameter. The ExpandRecipients method creates the second copy of the message and includes the recipients that remain in the EnvelopeRecipientCollection after removing the EnvelopeRecipient that is specified in the RemoveRecipient property of each structure that is specified in the recipientExpansionInfo parameter.

Examples

The following example shows how to use the ExpandRecipients method in the OnSubmittedMessage event to replace all recipients with a single recipient.

        private void SubmittedMessageHandler(SubmittedMessageEventSource source, QueuedMessageEventArgs e)
        {
            SmtpResponse expandSmtpResponse = new SmtpResponse("250", "2.1.5", "Replaced all recipients with a single recipient");

            // Replace all but the last recipient with nothing and
            // replace the last recipient with a different recipient.
            List<RecipientExpansionInfo> expansionInfoList = new List<RecipientExpansionInfo>();
            for (int i = 0; i < e.MailItem.Recipients.Count - 1; i++)
            {
                EnvelopeRecipient envelopeRecipient = e.MailItem.Recipients[i];
                expansionInfoList.Add(new RecipientExpansionInfo(
                    envelopeRecipient,
                    new RoutingAddress[] { },
                    expandSmtpResponse));
            }

            RoutingAddress expandRecipient = new RoutingAddress("user1@example.com");
            expansionInfoList.Add(new RecipientExpansionInfo(
                e.MailItem.Recipients[e.MailItem.Recipients.Count - 1],
                new RoutingAddress[] { expandRecipient },
                expandSmtpResponse));

            source.ExpandRecipients(expansionInfoList);
        }

The following example shows how to use the ExpandRecipients method in the OnResolvedMessage event to replace all recipients with a single recipient.

private void ResolvedMessageHandler(ResolvedMessageEventSource source, QueuedMessageEventArgs e)
        {
            // A message that is expanded and deferred will go back to the beginning of the pipeline,
            // which means that it will be resolved again and this handler will be invoked again.
            // To prevent an infinite loop, stamp a property on the message to indicate
            // that the message has already been expanded so that it can be skipped.

            string alreadyExpanded = "SampleRoutingAgent.AlreadyExpanded";
            if (!e.MailItem.Properties.ContainsKey(alreadyExpanded))
            {
                e.MailItem.Properties[alreadyExpanded] = true;

                SmtpResponse expandSmtpResponse = new SmtpResponse("250", "2.1.5", "Replaced all recipients with a single recipient");

            // Replace all but the last recipient with nothing and
            // replace the last recipient with a different recipient.
                List<RecipientExpansionInfo> expansionInfoList = new List<RecipientExpansionInfo>();
                for (int i = 0; i < e.MailItem.Recipients.Count - 1; i++)
                {
                    EnvelopeRecipient envelopeRecipient = e.MailItem.Recipients[i];
                    expansionInfoList.Add(new RecipientExpansionInfo(
                        envelopeRecipient,
                        new RoutingAddress[] { },
                        expandSmtpResponse));
                }

                RoutingAddress expandRecipient = new RoutingAddress("user1@example.com");
                expansionInfoList.Add(new RecipientExpansionInfo(
                    e.MailItem.Recipients[e.MailItem.Recipients.Count - 1],
                    new RoutingAddress[] { expandRecipient },
                    expandSmtpResponse));

                source.ExpandRecipients(expansionInfoList);

                // Use the Defer method to make sure that the new recipient
                // is resolved and the message is correctly routed.
                source.Defer(TimeSpan.Zero);
            }
        }

The following example shows how to use the ExpandRecipients method to replace a single recipient with a set of recipients. This shows functionality that is similar to that provided by using distribution lists.

private void SubmittedMessageHandler(SubmittedMessageEventSource source, QueuedMessageEventArgs e)
        {
            // If recipientToExpand is a recipient of this message,
            // replace it with a new list of recipients.
            RoutingAddress recipientToExpand = new RoutingAddress("users@example.com");
            EnvelopeRecipient envelopeRecipient = this.GetEnvelopeRecipient(e.MailItem, recipientToExpand);

            if (envelopeRecipient != null)
            {
                RoutingAddress[] expandedRecipients = new RoutingAddress[]
                {
                    new RoutingAddress("user1@example.com"),
                    new RoutingAddress("user2@example.com"),
                };

                SmtpResponse expandSmtpResponse = new SmtpResponse("250", "2.1.5", "Expanded a recipient");

                List<RecipientExpansionInfo> expansionInfoList = new List<RecipientExpansionInfo>();
                expansionInfoList.Add(new RecipientExpansionInfo(
                    envelopeRecipient,
                    expandedRecipients,
                    expandSmtpResponse));
                source.ExpandRecipients(expansionInfoList);
            }
        }
        private EnvelopeRecipient GetEnvelopeRecipient(MailItem mailItem, RoutingAddress routingAddress)
        {
            foreach (EnvelopeRecipient envelopeRecipient in mailItem.Recipients)
            {
                if (envelopeRecipient.Address == routingAddress)
                {
                    return envelopeRecipient;
                }
            }

            return null;
        }

See also

Reference

QueuedMessageEventSource class

QueuedMessageEventSource members

Microsoft.Exchange.Data.Transport.Routing namespace