Partager via

WCF Exchange Server Mail Transport

  • Article

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

The Windows Communication Foundation (WCF) mail transport for Microsoft Exchange Server provides a queued service by using WCF endpoints based on e-mail addresses. This solution enables both .NET Compact Framework and .NET Framework applications to host and consume Web Services from any computer as long as the e-mail server is reachable.

Note

WCF is supported in the .NET Compact Framework version 3.5 and later.

This feature can be used to enable a variety of application scenarios, including the following:

  • Applications that want to send secure communications from the field back to a central server and receive secure communications from the server.

  • Applications that push data from an enterprise server to devices in the field.

  • Peer-to-peer applications where two or more devices can talk to one another directly.

    In these scenarios, multiple parties communicate state information to one another by using the e-mail server as the mediator. For example, in a typical gaming scenario, one player sends an invitation to play a game to the other players by providing the application with e-mail addresses or a group alias.

  • Applications that locate lost devices.

  • Applications that update configuration information for other applications by pushing data to the device.

The WCF Exchange Server mail transport addresses two basic limitations of devices in the field: addressibility and the ability to queue data when devices are offline. The channel name and the e-mail address constitute the WCF endpoint address. This is similar to an IP address and port number in a socket-based application. Addressibility of the device is handled by the e-mail address, and addressibility of the application instance is handled through the input channel name. The WS-Addressing protocol is used to implement this custom addressing scheme.

Queuing is supported through the local data store in Windows Mobile powered devices. For general information about WCF queues, see Queues Overview.

Applications that are built on the WCF Exchange Server mail transport benefit from fundamental WCF features. WCF provides a unified programming model for various underlying protocols and transports, and separates the application logic from the WCF endpoint. This programming model provides several benefits, including support for different networks such as General Packet Radio Service (GPRS), Wi-Fi, and any other network that can access the e-mail server. Developing applications by using the WCF Exchange Server mail transport is very similar to developing applications by using WCF channels such as the HTTP channel.

Requirements

The e-mail server for applications based on the WCF mail transport is Exchange Server 2007. Exchange Server 2007 Service Pack 1 provides an administrative task that enables you to redirect service traffic into a separate folder for WCF e-mail.

Note

Service traffic uses the Inbox if it is not redirected.

The mail transport is supported on both devices and desktop computers.

The CE Messaging API (CEMAPI) is required on the device to support queuing. CEMAPI is present on Windows Mobile powered devices, but it is not present on Windows Embedded CE powered devices.

Windows Mobile version 5.0 and later versions support the WCF Exchange Server mail transport. In Windows Mobile versions earlier than version 5.0 (build 14847.2.0), Systems Management Server (SMS) is used instead of Direct Push to force synchronization with the Exchange e-mail server.

Note

The mail transport is also supported on Windows Mobile 2003 for Pocket PC and Windows Mobile 2003 Second Edition for Pocket PC. However, for devices that are running versions of Windows Mobile earlier than 5.0, the ActiveSync synchronization period for incoming messages does not always occur when scheduled. For these devices, we recommend that you do not specify a time-out or that you specify a large time-out when you call the Receive method. Windows Mobile 2003 for Smartphone is not supported.

  • On the desktop computer, communication with the e-mail server occurs directly through Exchange Server 2007 Web Services. The desktop does not support queuing. As a result, the desktop computer must always be online.

  • Applications on the desktop use the desktop implementation of WCF.

Architecture

The messaging layer is based on the standard desktop WCF architecture. The service runtime layer is not present. The following illustration shows the channel stack and the supported protocols and binding elements.

Messaging layer for the WCF Exchange Server mail transport

Messaging layer for Exchange Server mail transport

Support for the WS-Security specification version 1.0 includes SOAP message security using X.509 certificates.

The Message class is built on the WS-Addressing standard. All messages are asynchronous; they go from one device through the e-mail server to another device, without a return trip.

Serialization and deserialization of messages are handled within the .NET Compact Framework or .NET Framework runtime. On the device side, a custom serializer must be used in the application. This is not required for the desktop because the full .NET Framework supports the DataContractSerializer class. However, the same serializer that is used for devices should be used on the desktop if the application supports communication between devices and the desktop.

