WCF LOB Adapter SDK and BizTalk Adapter Pack : BizTalk

Things to consider when writing WCF LOB Adapters for consumption through BizTalk

SandeepP — Thu, 12 Mar 2009 08:22:00 GMT

If you are writing a WCF LOB adapter that can be consumed through BizTalk, you need to be aware of certain issues that can manifest because of the way BizTalk interacts with WCF adapters. Some of these can have performance and scalability impact and hence you should consider them when designing/configuring the adapter.

Processing in IConnection/IConnectionFactory instance – When using SSO, for each message, BizTalk will end up creating a new IConnectionFactory and a new IConnection instance. If your adapter is doing a lot of processing in either of those instances, it can cause significant performance impact. So you will need to think of alternatives – possibly doing the processing upfront and caching.
Caching of LOB artifacts on IConnection instance – Typically you will have some LOB artifacts that will comprise the context associated with an IConnection instance. If your adapter is using WCF LOB Adapter SDK’s connection pooling, in the non SSO scenario, the IConnection instances will be closed only when the idle connection timeout expires. So you need to think about freeing up the LOB resources that comprise your connection context. If you make idle connection timeout too small, it would impact performance since LOB connection creation will incur an overhead and if you keep it at a large value then you will be holding on to LOB artifacts for a longer time than you really need to, possible scalability/performance impact.
Throughput stall – You can find more details about the issue on http://blogs.msdn.com/adapters/archive/2008/08/18/throughput-stalls-when-using-adapters-developed-against-the-wcf-lob-adapter-sdk-in-biztalk.aspx. Note that if you don’t limit the number of concurrent connections through your adapter, you won’t run into this problem. The problem happens the contention between Open and Send/Execute for thread pool threads.
Writing/promoting properties to BizTalk message context – When the adapter receives a WCF message from BizTalk, it will have all the properties comprising the BizTalk message context. For messages that originate from the adapter, if you want to have properties either written/promoted to BizTalk message context, you can look at http://technet.microsoft.com/en-us/library/bb246105.aspx on how to go about doing that.
Transaction overhead – BizTalk will by default start a transaction and send the message/process the response in that transaction scope. This can cause a significant overhead particularly if say the LOB doesn’t support transactions. In BizTalk 2009, there is an option on the Send port that lets you configure whether transactions should be enabled or not.

Throughput stalls when using adapters, developed against the WCF LOB Adapter SDK, in BizTalk

mdoctor — Mon, 18 Aug 2008 18:21:17 GMT

We’ve had a few users complaining about the throughput of the adapters (the Adapter Pack ones, and/or custom ones) coming to a standstill during normal operation within BizTalk. In this post, I’ll explain why that happens, and some workarounds.

Let’s say BizTalk has received 100 messages which it needs to send to the adapter on a Send Port. Assume that it queues 50 work items on 50 thread pool threads, with each work item containing 2 messages to be processed.

Now, on each of the above thread pool threads, the logic used is something similar to:

1. for (int i=0; i < numberOfMessages; i++)

2. {

3. IRequestChannel channel = CreateNewIRequestChannel();

4. channel.Open();

5. channel.BeginRequest(message[i], callbackFunction);

6. }

IRequestChannel above maps to an adapter channel – IOutboundHandler in the Adapter SDK.

Now, many of the LOB systems for which the adapters are written are do not have an asynchronous version of the LOB API or SDK, i.e., the LOB API is synchronous – blocks the current thread while the invocation occurs. However, as can be seen above, a call to BeginRequest() is made, which means that the caller wants the adapter channel implementation to return immediately. Therefore, in the Adapter SDK, the implementation is:

7. BeginRequest(Message message, Callback callbackFunction)

8. {

9. ThreadPool.QueueUserWorkItem(channel.Request, message, callbackFunction);

10. return immediately;

11. }

What the Adapter SDK does is, since it needs to return immediately, it queues an additional work item in the thread pool queue. The work item, when run, will call Request(), which is a synchronous call, which maps to IOutboundHandler::Execute() in the adapter, with the message as the parameter. Once the adapter finishes processing the message (synchronously) on the thread pool thread, the Adapter SDK takes care of invoking the callback function to notify BizTalk that the message has completed processing, and to hand the response message to BizTalk.

