Building, Deploying and Running the Splitter Orchestrations in BizTalk 2004 and BizTalk 2006

Prerequisites:

The following solution should be built on a Development Machine with: 

a) Visual Studio 2003 and BizTalk 2004 SP1 (or greater) installed.
OR:
Visual Studio 2005 and BizTalk 2006 Beta 1 (or greater) installed.

b) A sql server Database will also have to be created on a Sql 2000 or Sql 2005 instance (local or remote).
(This database is needed to run the Sql Helper Splitter Patterns)

A discussion of this sample can be found here:

http://objectsharp.com/blogs/matt/archive/2005/08/31/3209.aspx
______________________________________

1) Unzip the BtsCompareSplitterPatterns.zip file (using folder names) on the root of the c: drive.
A directory structure will be created under C:\BtsCompareSplitterPatterns.

The following directory structure should be created:

C:\BtsCompareSplitterPatterns\Files
C:\BtsCompareSplitterPatterns\SplitterHelper
C:\BtsCompareSplitterPatterns\SplitterTests
C:\BtsCompareSplitterPatterns\Sql
______________________________________

2) Create the Splitter Database, on a Sql 2000 or Sql 2005 instance.

The necessary scripts to create the SplitterHelper database can be found in the below file:
C:\BtsCompareSplitterPatterns\Sql\CreateSplitterHelperDataBase.sql

You can run the above script in Query Analyzer or Sql Server Management Studio as is (while connected to the master database). 
The database, necessary table and stored procedures should be created. 

OR

You can manually create a database called SplitterHelper database beforehand and then just run in the create statements for the 
sql artifacts. These create statements can be found in the:
C:\BtsCompareSplitterPatterns\Sql\CreateTablesAndStoredProcsOnly.Sql file.
Query Analyzer or Sql Server Management Studio (while connected to the SplitterHelper database) can be used to run the above script to create the table and 
stored procedures.

Note: This database could be created with Sql Enterprise Manager or Sql Server Management Studio
a) The name of the database should be called -> SplitterHelper
b) The initial size of the database should be approx 60MB, to handle the insertion of the large XML file.

The artifacts to be created are in CreateTablesAndStoredProcsOnly.Sql as below: 

CREATE TABLE [dbo].[InsertNewProductionOrders] 
Create Procedure GetSplitProductionOrderMessage
Create Procedure InsertProductionOrders

______________________________________

3) For both a BTS 2004 or BTS 2006 installation edit the BTSDeploy.exe.config 
file.

For BTS 2004, (if the install folder is C:\Program Files\Microsoft BizTalk Server 2004) 
the file will be found as below:

C:\Program Files\Microsoft BizTalk Server 2004\BTSNTSvc.exe.config

For BTS 2006, (if the install folder is C:\Program Files\Microsoft BizTalk Server 2006)
the file will be found as below:

C:\Program Files\Microsoft BizTalk Server 2006\BTSNTSvc.exe.config

In both cases, make a copy of this file for a backup, and then edit the BTSNTSvc.exe.config file in 
notepad or some other editor. 

Add the following to the BTSNTSvc.exe.config file.

<appSettings>
	<add key="SqlConnectStringForSplitterDB" value= "packet size=12288;user id=sa;data source=redlake;persist security info=True;initial catalog=SplitterHelper;password=sa;Connection Timeout = 10"/>
        <add key="SendSplitMessage" value= "0"/>	
</appSettings>	

Note: A sample of this file can be found in -> C:\BtsCompareSplitterPatterns\BTSNTSvc.exe.config

Note: Modify the SqlConnectStringForSplitterDB key, for your specific connection to the SplitterHelper
database that was created in Step 2)
Note: If using a Sql Login, modify the connection string as above and: 
a) replace -> redlake, with the name of your Sql instance (most likely the name of the machine the Sql Server instance is installed on).
b) replace -> the user id and password attributes with the correct Sql Login and Password. 

Note: If using Integrated security with the SplitterHelper database and the BizTalk Host Instance Windows login has the correct 
rights to the  SplitterHelper database, the login will look as below:

<add key="SqlConnectStringForSplitterDB" value= "packet size=12288;integrated security=SSPI;data source=redlake;persist security info=False;initial catalog=SplitterHelper;Connection Timeout = 10"/>

a) replace -> redlake, with the name of your Sql instance (most likely the name of the machine the Sql Server instance is installed on).

Note for configuration value SendSplitMessage: 
if SendSplitMessage" value= "0" -> No split messages are sent out from the Splitter Orchestrations.
if SendSplitMessage" value= "1" -> Split messages are sent out to folder :
C:\BtsCompareSplitterPatterns\Files\SendSplitMessages 

Note: When changing the BTSNTSvc.exe.config file, for the new settings to be picked up, you must restart the BizTalk Host Instance 
in the Services window or in the BizTalk Administration Console (BTS 2004), or the BizTalk Administration Console (BTS 2006).

______________________________________

4) Open the BizTalk Solution in VS2003 or VS2005

Open the C:\BtsCompareSplitterPatterns\CompareSplitterPatterns.sln in VS2003 or VS2005

Note: When opening up in VS2005, a Dialog will appear to convert the solution.
Just click through the wizard to convert the solution. 

_______________________________________

5) Check for a Reference.

Add the following references to the BizTalk project -> BTSSplitterTests

With the Solution opened in VS2003 or VS2005, add the following reference to the project BTSSplitterTests (Note: only add if missing):
Microsoft.XLANGs.RuntimeTypes

This reference can be found under the .Net tab of the Add References dialog
Note: If you do not see this assembly in the .Net Tab, add the reference by browsing to the folder:

For BizTalk 2006:

