1. Problem
You are integrating with a
system that publishes messages to an MSMQ queue, and you must configure
BizTalk Server to receive messages from MSMQ.
2. Solution
You are building a solution
that processes orders from an online commerce site that outputs order
messages to an MSMQ queue. To receive messages from the queue, you must
create a BizTalk Server receive location that utilizes the MSMQ adapter.
To configure the receive location, follow these steps:
Open the BizTalk Administration Console.
Expand the BizTalk Server group, select an appropriate BizTalk application, and select the Receive Ports folder.
Right-click the Receive Ports folder, and select New→One-way Receive Port to open the Receive Port Properties dialog box.
Give your new receive port a descriptive name, and click OK.
Right-click
the receive port created in the previous step, and select New→Receive
Location. The Receive Location Properties dialog box appears.
Give your receive location a descriptive name, select the XMLReceive pipeline, and select MSMQ as the transport type.
Click the Configure button to the right of the Transport Type field. This launches the MSMQ Transport Properties dialog box.
Set the Queue property to the queue name that the online commerce site outputs messages to, as shown in Figure 1. In this scenario, we are using a queue named CommerceOrder.
Leave all the other properties with their default values, and click OK.
Click OK in the Receive Location Properties dialog box to save the receive location.
NOTE
You can also create receive ports and receive locations in the BizTalk Editor view in Visual Studio.
Select the Receive Locations folder in the BizTalk Administration Console, right-click the receive location created earlier, and select Enable.
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 Receive Options
Although this example
illustrates the simplest scenario for receiving MSMQ messages from a
specified queue, you can make a number of configurations against the
MSMQ adapter:
Queue:
Specifies the queue from which to receive messages. Each queue must be
polled by only one receive location per BizTalk environment. See the
following section for further information about how to format queue
names.
Ordered Processing: Specifies whether the message order is persisted in the MessageBox. If this property is set to True,
only one message is received in each batch (one message retrieved each
time the receive location polls the queue). This property enables a
solution to implement ordered message delivery, although you must also
ensure that any subsequent processing (including the delivery of the
message to a destination system) is handled serially if order is to be
maintained. A True value for this property overrides the Batch property, essentially setting its value to 1.
On Failure: Specifies the action the adapter should take on the receive location if an error occurs. These are the available values:
Stop: The receive location will be stopped.
Suspend (nonresumable): The receive location will remain enabled, with error messages being suspended in a nonresumable state.
Suspend (resumable): The receive location will remain enabled, with error messages being suspended in a resumable state.
Batch Size:
Specifies the number of MSMQ messages to be handled in a single batch.
The default value of 0 indicates an unlimited number of messages in a
batch. The MSMQ adapter retrieves messages from a queue and submits them
to the MessageBox in batches of one to many 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.
Transactional: Specifies whether the receive location will retrieve messages transactionally. This property must be set to True if the source queue is transactional and False if the source queue is not transactional.
If the Transactional property is set to True,
the MSMQ adapter transactionally retrieves the appropriate number of
messages into a batch and attempts to submit the batch to the MessageBox
within the transaction. If any errors are encountered when submitting
the messages, the MSMQ adapter attempts to suspend the messages that
have errors. If any errors are encountered when suspending the error
messages, the MSMQ adapter rolls back the receive transaction (which
leaves the messages in their original location—in the MSMQ queue).
Messages within a batch are handled individually; those messages that do
not encounter errors are submitted to the MessageBox, 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 in a
batch and attempts to submit the batch to the MessageBox. If any errors
are encountered when submitting the batch, the MSMQ adapter attempts to
suspend the messages. If any errors are encountered when suspending the
batch, the messages are lost.
NOTE
The MSMQ
adapter does not support transactionally receiving messages from a
remote queue. If the queue is remote, message batches will be retrieved
nontransactionally, regardless of the configuration of this property.
As a batch is submitted to
the MessageBox, errors can occur in messages. They pass through the
receive pipeline configured on the receive location, pass through the
map configured on the receive port, or are written to the MessageBox
database.
You should consider
the performance impact when using the MSMQ adapter. It is important to
understand the volume and size characteristics of the messages you
expect to receive via MSMQ, because they can significantly impact your
BizTalk Server resources. You should pay particular attention to the
following:
Threading:
BizTalk Server attempts to allocate threads to each MSMQ receive
location as it polls its queue. Depending on how many messages are in
the source queue, multiple threads may be allocated to each receive
location. By default, the number of active threads allocated to the MSMQ
adapter cannot exceed 25. If you have more than 25 messages being
retrieved at any one time, it is possible to have latency.
Memory allocation:
As message batches are retrieved by MSMQ receive locations, they are
stored in memory until they are written to the MessageBox. The larger
these batches are, the more memory is allocated. To throttle the amount
of memory used by the MessageBox adapter, you can use the BatchSerial Processing properties. You can limit the number of messages in any given batch by setting the Batch property to a low value. You can also set the Serial Processing property to True,
which limits the MSMQ receive location to retrieving a single message
in each batch. Memory allocation is particularly important if you have
implemented the large message extension for message queuing, which
allows messages larger than 4MB in size to be handled by the MSMQ
adapter. See the SDK example devoted to this topic for further
information. and
It is important to
understand the relationship of these configurations and the impact they
have on system resources. The ideal configuration of threading, serial
processing, and batch processing is specific to each BizTalk
environment. Optimization should be part of the performance-testing
phase for all solutions you deploy to your BizTalk Server environment.
5. MSMQ Queue Name Formats
To successfully read messages from an MSMQ queue, you must appropriately format the name of the queue via the 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
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.