Also, one more piece of information – the channel.Open() call in line number 4 above, is handled by the Adapter SDK. When the Open() call reaches the Adapter SDK, it tries to obtain a free connection from the connection pool, or create a new connection to the LOB provided the maximum number of connections hasn’t been reached. If it is unsuccessful in both attempts, it blocks until a connection becomes available. Note - The adapters in the Adapter Pack expose a setting (typically named MaxConnectionsPerSystem, or MaxPoolSize, etc); the value of which is passed on to the Adapter SDK via a setting it exposes; custom adapters might expose something similar which the end user can tweak.

Given the two blocks of code above, and the behavior of the Open() call, it is now easy to come up with a situation where you can see a throughput stall.

Assume that the maximum number of threads in the thread pool is 100. Also, let’s say that the maximum number of connections allowed to the LOB system is 10. You receive a large number of messages from your Receive Location (for example, 500?), and BizTalk, in all its enthusiasm, queues up all messages (one message per work item – lets refer to these work items as W1) on threads from the thread pool. Therefore, you have 100 threads (suppose, since its the maximum number of allowable threads in the thread pool), all of them beginning to execute lines 1 to 6 above. Only 10 threads are able to proceed past line number 4, since they were able to open a connection to the LOB (your maximum number of connections is configured to be 10, remember?). The other 90 threads are blocked at line number 4, waiting for a connection to become available.

Of the 10 which passed 4, they proceeded to 5, which means they now enter lines 7 to 11. They all queue up work items (lets call these work items W2) on the the thread pool (courtesy line number 9), and return immediately. These 10 threads are now freed up, which enables them to go and pick more items to work on from the thread pool queue.

Now, the actual processing against the LOB (and the real usage of the connection which was successfully opened in step 4) only happens when W2 gets a chance to do its work. However, the 10 threads which were freed up, they won’t process W2. Why? Because ahead of W2, there are yet 400 more W1 work items (BizTalk had queued 500 items, remember) in the queue. Hence, the 10 threads will pick up 10 more W1 work items. These work items of course can’t progress since they are in the same state as the other 90 – there is no connection available. And a connection won’t become available until a W2 work item will relinquish it, but it can’t since it can only do its work once a thread becomes available, and that will only happen when one of the current 100 threads (which are all stuck on line 4) gets freed up, and …… and you have a thread pool starvation problem.

How do you work around this? A number of ways, and possibly, you need to use a combination of some of them (at least the ones in your control) to work around this:

One point where the threads are stuck is on line number 4. Easy – just increase the number of connections available to the LOB to a really large number, and your problem goes away. Right? Well, you might be prevented from doing that based on server resources, licenses, etc.
Lines 7 to 11 are responsible for queuing additional work items in the thread pool queue. You could avoid that if there was no need to queue a work item – for example, if your LOB exposed an asynchronous API, you could directly invoke that, passing it the callback routine pointer to “call back” on once it completed, and you could return immediately after kicking off that asynchronous API. Of course, this is not always possible. For example, LOBs like SAP and Siebel – the SDKs which we use did not offer an asynchronous API which we could use in the adapters.
One of the limitations which led to this situation, was that the maximum number of threads in the thread pool was limited. If you could increase the number of threads in the pool to a sufficiently large number, you wouldn’t see this problem. BizTalk exposes a setting for increasing the number of threads – see http://msdn.microsoft.com/en-us/library/cc296779.aspx. Note that you should try this out in your environment, since increasing it to a large value could possibly hurt performance.
In my example above, I’ve assumed that if there are 100 threads in the thread pool (maximum), all threads are being used during the processing of messages for my adapter. This is not always the case – the BizTalk runtime (and possibly other artifacts in the same process) will compete for threads from the thread pool, leaving lesser threads for you to work with. One way around this is to configure the send handler for your adapter to run in its own host instance (which means a separate process), leading to lesser contention for the threads from the pool in your process.
If you look at the code again, you notice that the main reason you got into this situation, was BizTalk itself – it queued up a huge number of messages (lines 1 to 6). The link mentioned above contains the information on settings which control the number of messages BizTalk processes simultaneously; tweaking something here can possibly help.

