BizTalk 2010 Recipes : Adapters – Configuring MSMQ Sends

March 15, 2021

1. Problem

You are integrating with a system that subscribes to messages from a Microsoft Message Queue (MSMQ) queue, and you must configure BizTalk Server to send messages to MSMQ.

2. Solution

You are building a solution that processes orders from an online commerce site and must deliver those messages to an ERP system via an MSMQ queue. To send messages to the destination queue, you must create a BizTalk Server send port that utilizes the MSMQ adapter. To configure the send port, follow these steps:

  1. Open the BizTalk Administration Console.

  2. Expand the BizTalk Server group, select an appropriate BizTalk application, and select the Send Ports folder.

  3. Right-click the Send Ports folder, and select New→Static One-way Send Port to open the Send Port Properties dialog box.

  4. Give your send port a descriptive name, select the XMLTransmit pipeline, ensure any correct subscriptions are implemented (on the Filters tab), and select MSMQ as the transport type.

  5. Click the Configure button to the right of the Transport Type field. This launches the MSMQ Transport Properties dialog box.

  6. Set the Destination Queue property to the queue name that the ERP system accepts messages from, as shown in Figure 1. In this scenario, we are using a queue named ERPCommerceOrder.

    Figure 1. Configuring an MSMQ send port

  7. Leave all other properties with their default values, and click OK.

  8. Click OK in the Send Port Properties dialog box to save the send port.

    NOTE

    You can also create send ports in the BizTalk Editor view in Visual Studio.

  9. Right-click the send port created in the previous step, and select Start.

 

3. How It Works

The BizTalk Server MSMQ adapter allows easy access to messages in MSMQ queues (MSMQ versions 2.0 and 3.0). The adapter relies on the local MSMQ service, which must be installed on the same computer hosting the adapter.

4. MSMQ Send Options

