Components of a Design Time Adapter

Here is some content I am publishing on static vs dynamic design time adapters. There seems to be some confusion on documentation I have seen with respect to what exactly are we referring to when we mention “static” and “dynamic” in the context of design time.  Maybe this will help somoe folks understand better – I felt it was to the point and useful.


I also am solicting feedback on existing documenation from anyone who has struggled trying to understand this simple differentiation that is often somewhat confusing how it is written. How can we make this better for you?  Thank you!


———————————————


Components of a Design Time Adapter


An adapter contains both a run-time and a design-time component. The run-time component is not visible to a user. It is transparently responsible for the transmission, receipt, and processing of BizTalk Server messages.


The design-time component of an adapter is visible through administrative user interfaces. It is responsible for displaying available properties, accepting administrative input, and validating that input to configure an adapter. It is critical that the design-time component allow proper configuration of the adapter’s properties to enable the run-time functionality to exchange messages correctly.


Here we consider only the design-time component of an adapter. We will thus be concerned primarily with how to display and set the adapter’s configuration. There are two methods of configuring an adapter:


%u00b7         Property browser. Adapter properties for a send or receive port, or a send or receive handler, are configured through their Properties menu by using the BizTalk Server Administration console. During configuration of these artifacts the adapter (transport) is selected and its properties are configured by using a property browser. Applicable properties are displayed through a schema with a set name. For instance, for a send (transmit) handler the properties would be in the TransmitHandler.xsd file; for a receive location they would be in the ReceiveLocation.xsd file.  The adapter implements the IAdapterConfig interface to locate and load the appropriate schema to expose specific properties in the property browser. The IAdapterConfigValidation interface is used to validate those entries and make any final modifications to the values before saving the configuration data.


%u00b7         Add Adapter Metadata Wizard. This is (slightly) renamed for Biztalk Server 2006 by adding the term “Metadata”.  In the case of application and database adapters, you may need to import supporting schemas that describe message types and port types that the adapter needs in the BizTalk project in Visual Studio 2005. Or sometimes there is the need to consume services provided by the adapter. The Add Adapter Metadata Wizard enables you to view services that an adapter supports and import the related message types and port types into your project. This process is known as “metadata harvesting.” As an adapter developer you create an XML file describing those services and expose it to the wizard at design time through either the IStaticAdapterConfig or IDynamicAdapterConfig interface, with the following results:


a.         Static adapter. The wizard provides a standard default hierarchical tree structure with which to display the adapter’s services. A static adapter is defined as an adapter that uses the standard tree user interface (UI) provided by the wizard. Use the IStaticAdapterConfig.GetServiceOrganization and GetServiceDescription methods to allow selected services to be added to the BizTalk project. This is the simplest configuration option for an adapter developer, but the tradeoff is rigidity of the display format.


b.      Dynamic adapter. If the basic service selection UI provided by the wizard is not flexible enough meet your UI needs you can create a custom UI that is dynamically displayed by the wizard. Use the IDynamicAdapterConfig.DisplayUI method to display the custom UI to allow selection of services to be added to a BizTalk project.


 

Sorting, Grouping, and Debatching in Pure Messaging

Debatching can be done several different ways in BizTalk 2004. With a few message box hops, debatching can be done with a few maps and an envelope schema in pure messaging. This sample shows a map for Sorting, a map for Grouping, and the Envelope for debatching.

This sample will work in BizTalk 2004 and BizTalk 2006.

Get more information from the original blog post on this topic: https://www.biztalkgurus.com/biztalk_server/biztalk_blogs/b/biztalk/archive/2006/04/03/how-to-use-biztalk-messaging-for-grouping_2c00_-sorting_2c00_-and-debatching.aspx

Self Correlation and Passing Configured Port Parameters

Using Self Correlation, the Start Orchestration Shape, and Passing Configured Ports it is easy to get messages back into an Orchestration after it has been processed by another process. This sample shows how to Start two different Orchestrations and receive a response message without any Correlation Set to configure.

This sample should work for in BizTalk 2004 and BizTalk 2006.

Get more information from the original blog post on this topic: https://www.biztalkgurus.com/biztalk_server/biztalk_blogs/b/biztalk/archive/2006/02/28/working-with-start-orchestration-shapes_2c00_-self-correlated-ports_2c00_-and-configured-port-parameters.aspx

Working With Start Orchestration Shapes, Self Correlated Ports, and Configured Port Parameters