The safest way would be to ensure that the number of messages BizTalk hands to the adapter (lines 1 to 6) is the same as the maximum number of connections allowed to the LOB. I’m not 100% sure, but I think the In-Process Messages Per CPU setting can be used for this purpose; I’ll have to go through all the documentation for the throttling settings a little more thoroughly – meanwhile, you can do the same (the link available in point number 3 above seems to be the place to start).

Surfacing BizTalk Adapter Pack Adapters (WCF Bindings) as native BizTalk Adapters

mdoctor — Thu, 14 Aug 2008 19:32:48 GMT

One of the features we’ve enabled in the CTP3 of the BizTalk Adapter Pack V2 (which requires CTP3 of the WCF LOB Adapter SDK SP2), is the ability to expose the Adapters (which are in reality, WCF Bindings) as native BizTalk Adapters. Prior to this, if you wanted to use the Bindings from BizTalk, you had to use the WCF-Custom Adapter in BizTalk, then select the WCF Binding, and follow that route.

With CTP3, there is now an additional way you can use the adapters.

Firstly, install the CTP3 of the WCF LOB Adapter SDK SP2, and the CTP3 of the BizTalk Adapter Pack V2.
Open the BizTalk Server 2006 Administration Console
Navigate to the node as displayed in the screen shot below, right click in the empty space, and choose New->Adapter. A new dialog opens up.

Assuming you have the SQL and/or SAP Bindings installed during the installation of the Adapter Pack, you should see one or two entries in the “Adapter” drop down list, “WCF-SQL” and “WCF-SAP”. For the purpose of this blog illustration, choose WCF-SAP. Enter “WCF-SAP” in the Name text box, and press OK twice to close the dialog.
In the administration console, navigate to an existing application, and create a new Static Solicit-Response Send Port. You should now see WCF-SAP appear in the drop down list containing available Transport Types.

Click Configure to configure the transport. A new dialog opens up, containing a number of property pages.
The “General” tab looks similar to what you would see had you chosen WCF-Custom as the transport type. However, there is one addition. There is a “Configure” button above the text box where you enter the URI. You can click it to bring up a Connection Uri Builder Dialog.

If you navigate to the binding tab, you see that you no longer need to choose a binding. Also, the binding properties are displayed in a more user-friendly manner, with descriptions of the properties appearing at the bottom of the property grid.

The other four tabs (Behavior, Credentials, Messages, Import/Export) are the same as those which appear in the WCF-Custom adapter.

In CTP3, the above is available only for the SQL and SAP adapters. For the next CTP, we plan to do this for the OracleDB and the OracleEBS adapters also. Question – do you want this for the Siebel adapter too? If so, leave a comment here.

Also, in CTP3, this is being done only for BizTalk 2006 R2. For the next CTP, we plan to have this for BizTalk 2006 R3 also.

Making Microsoft BizTalk Adapter v2.0 for mySAP Business Suite projects work with WCF SAP Adapter #2

manasg — Thu, 17 Jan 2008 19:36:00 GMT

This is in continuation to the previous post, where we discussed the differences in the XML structure used by the old SAP adapter and the new WCF SAP Adapter. In a transactional scenario, the old adapter uses the context property named 'ConnectionType'. This context property is present in the new adapter too, with a few changes, which we illustrate here.

The corresponding values for the context property ‘ConnectionType’ in the old and the new adapters are as follows:

1. OPENREUSE: Open a new connection for reuse. Equivalent in new adapter is 'OPEN'
2. REUSECONNECTION: Reuse an existing cached connection. Equivalent in new adapter is 'REUSE'.
3. REUSECLOSECONNECTION: Reuse open connection and then close it. Equivalent in new adapter is 'CLOSE'.

In addition to the above, the new adapter provides an additional value 'ABORT', which closes the connection after the current call is made despite of any exceptions that may occur. This value does not have an equivalent in the old adapter. The WCF SAP Adapter documentation discusses this context property in more detail.

The pipeline component included with the preceding post (here) has now been updated to map the old adapter's context property ‘ConnectionType’ to that of the new adapter - in addition to the XML mapping it already did - making transition from the old adapter to the new one an easy process.

