BizTalk Server 2013 R2: WCF-MSMQ Binding (Adapter)
https://msdnshared.blob.core.windows.net/media/2016/05/0640_NinjaAwardTinyGold.pngGold Award Winner
Introduction
This short article will demonstrate how to receive and send a message to Microsoft Message Queue with BizTalk Server leveraging the out of the box WCF-MSMQ binding. The goal is to provide the reader a view of how to integrate with MSMQ using BizTalk Server.
Scenario
The scenarios is as follows:
- A message from a client application is send to a non-transactional private queue when the user clicks send message.
- BizTalk Application receive port configured with a receive location using the WCF-MSMQ binding picks up the message.
- Message is transformed with a specified inbound map and the transformed message is published in the BizTalk MessageBox.
- A send port subscribing to message type of the transformed message will pick the message and send it to another non-transactional private queue.
- A client application receives the message after user clicks get message.
http://i208.photobucket.com/albums/bb152/Steef-Jan/BizTalk%20and%20MSMQ/Scenario%201_zps2rx32efg.png
Picture 1. Diagram of the scenario.
Walkthrough
In the following steps will provide a demonstration how to configure receive and send port with the WCF-MSMQ binding (adapter). The first step after deploying a BizTalk solution is to configure send, receive ports and/or the orchestration(s), and/or any other type of configuration. After creating a receive port you need to add a receive location.
- Name the receive location.
- Select in type the appropriate binding i.e. adapter. In our scenario the WCF-MSMQ.
http://i208.photobucket.com/albums/bb152/Steef-Jan/Receive%20Location%201_zpsslhjbplx.png
Picture 2. Configure the receive location with WCF-MSMQ Binding (Adapter).
- Next step is to configure the binding. Click Configure …
- A dialog will appear name MSMQ Transport Properties
- In the Properties Tab specify the Queue name. The format is MachineName\Private$]\QueueName. Part after the Machine name is where you determine if it is a private or public queue. In case you need to access a public queue than the queue would be specified like: ServerX/InternalOrders
http://i208.photobucket.com/albums/bb152/Steef-Jan/Receive%20Location%202_zps95gzjzsn.png
Picture 3. Configure MSMQ Properties.
- Leave other properties default. Note that logon info can be required to access a public queue on a different server. For details of the MSMQ Transport Properties for a receive location see MSDN How to Configure an MSMQ Receive Location.
- Click Ok.
- Once the dialog is gone your receive location will look like below.
http://i208.photobucket.com/albums/bb152/Steef-Jan/Receive%20Location%203_zpswo038l8w.png
Picture 4. Specify the receive pipeline.
- The format of URI is: FORMATNAME:DIRECT=OS:DEVSTEEF\PRIVATE$\INTERNALORDERS. For queue names with WCF-MSMQ see MSDN Message Queuing Queues.
- Click Ok.
- As receive pipeline choose XMLReceive.
- The receive location is now created in the receive port.
- The final set here is that the inbound map is specified to the map responsible of mapping the External Order to the Internal Order format.
The Send Port configuration with MSMQ binding (adapter) is as follows.
- Create a new send port and provide it with an appropriate name.
- Next select in type the appropriate binding i.e. adapter. In our scenario again the WCF-MSMQ.
- Click Configure… and a dialog will appear
- In the Properties Tab specify the Queue name. The format is MachineName\Private$]\QueueName.
Picture 5. Specify the MSMQ Transport Properties Send Port.
- Leave other properties default. For other properties see MSDN How to Configure an MSMQ Send Port.
- Click Ok.
- Once the dialog is gone your Send port will look like below.
Picture 6. Send Port with WCF-MSMQ Binding (Adapter).
- As Send Pipeline choose XMLTransmit.
- Click .. and dialog will appear.
- Set AddXMLDeclaration to false if you do not need to send the message with an XML Declaration
- Next set the Preserve BOM property to false (see Test the solution to see behavior with preserving the BOM).
Picture 7. XMLTransmit Pipeline Properties.
- Click Ok.
- The final step in this send port is that the filter setting of the port is set to the message type of the Internal Order.
- Now both receive and send ports are configured.
Test the Solution
A windows form client application will load an XML message. By loading an external order message into the application it can be sent to MSMQ: private$\ExternalOrders
Picture 8. MSMQ Client loading External Order Message to be sent.
Once SendMessage is clicked the message will be send to the queue ExternalOrders.
Picture 9. MSMQ Client Sending Message to the Queue.
In BizTalk the message is picked up and send port subscribing on the message will pick it up and send it to queue InternalOrders.
http://i208.photobucket.com/albums/bb152/Steef-Jan/BizTalk%20and%20MSMQ/Queue%201_zpspnutjazi.png
Picture 10. Internal Order Queue containing an Internal Order message.
Once the GetMessage is clicked the message will be read from the queue InternalOrders.
Picture 11. MSMQ Client gets the message from the queue.
In case you preserve the Byte Order Mark (BOM) from a message send to the queue you fill face the following challenge. The message in queue will look like below.
http://i208.photobucket.com/albums/bb152/Steef-Jan/BizTalk%20and%20MSMQ/Queue%202_zpsecqbesc9.png
Picture 12. BOM visible in message properties (Body).
If you pick the message with a service and/or client that has the following implementation than you will not notice any difference as the BOM will be ignored.
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.Load(msgInternalOrder.BodyStream);
It is possible that the BOM could interfere with how you read the message.
In case you use the XMLFormatter to the instance of the Message than you might face an issue. The implementation to read the msessage from the queue could look like.
//Read the message from the queue
System.Messaging.Message msgInternalOrder = internalOrderQueue.Receive();
msgInternalOrder.Formatter = new XmlMessageFormatter(new String[] { "System.String,mscorlib" });
String message = (string) msgInternalOrder.Body;
And an error will occur.
Picture 13. MSMQ Client providing an error message.
Note: This error will occur regardless of the BOM!
Source Code
The code belonging to this article can be found on MSDN Code Gallery: BizTalk Server 2013 R2 WCF-MSMQ Binding (Adapter)
See Also
Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.