The GVCLC Adapter-My First WCFLOB Adapter

See  “Connecting BizTalk 2010 to a GVC-LC Vending Machine” to see how this adapter is used. I have recorded all the steps here for my own record of what was done. The custom BizTalk GVCLC LOB adapter  sends a poll command to a GVCLC vending machine and waits for  a response. The adapter connects to the machine over TCP/IP and starts a communications session. This session can last any length of time.

The socket C# library from Michael Stephenson was used as starting point.

I used the WCF LOB Adapter Development Wizard to create the GVCLC adapter project. I followed the steps from the EchoAdapter example and called the project and the solution GVCLCAdapter. At the welcome screen I supplied a schema of gvclc and a namespace. On the next screen I only ticked synchronous inbound dataflow and all the metadata features. On the next screen I specified the adapter properties as shown below. On the next screen I specified the connection properties as shown below. After pressing next on the summary page I got the expected project solution.

GVCLCAdapterConnection class

I continued to follow the EchoAdapter example and Michael Stephenson and updated the GVCLCAdapterConnection class.

• I added a field for the socket client and a field that tells us whether we are waiting for a response to send to the socket from BizTalk.
• Next I exposed the SocketClient and isWaitingBTSResponse as a property so they can they can be accessed from the inbound handler class.
• The constructor was modified following Michael Stephenson. In addition I assigned the value of _isWaiting4BTSResponse to false.
• The isvalid class was changed to make sure the adapter was still connectted to the socket.
• The Open method connects the adapter to the socket if the connection no longer exists.
• The Close method was implemented to gracefully shutdown the adapter.

GVCLCAdapterConnectionFactory class

Next i updated the GVCLCAdapterConnectionFactory class by opening the GVCLCAdapterConnectionFactory.cs file. I added the following private fields following Michael Stephenson.

GVCLCAdapterMetadataBrowseHandler class

I continued to follow the EchoAdapter example and updated the GVCLCAdapterMetadataBrowseHandler class to implement the GVCLC adapter’s metadata browse.

GVCLCAdapterMetadataSearchHandler

I continued to follow the EchoAdapter example and updated the GVCLCAdapterMetadataSearchHandler class to implement the IMetadataSearchHandler interface. Inside the Search method I replaced the existing logic in similar manner to he EchoAdapter.

GVCLCAdapterMetadataResolverHandler class

I continued to follow the EchoAdapter example and updated the GVCLCAdapterMetadataResolverHandler class to implement the IMetadataResolverHandler interface . Inside the IsOperationMetadataValid and IsTypeMetadataValid methods I replaced the existing with the following single statement to indicate that every specified type metadata is valid.

Inside the ResolveOperationMetadata method. I replaced the existing logic with the following to resolve the request and response operation. This is different from the EchoAdapter example because the response is now a predefined schema.

CustomGVCLCHonourDenyRespTypeMetadata and CustomGVCLCReqTypeMetadata

The request type metadata class and the response type metadata class was created following the EchoAdapter.

The request XML data definition and the response XML data definition was created. It is much easier if these are all data contacts. See Zhonje for an explanation of why this can be important.

GVCLCInboundHandler class

I continued to follow the EchoAdapter example and updated the IInboundHandler interface in the GVCLCInboundHandler class .

added  code to the StartListener method to reconnect to the TCP/IP socket if the connection is lost.

I provided the GVCLAdapter implementation for the TryReceive method.

• A poll message is sent to the socket.
• Subsequently  the socket is checked  for a response by trying the to receive from the socket using the same connection.
• If a “B” or a “N” is received, the adapter sleeps for the polling interval and then another pollong message is sent and the loop starts again.
• A GVCLC message is created if the message is not “B” or “N”.
• The polling stops until a response is received from BizTalk.

I added an implementation for the WaitForMessage method that is the same as in Michael Stephenson ‘s example.

The implementation of the Reply method handles the response from Biztalk back tot he adapter.

• The response is cast to a string using a custom override of the Tostring method on the proxy class that represents the GVCLC response.
• If the string contains a ”C” the response is sent back to the socket.
• Finally the polling of the socket is resumed.

I added an implementation for the Abort method that is the same as in Michael Stephenson ‘s example.

The TimeoutHelper class from the EchoAdapter example was added.

The GVCLC adapter was packaged following Sonuarora

Connecting BizTalk 2010 to a GVC-LC Vending Machine

I am writing about this because I think this is an interesting example of the new host tuning features in BizTalk 2010 and how to use the WCF LOB adapter SDK.

The GVC-LC vending machine  reads magnetic cards  and requests authorization via a TCP/IP socket before dispensing a vend. BizTalk takes a request from a vending machine, validates the card against a set of business rules and based on data retrieved from a database, returns the result of the validation to the vending machine. The latency as measured by the request/response time between the vending machine and BizTalk had to be less then one second 99% of the time to ensure an acceptable experience to a customer.

Custom WCF LOB Adapter for Vending Machine Communications

There is no out of the box BizTalk adapter that will communicate with the GVCLC vending machines. Communication with the vending machine is via a simple request/ response protocol where the custom BizTalk LOB adapter sends a poll command to the vending machine and waits for a response. The adapter connects to the machine over TCP/IP and starts a communications session. This session can last any length of time.

A custom WCF adapter was created to connect to the vending  machine (GVCLC) socket and handle all the communications before sending the messages to the BizTalk message box. I have summarised the GVCLC Adapter development here.

Tuning for Low Request/Response Latency

The table of latency tests below shows that sub-second request response latency can be achieved after the hosts have been tuned.