Making Microsoft BizTalk Adapter v2.0 for mySAP Business Suite projects work with WCF SAP Adapter

manasg — Mon, 14 Jan 2008 10:47:00 GMT

We have written a custom pipeline component (code and sample projects using this pipeline component are attached) that you can use to make your BizTalk orchestrations calling RFCs and BAPIs written with Microsoft BizTalk Adapter v2.0 for mySAP Business Suite work with the new WCF SAP Adapter. All you need to do is to use custom send and receive pipelines that replace the usual XMLTransmit and XMLReceive pipelines, and plug in the new adapter in place of the old one. No other changes. The source code of the pipeline component is included so you can make changes to it if you want to.

The custom pipeline component performs the following transformations:

1. Old adapter Request XML to New adapter request XML

2. New adapter Response XML to Old adapter response XML

The result? Your orchestration and messages do not have to change at all!

The major differences between the old and new adapters’ XML structure for RFCs are as follows:

1. Namespaces:

· Old Adapter : Root element is in the namespace http://schemas.microsoft.com/BizTalk/2003 while other elements have an empty namespace

· New Adapter: Elements with depth 0 and 1 are in the namespace http://Microsoft.LobServices.Sap/2007/03/Rfc/ while elements with depth 2 and 3 are in the namespace http://Microsoft.LobServices.Sap/2007/03/Types/Rfc/

2. Name of the Root Node:

· Old Adapter: The root node is named {RFC_NAME}_Request for the request XML, and {RFC_NAME}_Response for response XML

· New Adapter: The root node is named {RFC_NAME} for the request XML, and {RFC_NAME}Response for the response XML

3. Array of Complex types:

· Old Adapter : There are multiple nodes of with the name of the parameter, each of which contain one instance of the structure as the child nodes. The name of the complex type does not appear in the XML. For example:

<ComplexParameterName>
<Element1>Value1</Element1>
<Element2>Value2</Element2>

</ComplexParameterName>
          <ComplexParameterName>
                   <Element1>Value3</Element1>
                   <Element2>Value4</Element2>
          </ComplexParameterName>
           .
              .

· New Adapter : There is only one node with the name of the parameter, which contains multiple child nodes whose name is set to the name of the complex type , each containing one instance of the structure. For example:

.
.
<ComplexParameterName>
          <ComplexTypeName>
                   <Element1>Value1</Element1>
                   <Element2>Value2</Element2>
          </ComplexTypeName>
          <ComplexTypeName>
                   <Element1>Value3</Element1>
                   <Element2>Value4</Element2>
          </ComplexTypeName>
</ComplexParameterName>
.
.

4. Tables Returned:

· Old Adapter: All tables that have any output value are returned.

· New Adapter: Only the tables that were present in the request XML are present in the response XML.

How does the custom component work?

Changing Namespaces and Name of the root node is straightforward. To figure out the name of the ComplexParameter’s type, we use reflection on the RFC specific dll created by the old adapter, and expect it to be present at “C:\Program Files\Microsoft BizTalk Adapter v2.0 for mySAP Business Suite\Bin\{RFC_Name}.dll” (The old adapter creates this Dll automatically when you generate the RFC Schema). To make sure the tables returned are same as what the old adapter would have returned, we append empty nodes for all the table parameters that were not included in the request XML by using the schema in your project. That way, the response XML contains all tables. Now we simply eliminate the tables that are empty to get the response similar to that of the older adapter.

Using the custom pipeline component

1. Build the custom pipeline component or use the dll included

2. Copy the assembly to “C:\Program Files\Microsoft BizTalk Server 2006\Pipeline Components” and also add it to the GAC

3. In your existing BizTalk project, create new send and receive pipelines and include the custom component in encode and decode stages. (you’ll need to add reference to the custom pipeline assembly and add it to the pipeline toolbox)

4. Build and deploy

5. Go to the BizTalk administration console and restart the host instance.

6. For the ports that send or receive to/from SAP, select the new SAP adapter and configure it as described in the documentation. Set the ‘enableSafeTyping’ binding property to true

7. Use the custom pipeline you created with the ports that talk to SAP

8. Start!