These three topics could be entire blog posts on there own.  In this case, I’ll briefly cover all three and show how to use them all together.



Start Orchestration – This shape give you the ability to asynchronously start a new Orchestration.  You can pass in all types of parameters but you can not return parameters like the Call Orchestration Shape. 



Passing Configured Port Parameters – This is an input parameter type for Call and Start Orchestrations.  This can be used to pass in already configured ports to use to send messages back into the original Orchestration. 



Direct Binding using Self Correlation – When passing Self Correlation ports to a Started Orchestration a unique token is placed in BTS.PartnerService.  This is used for the return subscription.  I have not worked with Self Correlation Ports in any other scenario although they can be used on there own without a Start or Called Orchestration.



Solution Overview:  A single message is received into a Master Orchestration (Master).  This single message is then used to Start two different Orchestrations (SharedLogicA and SharedLogicB).  Inside these two Orchestrations, the message is “processed” (i.e. mapped and a 5 to 15 second delay is used to simulate processing).  The resulting mapped messages are returned to the Master Orchestration.  A single result message is sent out.



Download: Passing Configured Port Parameters Sample



The master Orchestration looks something like this:





How does this differ from Direct Binding Using Partner Ports? 


It is very similar except that you do not use the Start Orchestration shape (thus can not pass parameters, multiple messages, and so on).  Using Partner Ports, if you wanted a message back you would need to create a Correction Set and work out all those complexities.  There is some other under the cover differences between the two but that is for another post.



How to set this up on your own:


Step 1: Create the Master Orchestration with a Receive Port and a SharedLogic Orchestration.  Set up all required input and output messages.  Set up the Send Shape inside the SharedLogic Orchestation to send back the correct message.



Step 2: Inside the Master Orchestration add the Receive Shape and set it up to receive the response message from the SharedLogic Orchestration.  Select the Red ! to configure the Operation for the Receive Shape.  Give the Port a name (Port_A), create a new port type (PortType_A), select Directing Binding – Self Correlation.





Step 3: Inside the SharedLogic Orchestration add the parameters that will be passed in by from the Master.  In this case, an input message (InputA) and a configured port parameter (Port_1).  For the port type, select the type create above (PortType_A), for Port Binding select “I’ll always be sending messages on this port”.  Connect your Send Shape to your new Port. 









Step 4: Lastly, inside your Master Orchestration add a Start Orchestration Shape.  Select your Sharedlogic Orchestration.  Set your two input parameters if needed.







Note that you can send and receive messages on the same port type when using the Start Orchestration Shape.  If you tried this same approach with the Call Orchestration shape you would get a build error.  Read more about this on Charles Young awesome article on this topic.

One or more instances of the orchestration still exist

Lately I tried to redeploy a BizTalk 2006 solution from Visual Studio 2005. Unfortunately I was confronted with the following error message “Could not change the bindings for orchestration ‘.’, Version=1.0.0.0,Culture=neutral, PublicKeyToken=c380e04620d206e8′ as one or more instances of the orchestration still exist”.
When I tried to Unenlist and delete the Orchestration from the BizTalk Administration tool, I received the same error.

I found out that I had a few suspended instances. These instances need to be terminated before you can undeploy/redeploy the orchestration.

Terminating instances can be done in several manners:
– the polite manner: by terminating the instances using the BizTalk Administration Tool
– the not so polite manner: by using a Stored Procedure to clean up the MessageBox

Removing instances using the BizTalk Administration Tool
In the BizTalk Administration Group click in the left pane on ’BizTalk Group [Name of Computer/Name of Management database]’. In the right pane the ’Group Overview’ appears. Click on the tab page ’New query’ to create a query that searches for the suspended instances. In the ’Query Expression’ grid the first Search field is already selected, namely ’Search For’, also the ’Equals’ operator is already filled in in the second field. All we have to do in the ’Value’-field is search for suspended instances. And lucky us: when we open the dropdown box we see that ’Suspended Service Instances’ is one of the values we can choose! Next, we run the query by hitting the button with the label ‘Run Query’. The grid ’Query results’ now contains all suspended instances found. All we need to do is select all suspended instances, right click on the selection and choose ’Terminate Instances’. The BizTalk Administration Tool asks for confirmation and removes the instances. When you rerun the query, the instances will be removed and the orchestration can be undeployed/redeployed. So far for the polite manner.