Although this example illustrates the simplest scenario for sending MSMQ messages to a specified queue, you can make a number of configurations against the MSMQ adapter:

  • Destination Queue: Specifies the queue to which to send messages. See the following section for further information about how to format queue names.

  • Ordered Delivery: Specifies whether the message order is persisted when delivering messages to the destination queue. This property enables a solution to implement ordered message delivery, although you must also ensure that all the previous processing (including the receipt of the message from the source queue) is handled serially if the order is to be maintained.

    You can additionally specify whether the send port should be stopped if errors are encountered when delivering a message to the destination queue. This setting helps enforce a strict ordered delivery requirement, although it has the side effect of completely disabling an interface if a single error occurs. This property is available only via the BizTalk Administration Console, under the Transport Advanced Options grouping of an MSMQ Send Port Properties dialog box. See Figure 2

    Figure 2. The Ordered delivery setting for MSMQ ports

    NOTE

    You can make this setting only via the BizTalk Administration Console, under the Transport Advanced Options grouping of an MSMQ Send Port Properties dialog box.

  • Encryption Algorithm: Specifies the algorithm used to encrypt messages as they are written to the destination queue. The available values are RC2, RC4, and None. This property results in the Message.UseEncryption and Message.EncryptionAlgorithm properties being set.

  • Body Type: Specifies the body type of MSMQ messages written to the destination queue.

  • Maximum Message Size (in kilobytes): Specifies the maximum size of the message batch to be delivered to the destination queue. The MSMQ adapter will fill the batch with messages from the MessageBox until this setting is reached.

  • Message Priority: Specifies the priority for delivering messages. This setting is relative to the other send ports within your BizTalk environment. To nullify the functionality of this property, set the priority on all the send ports in your environment to the same value.

  • Recoverable: Specifies whether messages will be recoverable if errors are encountered during the delivery to the destination queue. When this value is set to True, messages are persisted to disk in between being pulled from the MessageBox and delivered to the destination queue. If errors occur during delivery, messages can be recovered from the disk.

  • Support Segmentation: Specifies whether the adapter allows large messages (larger than 4MB) to be segmented. This property should be set to True if you have implemented the large message extension—if the adapter attempts to deliver a message larger than 4MB and this property is set to False, an error is thrown and the message is not delivered.

  • Timeout: Specifies the timeout value for which messages must be delivered (combined with the Timeout Unit property). This value applies only when the Transaction property is set to True. The MSMQ adapter treats messages not delivered within the specified timeout period as error scenarios.

  • Timeout Unit: Specifies the timeout unit for which messages must be delivered (combined with the Timeout property). The available values for this property are Days, Hours, Minutes, and Seconds.

  • Use Journal Queue: Specifies whether messages will be copied to the journal queue.

    NOTE

    The journal queue is a system queue that is automatically created when MSMQ is installed and is meant to contain copies of messages that are sent or received.

  • Use Dead Letter Queue: Specifies whether error messages will be sent to the dead letter queue.

    NOTE

    The dead letter queue is a system queue that is automatically created when MSMQ is installed and is meant to contain undelivered messages.

  • User Name: Specifies the user for accessing a remote queue. This property applies only when accessing remote queues. The MSMQ adapter’s host account is used to access all local queues.

  • Password: Specifies the password for accessing a remote queue. This property applies only when accessing remote queues.

  • Acknowledgement Type: Specifies the type of acknowledgment to send upon the successful delivery of a message batch to the destination queue. The available acknowledgment types are defined in the System.Messaging.AcknowledgeTypes enumeration. You can select multiple acknowledgment types for this property.

  • Administration Queue: Specifies the administration queue where acknowledgment messages are sent upon the successful delivery of messages to the destination queue.

  • Use Authentication: Specifies that a certificate thumbprint will be used when delivering messages to the destination queue.

  • Certificate Thumbprint: Specifies the certificate thumbprint used to attach to the message batch. You can use this certificate thumbprint to authenticate your BizTalk environment as the sender of the messages, helping increase the overall security of your integration solution. The certificate is stored in the System.Messaging.Message.SenderCertificate property.

    NOTE

    You can find certificate thumbprints by viewing a certificate’s details in the Certificate MMC snap-in.

  • Transactional: Specifies whether the send port will deliver messages transactionally. This property must be set to True if the destination queue is transactional and False if the destination queue is not transactional.

    If the Transactional property is set to True, the MSMQ adapter transactionally retrieves the appropriate amount of messages (as defined by the Maximum Message Size property) into a batch from the MessageBox and attempts to deliver the batch to the queue within the transaction. If any errors are encountered when delivering the batch (including a timeout, as defined by the Timeout and Timeout Unit properties), the MSMQ adapter attempts to redeliver the messages. If any errors are encountered when redelivering the batch, MSMQ suspends the messages, leaving them in a recoverable state in the MessageBox. Setting this property to True automatically implements the behavior defined by the Recoverable property. Messages within a batch are handled individually—those messages that do not encounter errors are delivered to the destination queue, even if other messages in the batch have errors.

    If the Transactional property is set to False, the MSMQ adapter retrieves the appropriate number of messages (as defined by the Maximum Message SizeTimeout and Timeout Unit properties), the MSMQ adapter attempts to suspend the messages. If any errors are encountered when suspending the batch, the messages are lost. property) into a batch from the MessageBox and attempts to deliver the batch to the queue. If any errors are encountered when delivering the batch (including a timeout, as defined by the

    NOTE

    As a batch is delivered to the destination queue, errors can occur as messages. They pass through the send pipeline configured on the send port, pass through the map configured on the receive port, or are written to the destination queue.

5. MSMQ Queue Name Formats

To successfully send documents to an MSMQ queue, you must appropriately format the name of the queue via the Destination Queue property. The appropriate name depends on the type and location of the queue. The following list defines the way the Queue property should be entered for the commonly implemented queues:

  • Public queue: ComputerName\QueueName

  • Private queue: ComputerName\Private$\QueueName

  • Direct access to a queue via TCP: DIRECT=TCP:IPAddressOfComputer\QueueName

  • Direct access to a queue via HTTP: DIRECT=http://ComputerName/MSMQVirtualDirectory/QueueName, where MSMQVirtualDirectory is the Internet Information Services (IIS) virtual directory name of the MSMQ service

  • Direct access to a queue via HTTPS: DIRECT=https://ComputerName/MSMQVirtualDirectory/QueueName, where MSMQVirtualDirectory is the IIS virtual directory name of the MSMQ service

  • Journal queue: ComputerName\QueueName\Journal$

  • Dead letter queue: ComputerName\Deadletter$

  • Transaction dead letter queue: ComputerName\XactDeadletter$

By default, the MSMQ adapter prepends FORMATNAME:DIRECT=OS: to the Queue property, assuming the queue is referenced directly via the host computer’s name.