With the custom GVCLC WCF LOB adapter in hand an orchestration was built that persists the information on the card from the first card use until the end of the day.  Particular attention had been made during the creation of the orchestration to minimise the number of persistence points. Start orchestration shapes were used rather than call orchestration shapes and only one transaction scopes was  used around the database request/response. The number of persistence points per card swipe ranges between 2 to 3.

 

In this way the data is only retrieved from the source database once during the day and subsequent card swipes should have decreased latency.   The latency of this orchestration measured for about 900 unique card swipes ranges from 2.3 to 0.9 seconds. If a card that had already been swiped is swiped again then the latency is about 0.3 – 0.6 seconds because the data is already persisted. Surprisingly this time was not affected by the number of cards that were persisted. The latency when there were only ten card orchestrations dehydrated was almost identical to that when we had over 900 card orchestrations dehydrated. The latency was unaffected by the number of vending machines that were connected via the GVCLC adapter. Measurements using one machine or ten machines were identical.

If no cards are swiped for a long time (> 30 minutes) then the request/ response latency next card can be slow (> 2 seconds). This is due to the BizTalk assemblies being unloaded from memory when they are not being used. This was mitigated by setting up a custom domain to contain all the assemblies for this interchange and then setting the properties of SecondsEmptyBeforeShutdown and SecondsIdleBeforeShutdown to –1 as described by Ben Simmonds.

To decrease the request response latency three new “high priority” hosts were created, one for receiving messages, one for XLANG processing and one for sending messages. Additionally a dedicated tracking only host was created and tracking was disabled on all other hosts. After all the BizTalk artifacts had been assigned to the correct host the request response latency for about 400 unique card swipes decreased to be in a range of 1.4 to 1.0 seconds.

Finally we used the new host settings feature of BizTalk 2010 to change some of the settings on these three three hosts only.

• The value of polling interval was decreased for messaging from 500ms to 100ms for  the high priority hosts for receiving and sending messages.
• The value of internal message queue size was increased from 100 to 1000 on all high priority hosts.
• The value of polling interval was decreased for orchestrations from 500ms to 100ms on the high priority hosts for XLANG processing.

The measurement for 400 unique card swipes was now less than 0.7 seconds all of the time and most of the time is less than 0.4 seconds.

In summary the new host setting feature of BizTalk 2010 has been used advantageously to tune this BizTalk interchange. This highlights the power of tuning your BizTalk server either for low latency or high throughput depending on the exact situation. These results are all from my 32-bit development Windows 7 VM and we would expect much better figures from a production server.

Test Condition	No	Request/Response Latency(seconds)
		Range	Average
Initial card swipes, one host, one vending machine, and orchestrations do not contain send port to database.	6	0.6-0.5	-
Initial card swipes, one host, one vending machine, and orchestration contain send port to database.	6	1.2-1.8	1.4
Initial card swipes, one host, ten vending machines, ten card swipes simultaneously on each machine and orchestration contain send port to database.	10+	0.9-1.8	-
Initial card swipes, one host, one vending machines and orchestration contain send port to database.	400	1.0-1.9	-
Initial card swipes, one host, ten vending machines, card swipes sequentially on each machine and orchestration contain send port to database.	852	1.0-2.0	-
Initial card swipes, dedicated hosts, ten vending machines, card swipes sequentially on each machine and orchestration contain send port to database.	852	0.5-1.6	-
Initial card swipes, dedicated and tuned hosts, ten vending machines; card swipes sequentially on each machine and orchestration contain send port to database.	852	0.3-0.7	0.5

“Failed to start the BizTalk Host instance” – A strange case of this old chestnut

I got this error today while deploying to a UAT environment. The UAT environment was 64-bit and had two BizTalk 2010 server nodes.

Source:        BizTalk Server
Date:          27/01/2011 8:29:33 a.m.
Event ID:      5410
Task Category: BizTalk Server
Level:         Error
Keywords:      Classic
User:          N/A
Computer:      AKSDBTS01N2..com
Description:
A failure occurred when executing a Windows service request.
Service request: Start
BizTalk host name: testhost
Windows service name: BTSSvc$testhost

Additional error information:
Error code: 0×80131604
Error source: mscorlib
Error description: Exception has been thrown by the target of an invocation.

This annoying error is not very informative but in all my previous cases this had been a due to a bad entry in the BTSNVC.exe.config file. If this file is not correct then every host  instance will not start because this file is read by every host instance at startup.

In the present example host instances that had been created before our deployment would start without error. Any new host instance that was created after our deployment would not start. This was beginning to drive me crazy until we discovered that we had missed something in our deployment to one of the  BizTalk nodes. Our new deployment contained a new custom WCF LOB adapter which had to be registered by adding some new bindings to the machine.config files. We discovered that although we had changed the machine.config file at C:\Windows\Microsoft.NET\Framework\config\4.0.30319 we had not changed the machine.config at C:\Windows\Microsoft.NET\Framework64\config\4.0.30319. As soon as we added the missing machine.config file version all the host instances now started without error.

The deployment and configuration of all the receive ports and locations, orchestrations, sends ports, hosts,  host instances , receive handler and send handlers had been successful because during deployment the …Framework/config/4…  is not read. It is only when you try to start the new host instances that BizTalk complained because it cannot find the new adapter binding in the machine.config. What is really surprising is that this problem is exhibited by any new host instance that you create, either 32-bit or 64-bit. while any pre-existing host instances are not affected.

It would be really nice if you got a more informative error when this problem occurs.