Removing instances using a Stored Procedure
The less polite manner to remove suspended instances is by running a Stored Procedure which will clean up the MessageBox. Attention: this is NOT a recommended procedure on production environments!
Open the SQL Server Management Studio and connect to the database server. In the left pane expand the server-node and the Databases-node. Next, click on the MessageBox-database (BizTalkMsgDb) and hit the ’New Query’-button in the toolbar. In the right pane you can enter SQL commands. Since you selected the MessageBox-database in the left pane, the commands are executed against that database. Now type: ‘exec bts_CleanupMsgbox 0’ (without the quotes) and hit the ’! Execute’-button in the toolbar. All suspended instances will now be removed. You can now undeploy/redeploy the orchestration.

Common COM HRESULTs…

It’s so annoying to look for HRESULT codes… I remember some, but not all. So, why not to list them here? At least they will be easy to find.


Well, actually it’s easy in VS too — the codes are declared in WinError.h, it’s just it is never opened and hard to open with one click. So, here they are (just S_*, E_* and CLASS_E_* — class factories codes):







































































Name Hex Decimal
S_OK 00000000 0
S_FALSE 00000001 1
E_PENDING 8000000A 2147483658
E_NOTIMPL 80004001 2147500033
E_NOINTERFACE 80004002 2147500034
E_POINTER 80004003 2147500035
E_ABORT 80004004 2147500036
E_FAIL 80004005 2147500037
E_UNEXPECTED 8000FFFF 2147549183
CLASS_E_NOAGGREGATION 80040110 2147746064
CLASS_E_CLASSNOTAVAILABLE 80040111 2147746065
CLASS_E_NOTLICENSED 80040112 2147746066
E_ACCESSDENIED 80070005 2147942405
E_HANDLE 80070006 2147942406
E_OUTOFMEMORY 8007000E 2147942414
E_INVALIDARG 80070057 2147942487

 

MSH Segment and the undocumented required object

I have been at a few client sites that had required that we use cusom namespaces for their HL7 interfaces.

This is all well and good, but what is not mentioned is that you have to have the BTHL72XCommon project deployed, because the acellerator absolutely requires it to be deployed to handle the MSH segment.

The reason why this is the case is because the pipeline component only looks for the default microsoft target namespace (http://microsoft.com/HealthCare/HL7/2X). The implications of this are: if you want to make changes to the format of the MSH segment, you only can do it with one schema.

Upgrade can be resumed…

So we have been talking about seamless upgrade. Following are the operations setup performs in order to ease the upgrade pain. Basically, the whole process of upgrading from BizTalk Server 2004 to BizTalk Server 2006 is divided in four steps:



  1. Checking for the installed pre-requisites required by BizTalk 2006. In case there any of the following is missing we download and install the pre-requisites in the upgrade. The ones that can be downloaded and installed while performing the upgrade are

    1. Microsoft .Net Framework 2.0
    2. Microsoft Data Access Components 2.8
    3. Microsoft SQL XML 3.0 Service Pack 3
    4. Microsoft XML 3.0 Service Pack 7
    5. Microsoft XML 6.0
    6. Microsoft Office Web Components
    7. Microsoft ADO MD.Net 8.0
    8. Microsoft ADO MD.Net 8.0 Patch
    9. Microsoft ADO MD.Net 9.0

  2. Upgrading the BizTalk databases
  3. Uninstalling the BizTalk 2004 and installing the BizTalk Server 2006
  4. Post upgrade configuration to configure the components for BizTalk Server 2006

In case of any unexpected failure while upgrading, we can resume the upgrade from the middle. To consider a scenario, let us say the machine being upgraded goes off the network while upgrading the remote databases. The upgrade can still be resumed from that stage by simply restoring the database that was being upgraded (from its backup) and executing the setup again.


Similarly, in case post upgrade configuration fails because of a similar reason, add a DWORD registry entry RerunUpgrade=1 under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\BizTalk Server\3.0_Migrated. The setup can be executed multiple times even after the BizTalk 2006 installation. This enables us to complete the upgrade successfully in case it fails because of some unprecedented scenario.


 

BizTalk Maps Get Documented

Finally someone has tackled the nasty problem of documenting the maps produced in BizTalk. Steve Hart has published the HTML Generator Stylesheet for BizTalk 2004 Maps, a handy tool to have when attempting to recall exactly what the relationship between this node and those nodes was when you delivered your BizTalk solution 6 months […]