다음을 통해 공유

  • 아티클

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) _
)

public abstract void ExpandRecipients (
    IList<RecipientExpansionInfo> recipientExpansionInfo
)

public:
virtual void ExpandRecipients (
    IList<RecipientExpansionInfo>^ recipientExpansionInfo
) abstract

public abstract void ExpandRecipients (
    IList<RecipientExpansionInfo> recipientExpansionInfo
)

public abstract function ExpandRecipients (
    recipientExpansionInfo : IList<RecipientExpansionInfo>
)

Parameters

  • 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.

Important

If you use the ExpandRecipients method in any event other than the OnSubmittedMessage event, you must call the Defer method on the MailItem so that the new recipient can be resolved and routed correctly.

Example

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;
        }

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2003,

Target Platforms

Windows Server 2003