C:\Program Files\Microsoft BizTalk Server 2006

For BizTalk 2004 :

C:\Program Files\Microsoft BizTalk Server 2004

And then choose file: Microsoft.XLANGs.RuntimeTypes.dll


(Note: You may have to remove the old one with a yellow caution sign, before adding the new one).
(Note: This reference is to retrieve the Orchestration Instance Id in the orchestrations, as below):

varGuidOrchestrationInstanceID = Microsoft.XLANGs.Core.Service.RootService.InstanceId;

_______________________________________

6) In VS2003 or VS2005 Build and GAC the SplitterHelper C# component. You can use the Gacutil using the visual studio 
command prompt or an easy way to Gac is to drag the :

C:\BtsCompareSplitterPatterns\SplitterHelper\bin\Debug\SplitterHelper.dll 

to the:

C:\WINDOWS\assembly folder. 


_______________________________________

7) Deploy the BizTalk BTSSplitterTests project 

In VS2003 or VS2005 Deploy the BTSSplitterTests BizTalk project.

_______________________________________


8) If you will be running the SplitterHelper Database on a remote machine please review the 
following to avoid Distributed Transaction Errors:

For windows XP:

http://codebetter.com/blogs/jeff.lynch/archive/2005/04/15/23022.aspx


For Windows 2003 and Windows XP:

http://geekswithblogs.com/sthomas/archive/2005/06/21/44361.aspx

Additionally using Windows 2003 please ensure that have:

Enabled Network DTC Access:

http://www.microsoft.com/technet/prodtechnol/windowsserver2003/library/ServerHelp/e603c463-0636-4b85-8ada-c2b99f8555ac.mspx

_______________________________________


9) Import the Binding file to create the correct physical ports and bind the logical ports in the 
orchestrations to the physical ports.

First edit the below file in notepad or some other editor:

C:\BtsCompareSplitterPatterns\SplitterBindings.xml

In this file find the string:

Provider=SQLOLEDB.1;Password=***************;Persist Security Info=True;User ID=sa;Initial Catalog=SplitterHelper;Data Source=redlake

Replace this string with the connection to your splitter database.
Edit for the proper Password, User ID and Data Source

Note: If integrated security is being used, the below sample string must be edited and used as below:

Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False;Initial Catalog=SplitterHelper;Data Source=redlake

Also in this file find the string 

<Address>SQL://redlake/SplitterHelper/</Address>

Replace redlake with the name of you Sql Instance that is hosting the Splitter Database (Same as the edited Data Source as above).

For BTS 2004 -> Use the BizTalk Deployment Wizard to deploy the edited SplitterBindings.xml. Choose the 
Import BizTalk Assembly Binding From File radio button choice and supply the:
C:\BtsCompareSplitterPatterns\SplitterBindings.xml file to create the necessary receive 
ports and to bind the orchestration logical ports to the these physical ports.

For BTS2006 -> Open up the BizTalk Administration Console. Navigate to the Default Application (Probably called BizTalk Application 1)
Right mouse button on the application node and choose Import -> Bindings. Choose the edited SplitterBindings.xml



_______________________________________

10) Get DebugView

Download the free utility DebugView from the link below:

http://www.sysinternals.com/utilities/debugview.html

This utility can be used to capture the output from the Writeline 
statements in the orchestrations and .Net helper code.

_______________________________________

11) Five Orchestrations are deployed :

BTSSplitterTests.orcCommonTypes
BTSSplitterTests.orcSplitterUsingMap
BTSSplitterTests.orcSplitterUsingMap_Singleton
BTSSplitterTests.orcSplitterUsingSQL
BTSSplitterTests.orcSplitterUsingSQL_Singleton

BTSSplitterTests.orcCommonTypes only contains types that the other 
orchestrations use and does not have to be enlisted or started.

To test, only enlist and start only one of the Splitter Orchestrations 
at a time. Ensure that all the necessary receive ports and send ports are started:

BTSCompareSplittersReceiveProductionOrders    (File Receive)
BTSCompareSplittersGetSplitMessage	      (Sql Send , Solicit-Response)
BTSCompareSplittersSendSplitMessage	      (File Send)	
BTSCompareSplittersSendUnconsumedMessage      (File send)	


To start off, copy and paste file:

C:\BtsCompareSplitterPatterns\Files\ProductionOrdersSmall.xml 

Into folder:

C:\BtsCompareSplitterPatterns\Files\ReceiveProductionOrderMessage

Split messages should then show up in:

C:\BtsCompareSplitterPatterns\Files\SendSplitMessages

Note: Split messages will only be sent out if the
SendSplitMessage" value= "1" in the BTSNTSvc.exe.config file.

Once the ProductionOrdersSmall.xml was processed properly with Split messages 
produced, then try the larger message :

C:\BtsCompareSplitterPatterns\Files\ProductionOrdersBig.xml

_______________________________________

12) To test that undelivered and unconsumed messages are processed properly

Edit the BTSNTSvc.exe.config config file and edit the key to force an error:
<add key="SqlConnectStringForSplitterDB" value 

To force an error, place in an non existent sql server instance in the data source=
setting of the connection string.

Restart the BizTalk host instance. 

Enslist and Start the BTSSplitterTests.orcSplitterUsingSQL_Singleton orchestration.

Make a few copies of file :

C:\BtsCompareSplitterPatterns\Files\ProductionOrdersSmall.xml 

Drop the ProductionOrdersSmall.xml and the copies of this file into the folder:

C:\BtsCompareSplitterPatterns\Files\ReceiveProductionOrderMessage

The delivered but unconsumed messages should show up in this folder:

C:\BtsCompareSplitterPatterns\Files\SendDeliveredButUnconsumedMessages