Deploying a custom biztalk adapter with strong named assemblies

In a BizTalk environment it is sometimes necessary to create a custom adapter to implement functionality that is not available with the out-of-the-box adapters. This article will handle a small part in the process of implementing your custom adapter, the deployment part.

Also, this article only applies to adapters that use strong named assemblies. Using strong named assemblies has advantages like unique names, versioning, security,… See this link: http://msdn.microsoft.com/en-us/library/wd40t7ad(VS.71).aspx

To install or update your custom adapter you need to do the following steps.

Install the assemblies in the GAC.

You can use a MSI installation for production. For development you can drag your newly built assemblies in the GAC where the BizTalk runtime resides.You do this for both the design-time and run-time assembly.

Registry settings

When the BizTalk administration console starts it will check the registry for the design-time settings (assemblypath,propertynamespace). Therefor it is important to restart your administration console each time you update these. You can generate a registry file (.reg) to insert/update the adapter registry settings using the adapter registration wizard (see this link: http://msdn.microsoft.com/en-us/library/aa578379(BTS.20).aspx). Unfortunately some generated items are incorrect when using strong named assemblies. You can’t choose strong named assemblies when choosing the assemblies that represent your adapter with the Registration Wizard. This leads to values like these in the registry file: “AdapterMgmtAssemblyPath”=”C:\\MyProject\\bin\\debug\\AdapterManagement.dll”This is not the path for a strong named assembly. You can delete the values for the AdapterMgmtAssemblyPath, OutboundAssemblyPath and InboundAssemblyPath. Execute the registry file. You can verify the settings with the registry editor.

Update Database table

If you have not yet added your adapter to the available adapters yet, do this now. This is done by right clicking the adapters node in the administration console and choose new, adapter. Add your custom adapter. When adding your custom adapter, a record will be created in the adm_adapter table in the BizTalkMgmtDb. This record will be read when the runtime (host) starts, the host will load your adapter assembly based on the references in this table. It is not customary to change data in the BizTalk databases manually but we’ll make an exception just this once. Open the adm_adapter table in the BizTalkMgmtDb. Verify if strong named references to your runtime assembly is used. For example the inboundTypeName column should contain MyCompany.BizTalk.FileReceiver, MyCompany.BizTalk.FileReceiverClass, Version=11.4.0.0, Culture=neutral, publicKeyToken=63168444d906e8f6

Activate your adapter

You activate the new version of your adapter by restarting all the host instances that use it. Watch out for changed properties. These should be filled in properly for each receive location or send port that uses your adapter.

AS2 and context properties

In a previous post I wrote about an AS2 problem that I encountered after renaming the BizTalk Groupname.
In this post I digg into another AS2 problem, this time related to context properties.

Lately I have been asked to reconfigure an AS2 configuration to send messages with a predefined filename. This is easily done by selecting Transmit file name in MIME header. This checkbox can be found under the AS2 properties of the sending party. As you can see in the printscreen there is a possibility to point to a context property of which the value will be used as filename.
Simply put the context property shortname between two percent signs. If the context property wouldn’t exist you can choose to suspend the message.



After my first attempt to send a message another AS2 error showed up.


A message sent to adapter “HTTP” on send port “sp_As2ToACC” with URI “http://192.168.254.163:5081/BTSHTTPReceive.dll”
http://192.168.244.153:5081/BTSHTTPReceive.dll”
” is suspended. Error details: There was a failure executing the send pipeline: “Microsoft.BizTalk.EdiInt.DefaultPipelines.AS2Send, Microsoft.BizTalk.Edi.EdiIntPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35” Source: “AS2 encoder” Send Port: “sp_As2ToACC” URI: http://192.168.254.163:5081/BTSHTTPReceive.dll

Reason: The type initializer for ‘Microsoft.BizTalk.AS2.Pipelines.BizTalkPropertyList’ threw an exception.

MessageId: {451AC15C-7545-4487-8979-26E0511BCC3E}

InstanceID: {B8823D47-30F9-4E29-8649-8A965ADA1AF4}

Following the errormessage something went wrong with the initialisation of the BizTalkPropertyList.
This list can be found in the BizTalkMgmt database table bt_DocumentSpec.
The AS2 encoder will query this table to look up the property configured for retrieving the filename.
So what happened? If we open this table we see a lot of columns. But for the AS2 encoder only two seems to matter: clr_namespace and schema_root_name. The error mentioned above is caused when there are two or more property schemes deployed with the same value for these fields. In other words to avoid the AS2 encoder error, the concatenation of these fields must act as a primary key within this table. Also note that the duplicate property does not necessarely have a relation to the configured filename property. Lets have a closer look. Every BizTalk developer knows that every scheme must be made unique by its targetnamespace and rootname. This garantuees that BizTalk will process every message correctly. In the bt_DocumentSpec table this value is stored as ‘msgtype’. In this case we are talking about propertyschemes. So the msgtype field value is constructed by targetnamespace#propertyname. Because a scheme lives in a .Net BizTalk Assembly there is also another .NET namespace associated with the property. Right! clr.namespace.schema_root_name. Do remember that while this is not the fully qualified name of the property it is the value where the AS2 encoder will look for.

For example, the two rows shown in the picture below will cause the error.



I wrote a sql script to easily find duplicates in the bt_DocumentSpec table.

SELECT clr_namespace + ‘.’ + schema_root_name as shortName, COUNT(*)
FROM [dbo].[bt_DocumentSpec]
WHERE xsd_type <>
GROUP BY clr_namespace + ‘.’ + schema_root_name
HAVING COUNT(*) > 1

If you find duplicate properties you have to rename the clr_namespace. Do this by opening the propertylist of the propertyschema you want to modify (from within visual studio). There you will find the .Net namespace. Try to keep this namespace unique for all your BizTalk projects.