Posts Tagged Adapter Pack
Why would you want a WCF LOB SDK Adapter?
Introduction
In my last post I mentioned the registry content for registering a custom WCF LOB SDK binding as an adapter. I am still working out the details of how this should be done for a custom adapter and will be hoping how to do this in a walkthrough in a later post.
To give you some preview of the process, the adapter class just needs to inherit from Microsoft.Adapters.Common.BizTalk from the BizTalk adapter pack rather than Microsoft.ServiceModel.Channels.Common.Adapter from the WCF LOB SDK. The abstract classes for Microsoft.Adapters.Common.BizTalk are included with the BizTalk Adapter Pack. The GUID values mentioned in the .reg file are set in the derived adapter classes and when calling the base class constructor for the adapter, WcfBtsAsdkAdapterBinding.
While it looks like it is possible to register a custom WCF LOB SDK binding as an adapter, the question comes up as to why would you ever want to do this when you can just use the custom binding in the WCF-Custom adapter anyway. This is one question I have asked repeatedly in reference to why the BizTalk adapter pack gives the developer the option of using the separate adapter rather than the bindings with the WCF-Custom adapter. At this time I am not sure if some of the scenarios I have come up with explain why the BizTalk adapter pack bindings are also exposed as custom adapters.
I wanted to take this post and describe a few scenarios that would be useful for having the capability of an adapter rather than a WCF-Custom binding.
Discussion
Deciding whether to expose a WCF LOB SDK binding vs. a full adapter is an important question that depends largely on the consumers of your data. If you want the same data and management of the connection to your data to be the same whether it is being called from .NET or BizTalk then use of the standard custom binding makes sense. You will only need to code the logic once as the custom binding. But there are typically many differences between .NET applications and BizTalk applications so it seems like there would be compelling reasons to have other settings or different settings based on whether the binding is being called from a BizTalk system. For example, SSO settings like the SSO Application Name and key should not be exposed unless the binding is being called from BizTalk. These properties will not make sense if you are providing a way to connect to your custom LOB data without going through BizTalk.
The full adapter does have a configuration limitation that prevents it from fully functioning as an equivalent to the WCF-Custom binding. The custom binding configuration exposes the custom behavior config window for all WCF-Custom adapter handler properties. At this point I am not sure if it is possible to have the custom full adapter to provide a customized property page for the adapter handler properties. Interestingly, all of the BizTalk adapter pack custom adapters have the properties button grayed out in the adapter handler window. So it is not even possible to choose the same adapter handler configuration as found on the WCF-Custom adapter handlers so if you did use a full adapter rather than WCF-Custom you would still need to register the custom WCF behaviors in the machine.config. This could possibly be an overlooked scenario in the current implementation.
So theoretically it is possible to come up with a reasonably good scenario for splitting apart the properties and implementation based on the caller type. But due to the current BizTalk admin console limitation on the adapter handlers configuration, there may unfortunately be some tradeoffs.
Thanks,
Sample .reg file for WCF-LOB SDK Adapter registration
On the forums today someone was asking how to register a custom adapter based on the WCF LOB SDK. The question was not how to get it to show up in the bindings list for the WCF-Custom adapter, it was how to get the custom adapter to show up as an actual adapter. With the BizTalk adapter pack, the custom adapters show up both as custom bindings under the WCF-Custom adapter and as custom adapters under Platform Settings\Adapters. The WCF LOB SDK gives good examples for how to register the custom binding and there are some free tools to help with this like this one: http://regwcflobmsbuildtask.codeplex.com/. But there are not any .reg files in the samples folder for the SDK like there are for the samples found at c:\Program Files (x86)\Microsoft BizTalk Server 2010\SDK\Samples\Adapter Development\…
I developed one custom adapter using the older adapter framework for a major client to interface with the Endeca search index tool (www.endeca.com). Based on my experience working with the adapter framework, I knew there was probably a GUID value I could use to find the registry settings for registering a WCF LOB SDK adapter. So I opened the WCF-SQL adapter assembly in Reflector and found the GUID value. Then I opened the registry and searched it under HKLM\Software\Microsoft to find the registry keys for the WCF-SQL adapter. Although this was not surprising to me, it was interesting to see that many of the registry values are similar to the values given for the adapter framework settings in the .reg files of the SDK samples.
Here is the WCF-SQL adapter registry content – shown below. Here is a link for just downloading the .reg file. This seemed like a missing sample file so I will be working on taking the Contoso and Echo adapters and creating registry files for them. There are a couple logical questions about what to do to your custom WCF LOB SDK code in order to make it work with the .reg file so I will be working on that next. Having the .reg file available makes it a lot easier to accomplish the adapter registration.
Thanks!
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}]
@="WCF-SQL"
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\BizTalk]
@="BizTalk"
"TransportType"="WCF-SQL"
"Constraints"=dword:0000030b
"ReceiveLocation_PageProv"="{86e62ea8-d681-4aac-a62b-f8e7dc0306b4}"
"TransmitLocation_PageProv"="{ea897b1c-08b9-4d21-87fa-223f7fc5acf3}"
"AdapterMgmtCLSID"="{dea558d0-6960-4f96-9bc7-9b3837689fc0}"
"AdapterMgmtTypeName"="Microsoft.Adapters.Sql.BizTalk.WcfBtsSqlManage, Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"InboundEngineCLSID"="{1ad7c0c2-cdd2-4e87-922c-6e89d9f8b0e2}"
"InboundTypeName"="Microsoft.Adapters.Sql.BizTalk.WcfBtsSqlReceiver, Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"OutboundEngineCLSID"="{6a640a11-2f39-42eb-96c7-490aac4f32f6}"
"OutboundTypeName"="Microsoft.Adapters.Sql.BizTalk.WcfBtsSqlTransmitter, Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"PropertyNameSpace"="http://schemas.microsoft.com/BizTalk/2006/01/Adapters/WCF-properties"
"AliasesXML"="<AdapterAliasList />"
"ReceiveHandlerPropertiesXML"="<CustomProps><WcfExtensions vt=\"8\" /></CustomProps>"
"ReceiveLocationPropertiesXML"="<CustomProps><Headers vt=\"8\" /><BindingType vt=\"8\" /><BindingConfiguration vt=\"8\" /><ReferencedBindings vt=\"8\" /><ServiceBehaviorConfiguration vt=\"8\" /><EndpointBehaviorConfiguration vt=\"8\" /><InboundBodyLocation vt=\"8\" /><InboundBodyPathExpression vt=\"8\" /><InboundNodeEncoding vt=\"8\" /><OutboundBodyLocation vt=\"8\" /><OutboundXmlTemplate vt=\"8\" /><DisableLocationOnFailure vt=\"11\" /><SuspendMessageOnFailure vt=\"11\" /><IncludeExceptionDetailInFaults vt=\"11\" /><CredentialType vt=\"8\" /><UserName vt=\"8\" /><Password vt=\"8\">Encrypted</Password><AffiliateApplicationName vt=\"8\" /><OrderedProcessing vt=\"11\" /><Identity vt=\"8\" /></CustomProps>"
"SendHandlerPropertiesXML"="<CustomProps><WcfExtensions vt=\"8\" /></CustomProps>"
"SendLocationPropertiesXML"="<CustomProps><Headers vt=\"8\" /><BindingType vt=\"8\" /><BindingConfiguration vt=\"8\" /><ReferencedBindings vt=\"8\" /><EndpointBehaviorConfiguration vt=\"8\" /><StaticAction vt=\"8\" /><UseSSO vt=\"11\" /><UserName vt=\"8\" /><Password vt=\"8\">Encrypted</Password><AffiliateApplicationName vt=\"8\" /><ProxyAddress vt=\"8\" /><ProxyUserName vt=\"8\" /><ProxyPassword vt=\"8\">Encrypted</ProxyPassword><InboundBodyLocation vt=\"8\" /><InboundBodyPathExpression vt=\"8\" /><InboundNodeEncoding vt=\"8\" /><OutboundBodyLocation vt=\"8\" /><OutboundXmlTemplate vt=\"8\" /><PropagateFaultMessage vt=\"11\" /><EnableTransaction vt=\"11\" /><IsolationLevel vt=\"8\" /><Identity vt=\"8\" /></CustomProps>"
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\Implemented Categories]
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\Implemented Categories\{7F46FC3E-3C2C-405B-A47F-8D17942BA8F9}]
[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{59b35d03-6a06-4734-a249-ef561254ecf7}\Install]
"Assembly"="Microsoft.Adapters.Sql.BizTalk, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
"DateTime"="12/28/2010 00:20:47"
WCF-SQL Adapter’s Database Schema Gotcha
- BizTalk WCF-Custom SOAP Action Headers such as TypedProcedure/dbo/MyProcCall to TypedProcedure/MySchema/MyProcCall
- BizTalk binding properties with SQL information such as the properties notificationStatement, pollingStatement, or polledDataAvailableStatement, etc.
I restarted my BizTalk application and hosts and I started getting errors that referred to my old database schema. At this point I realized that the database schema is actually hard coded during the BizTalk schema generation process. This is a significant gotcha; that the changing of the database schema for custom objects that BizTalk uses requires a regeneration of the BizTalk schemas. The next section describes the steps I went through to correct the old database schema references after moving my database objects to the new database schema:
Resoluton
In addition to the deployment steps done above, I had to update several of my BizTalk solution artifacts. For my BizTalk solution, I was working with 5 different database objects and I did not want to delete all of my BizTalk schema files (approx. 15 different files) and go through the adapter wizard so many times. I decided to opt for a find and replace solution instead. Here are the steps I did to replace the old database schema references:
- Open up the base and referenced BizTalk schemas using the Open With…, XML Editor. If you are interacting with rows of data then you may have separate referenced schema files that may also have the old schema in them.
- Do find/replace and search for "/dbo" or whatever old database schema you are replacing. The "/" comes from the SOAP Action Header.
- Save the schema changes.
- Once you replace one database schema reference, your BizTalk schema will be in an inconsistent state until all of the database schema references have been updated. Try opening the BizTalk schema in the BizTalk schema designer and if you get a warning when opening you will know that there are still old database schema references to migrate. When all of the old database schema references are replaced you will no longer get a warning
- Recompile
- Then investigate the BizTalk map and orchestration files because these also contain hard coded references to the old database schema.
- It would seem that a recompile of your BizTalk solution would regenerate the .cs files for the BizTalk maps and orchestrations, but I found this to not be the case. An approach I found that worked was to open any BizTalk maps and make an insignificant change (add a functoid and then remove it) just to change the file status to edited and then to save the map. This would refresh the generated map code.
- Also, I opened all of my BizTalk orchestrations and double-clicked all of the Transform shapes and then checked the button "Open the map when I click the OK button" to change the file status to edited. This refreshed the generated orchestration code. Even though no actual changes were made the generated code was refreshed.
- You could alternately remove all of the generated files such as those named like *.odx.cs or *.btm.cs
- One disadvantage of this find & replace technique is that your old generated binding files will still refer to the old database schema so be sure to discard those.
Conclusion
This post has shown that a change to the database schema for SQL objects can have a major ripple effect on a BizTalk solution that uses the WCF-SQL adapter. I do not expect that changes to database schemas occurs very often so you may never encounter this but if you do, be prepared for a little bit of work to get the updated database schema names back into your solution. Thanks for reading!
Simplify the Install Experience of the BizTalk SAP Adapter
During a recent project I was using the BizTalk SAP Adapter to interact with a custom BAPI that was exposed as an RFC. In order to get the Add Adapter Service Wizard in BizTalk to work properly, I had to install all of the SAP dependency libraries on the BizTalk server. I was amazed at how complicated this whole process was. There are a couple things I would like to do in this blog post:
- Give the names of all of the files that must be used for 32-bit and 64-bit installs of the SAP dependencies for the 6.4 version of the SAP RFC SDK.
- Provide a shell script for copying all of the SAP dependencies for 32-bit and 64-bit installs of the SAP dependencies
- Provide some additional details on the SAP Adapter installation.
The reasons I am posting on this is because I think the InstallGuide.htm which is included with the BizTalk Adapter Pack is a little vague. The file is already very long and inclusive but some important details like the names of many of the SAP client files is not included. Below is an expanded list of directions for the 6.4 version of the SAP client dependency installation:
| SAP client version | Required drivers |
|---|---|
|
6.4 32-bit |
|
| ———- | ————————————————————————————- |
|
6.4 64-bit |
|
WCF-SQL Adapter Modernizes BizTalk SQL Adapter Capabilities
In my spare time I have been playing and testing all of the latest released capabilities of BizTalk Server 2009. During some of my time I have been working with the new WCF-SQL adapter that exposes a new WCF binding, SqlBinding, as part of the latest Adapter Pack. If you have ever worked with the BizTalk SQL adapter you know that the wizard in Visual Studio frequently caused problems and unfortunately these shortcomings were never adequately addressed in a service pack or updated release. Usually it was required that you just take a working example of the SQL adapter and then manually modify it to work with your database objects. More often than not you probably just avoided the SQL adapter completely and worked with the database through ADO.NET calls in an orchestration or custom pipeline. Now with the updated Adapter pack the WCF-SQL adapter finally modernizes the SQL adapter experience and gives you a stabile and very functional environment for interacting with SQL via an adapter. This article will highlight some of its capabilities and provide a walkthrough of the new WCF-SQL adapter wizard.
All of my testing has been with the BizTalk 2009 Beta loaded on a Windows Server 2003 box with Visual Studio 2008 (including SP1) installed. I installed the BizTalk Adapter Pack found at https://connect.microsoft.com/content/content.aspx?ContentID=10580&SiteID=218. To add a schema based on the WCF-SQL adapter, open or create a BizTalk project in Visual Studio 2008 and right-click on the project. Clcik on the Add New Item > Add Generated Items as shown below:
Then after the window loads you should see the following window:
Click on "Add Adapter Metadata" and then click "Add". This will open up a general window that is used for several different adapters. After installing the BizTalk Adapter Pack V2, you should see an item listed in the listview called WCF-SQL. You should also see the older SQL item listed as well as any other Adapter Pack or Line-of-Business (LOB) adapters. You will need to enter a SQL server name and database in the combo boxes below the listview. I entered my local SQL Server instance and my BizTalkMgmtDb as seen in the screenshot below:
You do not need to enter a port for this adapter so just leave this one blank and click Next. The following screen shows the form that is loaded next to help you determine which SQL objects to include in the WCF-SQL schema. If you worked with the previously mentioned rudimentary SQL adapter in BizTalk, at this point you would be presented with the option of entering a command text or a single SQL object name for the wizard to use to generate the schema. But the WCF-SQL adapter wizard provides database object browsing and filtering to further simplify the task of schema generation. The following screenshot shows the form when it is initially loaded:
If you merely want to use the database you specified earlier in the wizard, click the configure button and then click OK to generate the default URI of mssql://.//?. Then click Connect to connect to the database specified. This will enable the bottom half of the screen where you can expand the categories of database objects and then find one or more objects to select. It is also possible to select a different database and/or configure additional database connectivity properties via the Configure button’s window. Below is an image of the Configure button’s window with the SSO database details specified:
I have found that it is not possible to specify "(local)" for the SQL instance name as shown above so do not try this. Below is the form changed to allow selecting from several of the SSO databases’s tables:
The "Search in Category" box in the middle of the form provides a way to filter the list of database objects. I have found that it is possible to use wildcards in this box by the percent character "%" but not by the asterisk – "*". Once you have selected objects to generate a schema for, click OK. Visual Studio will generate a schema and a related code class as well.
The designer experience provided by the WCF-SQL adapter wizard is a huge step forward for the creation of BizTalk SQL schemas.