Design

For the WCF Exchange Server mail transport, a WCF endpoint is represented by the combination of a WCF binding and the endpoint address. The binding specifies the parameters that are used for communication. It represents a collection of binding elements that includes a transport binding element, an encoding binding element, and a security binding element. For applications that use the mail transport, these elements are defined as follows:

Instead of instantiating a set of binding elements within a CustomBinding object, applications can create a predefined collection of binding elements by using a class that is derived from the MailBindingBase object. In addition to the e-mail transport binding element, this class includes a text encoding binding element and optional message security.

Messages are included in the body of the e-mail message or sent as an attachment. The Subject line of the message contains the channel name. The message is identified with a custom WCF e-mail channel stamp that is provided by the message class used by Exchange Server.

Sending Messages

When an application sends a message, it calls the Send method on the current output channel, which must be open. The output channel serializes the message to a string and creates the message in the Drafts folder. It sets the appropriate values in the e-mail fields. When the message has been created, it is moved into the Outbox. This occurs through CEMAPI on the device or through Exchange Web Services on the desktop. On the device, messages in the Outbox are synchronized with other outgoing messages, as defined by ActiveSync.

Receiving Messages

When an application that is based on the WCF Exchange Server mail transport receives a message, the following process occurs:

  1. The application opens the input channel.

  2. The input channel calls the Receive method to begin to listen for messages.

  3. When the Exchange e-mail server receives a message that has the WCF e-mail channel stamp, it automatically routes the message into the Service E-mail folder, which is at the same level as the Inbox.

    Note

    If the Exchange e-mail server has not been configured to route WCF Exchange Server service mail into the Service E-mail folder, it uses the Inbox instead.

  4. The input channel that is listening for the new mail event checks each message that arrives in the Service E-mail or Inbox folder.

    The input channel blocks the code while it is listening for messages.

  5. If the input channel matches the specific channel name in the message, it retrieves the message and unblocks the code.

You can call the Receive method for multiple input channels that are built on the same transport. Blocking occurs only when Receive is called for the second time on the same input channel on the same thread.

Note

Only one input channel can be associated with each channel listener. A second call to the AcceptChannel method on a channel listener will not return until the first input channel closes.

For greater flexibility, the e-mail transport can be configured to handle messages of various sizes in different ways. For example, messages can be sent as attachments or in the message body based on their size. Larger messages might not be downloaded fully during the initial synchronization. On the device, messages in the Service E-mail or Inbox folder are synchronized with other incoming messages, as defined by Microsoft ActiveSync.

Note

For the device, the ActiveSync e-mail synchronization settings control the maximum size of each message that is initially downloaded to the device. If a message exceeds this size, only a part of the message body is downloaded initially. If a message is partially downloaded and a channel listener is waiting for the message, the transport marks the message to indicate that it has to be downloaded in its entirety. The full message is downloaded at the next synchronization session.

When receiving a message, you can obtain the e-mail address of the sender by using the FromEmailAddress custom property in the Message class. The following example demonstrates how to use this property.

System.ServiceModel.Channels.Message m;
String senderAddress;
m = input.Receive();
senderAddress = m.Properties.ContainsKey("FromEmailAddress")

Deleting Messages

The transport deletes a message as soon as the message is requested and received by the application. The process for deleting incoming messages after they are processed varies by platform.

The process for deleting incoming messages on Windows Mobile powered devices consists of the following steps:

  1. The input channel retrieves a message after it calls the Receive method.

  2. The mail transport issues a call to delete the message from the message store on the Windows Mobile powered device.

  3. The message is deleted from the server at the next e-mail synchronization.

The process for deleting incoming messages on the desktop consists of the following steps:

  1. The input channel retrieves a message after it calls the Receive method.

  2. The mail transport places the message into the deleted messages cache, which is an internal cache owned by the mail transport.

  3. At the next query interval, the mail transport checks the deleted messages cache.

    The query interval is determined by the ServerQueryInterval property.

  4. If the deleted messages cache contains any messages, the mail transport issues a query that includes a command to the server to delete the messages in the cache.

  5. During the query, the mail transport checks the server events and downloads any associated messages.

  6. The mail transport posts any downloaded messages to its processing cache for processing by the application.