A few sample BizTalk projects that use schemas generated with the old adapter and include custom pipelines are included in the attachment. Sample configuration bindings are also included. To build the samples, you should change the name of the SQL server in project deployment properties.

Update: The attached Pipeline component has been updated to transform the context property 'ConnectionType' too. See this post for more info.

Why does the Adapter say ‘Action is not understood’ even though I am using the binding file generated by the ‘Consume Adapter Service’ wizard?

tusharma — Wed, 26 Dec 2007 09:03:00 GMT

Believe me, the adapter is telling the truth! It really doesn’t understand the action it got! To understand what’s going on, read on…

When you use the ‘Consume Adapter Service’ wizard to generate LOB schemas in a BizTalk project, you also get a binding file which you can import (using the BizTalk Administration Console) to create the corresponding physical WCF-Custom port (Send or Receive Port, based on whether the contract was Outbound or Inbound respectively) when deploying your BizTalk Application. While this does save you the pain of creating and configuring the port manually, there is a ‘not-so-obvious’ caveat which you need to be aware of. (This applies only to send ports i.e. Outbound Contracts)

The WCF-Custom Adapter allows the SOAP Action to be specified in the following two ways on the static send ports:-

As a single line of text – the port is used for a single intended operation (say ‘ABC Action’).
As an xml, mapping each of a set of ‘Operations’ to the corresponding SOAP Action. This xml looks something like this:- (namespaces omitted for clarity)

<BtsActionMapping>
<Operation Name =”ABC” Action = “ABC Action” \>
<Operation Name = “XYZ” Action = “XYZ Action” \>
</BtsActionMapping>

The binding file created by the ‘Consume Adapter Service’ wizard chooses the second method to specify the action, even if you generate schemas for a single operation.

Now the question is, when a message comes to a port using such a mapping, how does it know what the intended operation was? Or more specifically, how does it know which action to use for which incoming message?

To make this decision, the WCF-Custom adapter compares the message’s BTS.Operation context property with the list of operations in the map (attribute ‘Name’). If a match is found, the corresponding action is used.

However, if the WCF-Custom adapter fails to resolve the operation name from the map, it assumes that the entire thing specified is a single line action (as in 1 above) and sends the whole string to the target adapter binding.

The most common scenario this could happen is when you create an orchestration and forget to change the operation names on the logical ports to appropriate names. By default, when you create a logial port in an orchestration, it’d be created with a single operation called ‘Operation_1’. The next operation you add (either on the same port or while creating another port) would be called ‘Operation_2’ and so on. You need to modify these default names to the appropriate names as the BTS.Operation context property derives it’s value from the operation name on the logical orchestration port which published the message to the message box. (That also means if you are not using orchestration and still want to use the Action-Mapping feature, you’ll probably need to write a custom pipeline component to populate this context property).

So if you are seeing the error mentioned in the title, what is possibly happening is this:-

Your FOO Adapter supports two operations with the corresponding actions being ‘ABC Action’ and ‘XYZ Action’. You generate the schemas and the binding file, create an orchestration (but forget to change the default operation names), tie the message types, deploy the project and import the binding file.

At runtime when you send a message, because you did not change the operation name on the logical port, the BTS.Operation property is set to ‘Operation_1’. The WCF-Custom adapter tries to look up this name in the map you specified on the send port (by importing the binding file). Since it does not find any operation by the name ‘Operation_1’, the WCF-Custom adapter believes that whatever you specified on the port is a single line action and passes the same to the FOO adapter.

So, instead of getting “ABC Action” or “XYZ Action”, which it understands, the FOO adapter gets “<BtsActionMapping><Operation Name =”ABC” Action = “ABC Action” \><Operation Name = “XYZ” Action = “XYZ Action” \></BtsActionMapping>”.

Clearly, it doesn’t understand that action!

Ok, so what do I do to fix this?

In the above example, you should change the operation names on the logical ports in the orchestration to ‘ABC’ and ‘XYZ’ instead of the default ‘Operation_1’, ‘Operation_2’ etc. (Of course, you can also do it the other way round – change the mapping on the port to use names in the orchestration or, if there is just one action to use, specify the action directly on the port instead of using the action map.)
Basically, you need to make sure that the WCF-Adapter is able to resolve the operation name on the message to use the correct action, as explained above.