For the desktop, the mail transport also issues a command to the server to delete messages in the deleted messages cache under the following circumstances:

  • When you call the Close method on the last remaining open input channel that is associated with a mail transport.

  • When you call the Dispose method on the mail transport.

These operations are synchronous; Close and Dispose block the code until the messages are deleted from the server. The time required to delete the messages can vary and depends on the number of messages that have to be deleted. If a failure occurs during this process, the transport makes several more attempts to delete the messages.

On Windows Mobile powered devices, the message store handles this function.

Messages are also deleted when they are invalid or malformed. A message that has a corrupted SOAP envelope is considered invalid and will be deleted permanently. If the subject line in the message contains bad information following the WCF e-mail channel stamp, such as an unsupported character in the channel name, it is considered to be a malformed message. Malformed messages are moved to the Deleted folder.

Default Settings

The MailBindingBase class and the classes derived from it represent a collection of predefined binding elements. These classes are designed to make it easier to create input and output channels. In some scenarios, you might have to change default values in these predefined collections. If the property you have to change does not exist in MailBindingBase or in the derived class you are using, you can create the binding element separately in a CustomBinding object. Alternatively, you can call the CreateBindingElements method to return all the binding elements in MailBindingBase.

For example, in the ExchangeWebServiceMailBinding class, the default maximum message size for received messages is 65,536 bytes. You can increase the maximum size to 100,000 bytes by using the following code to set the MaxReceivedMessageSize property.

binding = new ExchangeWebServiceMailBinding(Server, Credential, MailSecurityMode.Message);
bindingElems = binding.CreateBindingElements();
bindingElems.Find<ExchangeWebServiceMailTransportBindingElement>().MaxReceivedMessageSize = 100000;
binding = new CustomBinding(bindingElems);

Security

Applications that are based on the WCF Exchange Server mail transport support SOAP message security based on the WS-Security protocol, which resembles the desktop security features supported for the HttpTransportBindingElement class. This security feature relies on X.509 certificates.

If you use the predefined set of binding elements in a subclass of the MailBindingBase object, message security is available but disabled by default. To enable security, use the Mode property. You can change the default encryption algorithm by using the AlgorithmSuite property. When security is enabled, Basic256Rsa15 is the default value.

The security binding elements that are supported on applications that use the WCF Exchange Server mail transport are SecurityBindingElement and AsymmetricSecurityBindingElement.

Note

Using message security increases the size of each message. If you are using the ExchangeWebServiceMailBinding class, and your messages exceed 45,000 bytes, you might have to increase the value of the MaxReceivedMessageSize property. The code example in the preceding section demonstrates how to increase the maximum message size.

Deployment

For device deployment, the WCF Exchange Server mail transport DLLs are delivered in the .NET Compact Framework CAB files for Windows Mobile powered devices. The managed assemblies are installed in the global assembly cache.

The mail transport DLLs for the device are as follows:

  • Microsoft.ServiceModel.Channels.Mail.dll

  • Microsoft.ServiceModel.Channels.Mail.WindowsMobile.dll

  • Netcfmail3_5.dll, which is a CEMAPI native wrapper

The .NET Compact Framework WCF DLLs must also be present on the device.

Desktop deployment is handled through the .NET Compact Framework .msi setup file. The WCF Exchange Server mail transport feature is installed by default. The mail transport assemblies are installed in the desktop's global assembly cache.

The WCF Exchange Server mail transport DLLs for the desktop are as follows:

  • Microsoft.ServiceModel.Channels.Mail.dll

  • Microsoft.ServiceModel.Channels.Mail.ExchangeWebService.dll

The standard desktop WCF DLLs must also be present on the desktop.

See Also

Tasks

Walkthrough: Using the WCF Exchange Server Mail Transport

Other Resources

Windows Communication Foundation (WCF) Development and the .NET Compact Framework