Category Archives: ESB

New ESB Toolkit Whitepaper Published

It is written by MVP Jon Flanders. It gives you a good overview of ESB Toolkit and also provides a tutorial.

You can get it here

http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=05bcda1a-c942-4db3-99ac-8fb83e603595

Sending Messages from ESB Toolkit to MSMQ

Sending Messages from ESB Toolkit to MSMQ

Introduction

The BizTalk ESB Toolkit 2.0 is a collection of tools and libraries that extend BizTalk Server 2009 capabilities of supporting a loosely coupled and dynamic messaging architecture. You can learn more about ESB Toolkit 2.0 at http://msdn.microsoft.com/en-us/biztalk/dd876606.aspx. This article will show you how you can use ESB Toolkit to communicate with MSMQ.

ESB Toolkit uses dynamic send ports called Off Ramps to send messages to various BizTalk adapters. It relies on .Net components called Resolvers and Adapter Providers.

Resolvers

For runtime flexibility ESB Services are not hard-coded to specific endpoints or maps. This metadata is determined at runtime. Resolvers can locate and retrieve this metadata. Itineraries define which ESB services execute and in which order. Resolvers define how ESB Services execute. List of Resolvers included in ESB Toolkit 2.0 are shown below.

 

Adapter Providers

Information retrieved by a Resolver is stored in a .Net based Dictionary object. BizTalk isn’t built to work with Dictionary objects. Adapter provider act as a bridge between .Net based ESB components and the BizTalk based components. Here is a list of adapter providers that are included in ESB Toolkit 2.0.

As you can see from the above list MSMQ Adapter provider is not included in ESB Toolkit. This is where WCF-Custom adapter provider comes in handy. WCF-Custom adapter is able to invoke any WCF binding. WCF includes netMsmqBinding which can be used to send messages to MSMQ.

Itinerary

Any message that is sent to the BizTalk Server goes through a series of steps before its processing is complete. In messaging only scenarios a BizTalk receive location might pick up a message and send it to the MessageBox. One or more Send Ports might be subscribed to this message so they will get this message and send it to the destination system. In case of an Orchestration the message will be subscribed by an Orchestration where it may be decomposed, transformed and sent to one of more system. All this can be easily accomplished by BizTalk without ESB Toolkit. However Itineraries provide the runtime flexibility that BizTalk does not have by default. They also provide more flexible Service Composition. Itineraries are designed in the Itinerary designer in Visual Studio. The designer allows you do to design time validation of the itinerary. When the design activity is complete the Itinerary is exported to an Itinerary Repository.

Sending messages to non Transactional MSMQ using WCF-Custom Adapter Provider

  1. Create a private MSMQ queue called test
  2. Start Visual Studio 2008 and create a new project of type Class Library.
  3. Add a new Itinerary to this project.
  4. Set the name of the Itinerary to wcfmsmq
  5. Select the Model Exporter to have a value “Database Itinerary Export”. This will enable export of the itinerary to database.
  6. Set the Itinerary Status to “Deployed”. This is similar to a business rules engine policy deployment where a policy can be in published or deployed status.
  7. Set the Export Mode to “Strict”. This mode captures more details about the itinerary and should be used for any new itinerary. The other mode is called “default” and it is there for backward compatibility with ESB Guidance 1.0 Itineraries.
  8. Set the Encryption Certificate Property if you want to encrypt your itinerary. If you want to disable encryption you can see the instructions here (http://blogs.msdn.com/pkelcey/archive/2009/06/08/disabling-itinerary-encryption-in-the-esb-toolkit-2-0.aspx).
  9. Other values in the properties windows can be left unchanged.
  10. Drag On-Ramp to the design surface.
    1. Update the name property of the OnRamp.
    2. Select “On-Ramp ESB Extender” as the value of Extender
    3. Set the value of BizTalk Application to “Microsoft.Practices.ESB”. This value should be set to the application where OnRamp exists. In this example we are going to use an OnRamp that exists in “Microsoft.Practices.ESB” application.
    4. Select “OnRamp.Itinerary” receive port as the value of Receive Port. This port is a one way receive port.

 

  1. Drag Itinerary Service to the design surface.
    1. Set the name of this service to “RoutingService”
    2. Set the value of Itinerary Service Extender to “Messaging Extender”. This instructs ESB Toolkit to execute this setup in a pipeline.
    3. Set the value of Service Name to be “Microsoft.Practices.ESB.Services.Routing”. This service is a part of the ESB Toolkit. You can create your own messaging services and register them in ESB.Config and they will become available to you in Visual Studio Itinerary Designer.
    4. Set the Container to “OnRamp1->ReceivePort”. This instructs ESB Toolkit to execute the routing service in the pipeline for the Receive Port.
    5. Tracking Enabled property determine if steps of the itinerary will be tracked in BAM.
    6. Right click on the service and add a new Resolver.

  1. Set the name of the resolver to “MsmqTest”
  2. Set the value of Resolver Implementation to “STATIC”. This implies that we will hard code the settings in the itinerary
  3. Set the Transport Name to “WCF-Custom”
  4. Set the Transport Location to “net.msmq://localhost/private/test”. This tells the WCF Custom adapter to use netMsmqBinding of WCF to send message to MSMQ
  5. Set the value of Action to any string. This value is not used in case but its value still needs to be set.
  6. Press the … button for Endpoint Configuration to bring up the configuration dialog box.
    1. Set the BindingType to be “netMsmqBinding”
    2. Set the BindingConfiguration to <binding name=”netMsmqBinding” durable=”false” exactlyOnce=”false”><security mode=”None” /></binding>

      This setting implies that MSMQ message will be not be transactional or recoverable.

 

 

 

 

  1. Right click on the design surface and select “Validate”
  2. If there are no errors you should right click and select “Export” Model
  3. If there are no errors you can use test application C:\Projects\Microsoft.Practices.ESB\Source\Samples\Itinerary\Source\ESB.Itinerary.Test\bin\Debug\ESB.Itinerary.Test.exe
    1. Set the Itinerary Name to be “wcfmsmq”
    2. Set the Version to 1.0
    3. Select the appropriate file in the Load Message section
    4. Press the “Submit Request”
  4. Verify that MSMQ message was written to the Test Queue.

 

Sending messages to Transactional MSMQ using WCF-Custom Adapter Provider

Most of the steps required to accomplish this task are similar to the steps in the previous section.

The only differences are:

  1. Create a new private Transaction MSMQ Queue called “trantest”
  2. When you create a new resolver it should be named “MsmqTranTest”
  3. Transport Location should be “net.msmq://localhost/private/trantest”
  4. Binding Configuration should be set to

<binding name=”netMsmqBinding” durable=”true” exactlyOnce=”true”><security mode=”None” /></binding>

 

Creating Custom Adapter Provider for MSMQ

We can easily extend ESB Toolkit to create a Custom Adapter Provider for MSMQ. The only requirement for this is that the adapter which you are invoking has to support dynamic behavior.

  1. Create a new Class Library project in Visual Studio called “Microsoft.Practices.ESB.Adapter.MSMQ”
  2. Set a reference to C:\Program Files\Microsoft BizTalk ESB Toolkit 2.0\Bin\Microsoft.Practices.ESB.Adapter.dll
  3. Add a strong name key to this project.
  4. Add a new class called “AdapterProvider”
  5. Add a statement using Microsoft.Practices.ESB.Adapter;
  6. Inherit the AdapterProvider class from BaseAdapterProvider class.
  7. Override the properties AdapterName andAdapterContextPropertyNamespace as shown below.

  1. Add a new XML file to the project called MSMQPropertyManifest.xml. This file has to be named in AdapterNamePropertyManifest.xml format. This file contains all the MSMQ Adapter schema properties(http://technet.microsoft.com/en-us/library/aa577593(BTS.10).aspx ). These are the properties that are used by BizTalk to send a message to MSMQ. Partial list of these properties is shown below.
  2. Build the class library and add it to Global Assembly Cache.
  3. Copy the file MSMQPropertyManifest.xml to C:\Program Files\Microsoft BizTalk ESB Toolkit 2.0\Tools\Itinerary Designer
  4. Register the adapter provider in esb.config file by adding the line to the section where other adapter providers have been registered.

<adapterProvider name=”MSMQ” type=”Microsoft.Practices.ESB.Adapter.MSMQ.AdapterProvider, Microsoft.Practices.ESB.Adapter.MSMQ, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d3afc588de1b9f91″ moniker=”MSMQ” adapterAssembly=”Microsoft.BizTalk.Adapter.MSMQ.MsmqAdapterProperties, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35″ />

Here the name is the name of the adapter, Type is the .Net type of custom adapter provider you just created, moniker is Transport Name in the Resolver configuration and adapter assembly is the BizTalk assembly that contains all the context properties related to the MSMQ Adapter.

 

 

 

Testing MSMQ Adapter Provider

Most of the steps required to accomplish this task are similar to the steps in the previous sectiosn.

Non Transactional Queue

The only differences are:

  1. Name of the Itinerary should be ExpressMsmq.
  2. After creating Itinerary Service called RoutingService, you need to add a new Resolver.
  3. Resolver Implementation is still STATIC.
  4. If your MSMQ Adapter provider registered correctly you should be able to select “MSMQ” as the Transport Name.
  5. Set Transport Location to FORMATNAME:DIRECT=OS:ESBWIN2008\PRIVATE$\TEST
  6. You can once again use C:\Projects\Microsoft.Practices.ESB\Source\Samples\Itinerary\Source\ESB.Itinerary.Test\bin\Debug\ESB.Itinerary.Test.exe to test this itinerary.

 

Transactional Queue

The only differences are:

  1. Name of the Itinerary should be TranMsmq.
  2. After creating Itinerary Service called RoutingService, you need to add a new Resolver.
  3. Resolver Implementation is still STATIC.
  4. If your MSMQ Adapter provider registered correctly you should be able to select “MSMQ” as the Transport Name.
  5. Set Transport Location to FORMATNAME:DIRECT=OS:ESBWIN2008\PRIVATE$\TRANTEST
  6. Press the … button for Endpoint Configuration to bring up the configuration dialog box and change the value of Transactional Property to True.
  7. You can once again use C:\Projects\Microsoft.Practices.ESB\Source\Samples\Itinerary\Source\ESB.Itinerary.Test\bin\Debug\ESB.Itinerary.Test.exe to test this itinerary.

 

 

 

 

Conclusion

ESB Toolkit provides Adapter Providers to allow you to communicate with various BizTalk adapters. WCF-Custom adapter offers a lot of flexibility because it can use any WCF binding. For example WCF-Custom can be used to communicate with any of the WCF based adapters that are included in BizTalk Adapter Pack 2.0. When the existing Adapter Providers don’t meet your need you can easily extend ESB Toolkit to create new Adapter Providers. You can download code samples used in this article from my blog at https://rajsinghblog.wordpress.com

BizTalk Annoucements at PDC

We recently announced roadmap for BizTalk Server. You can watch the session here:

http://microsoftpdc.com/Sessions/SVR15

There was also a session on ESB Toolkit 2.0. You can watch it here

http://microsoftpdc.com/Sessions/SVR16

 

 

 

Code samples for ESB Toolkit to MSMQ Post

I have uploaded the code samples I used in “ESB Toolkit to MSMQ Post” to

http://cid-029243050862a734.skydrive.live.com/self.aspx/.Public/CodeSamples/ESBToolkitToMSMQ/Microsoft.Practices.ESB.Adapter.MSMQ.zip

ESB Toolkit Install Hangs

I was setting up yet another VPC image for ESB Toolkit 2.0.  My operating system was Windows 2008 Enterprise. BizTalk Version was 2009 Enterprise and SQL Server was 2008. I configured BizTalk without any problems.

Next I wanted to install BizTalk Adapter Pack 2.0.

While trying to install WCF LOB Adapter SDK that is a requirement for the BizTalk Adapter Pack 2.0 my install would hang with a message:

“Please wait while installer finishes determining your disk space requirements”.

The following blog post has a fix for this issue.

https://blogs.msdn.com/biztalkmusings/archive/2009/09/22/please-wait-while-the-installer-finishes-determining-your-disk-space-requirements.aspx

msiexec.exe -package MyPackage.msi -qr

I installed all the pre-reqs for ESB Toolkit. While doing the ESB core Install I got the same error. I was able to fix it with msiexec command shown above.

I don’t know why this error occurrs but at least we have a work around for it.

Installing ESB Toolkit 2.0 on Win 2003 64 bit OS

For installing ESB Toolkit 2.0 in a single machine 32 bit environment you should look at this link Quick Learn.

I recently installed and configured ESB Toolkit 2.0 on Windows 2003 SP2 64 bit OS. I am sharing my install notes with you so you can benefit from my experience. Use these instructions to install and configure ESB Toolkit in development environment only. Before installing the ESB Toolkit I had already installed and configured BizTalk 2009

  1. Set the trust level of BizTalkServerApplication and BizTalkServerIsolatedHost to “untrusted”. This is needed because all the bindings for ESB Sample expect these hosts to be untrusted.
  2. Run BizTalk ESB Toolkit 2.0-x64.msi
  3. The installer will extract all the files to C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0
  4. Read the Readme file from C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\Readme.htm
  5. Also read Get Started C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\GettingStarted.htm
  6. Read know issues document from  C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\KnownIssues.htm
  7. In addition to this you should read the known issues from http://msdn.microsoft.com/en-us/library/dd897942.aspx
  8. Use the section “Installing the BizTalk ESB Toolkit” section from Microsoft BizTalkESBToolkit.chm file.
  9. Install all the Prerequisites.
  10. Import the C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\Microsoft.Practices.ESB.CORE64.msi in BizTalk Server 2009 Administration Console.
  11. Run c:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\Microsoft.Practices.ESB.CORE64.msi  and accept all defaults
  12. Run C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\Bin\ESBConfigurationTool.exe
  13. Follow the directions in section “Configuring Services and Components” to configure all the databases and services.
  14. This configuration is performed in steps. First you configure the database and then you can configure the corresponding service.
  15. Create c:\projects
  16. Create c:\projects\microsoft.practices.ESB folder
  17. Uncheck the read-only attribute on c:\projects\microsoft.practices.ESB
  18. Extract C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\ESBSource.zip to c:\projects\microsoft.practices.ESB
  19. The previous setup will create keys and source folders. Run Visual Studio Tool Command prompt and change directory to c:\projects\keys. Run the command sn -k Microsoft.Practices.ESB.snk.
  20. Install Management Portal.
    1. Open Windows PowerShell(32) command prompt
    2. Run the command Get-ExecutionPolicy. If the response to this command is not “RemoteSigned” you will need to run Set-ExecutionPolicy RemoteSigned This will allow you install scripts to run.
    3. Navigate to C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\Install\Scripts
    4. Run the command .\Management_Install.ps1 1
    5. Open the solution C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.AlertService\ESB.AlertService.sln in Visual Studio.
    6. Change the configuration type to Release and build the solution.
    7. Run C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.AlertService.Install\Release\Setup.exe
    8. When you are prompted for user name you should enter it in format domain\username  format. Even if you are doing a single computer install you should enter computername\username.
    9. Run UDDI Services Management Console. Right click on UDDI and select Properties. Select Security tab. Uncheck “Require SSL for publication to this site”.
    10. Open the solution C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.UDDI.PublisherService\ ESB.UDDI.PublisherService.sln
    11. Change the build configuration to “Release” and build.
    12. Run C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.UDDI.PublisherService.Install\Release\Setup.exe
    13. Follow the instruction  in section Configuring Exception Management InfoPath Form Template Shares of section “Installing the BizTalk ESB Toolkit” of MicrosoftBizTalkESBToolkit.chm
    14. Follow the Security Considerations section of section “Installing the BizTalk ESB Toolkit” of MicrosoftBizTalkESBToolkit.chm
  21. Install Exception Management Samples
    1. Start the BizTalk Application Microsoft.Practices.ESB.
    2. Edit the file C:\Projects\Microsoft.Practices.ESB\Source\Samples\Exception Handling\Install\Scripts\Setup_bin.cmd. Comment out the line that executes
      REM ./ExceptionHandling_Install.cmd
    3. Run C:\Projects\Microsoft.Practices.ESB\Source\Samples\Exception Handling\Install\Scripts\Setup_bin.cmd
    4. Open Windows PowerShell(32) command prompt(You need this because the install relies on Explorer OM which does not support 64 bit)
    5. Navigate to C:\Projects\Microsoft.Practices.ESB\Source\Samples\Exception Handling\Install\Scripts
    6. Run the command .\ExceptionHandling_Install.ps1 1
    7. This will install the exception handling samples. Now you are all set to run the exception handling samples. You can use similar steps to install other samples.
  22. Create a 32 bit host and change and send and receive handler for SQL Adapter. This is needed because the SQL Adapter cannot run in 64 bit mode.
  23. Enable the web service extension for btshttpreceive.dll
  24. Configure IIS for both Kerberos and NTLM using the instructions http://support.microsoft.com/kb/215383
  25. Install SQLXML 4.0 SP1 from http://blogs.digitaldeposit.net/saravana/post/2009/06/10/ESB-Toolkit-20-MicrosoftDataSqlXml-issue.aspx This is needed by the exception management components to write the expection the the database. Thanks to Saravana Kumar for discovering this issue and posting a fix for it.
  26. Install BAM definitions by executing these commands:

cd C:\Program Files (x86)\Microsoft BizTalk Server 2009\Tracking
Bm.exe deploy-all -DefinitionFile:”C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\Bam\Microsoft.BizTalk.ESB.BAM.Itinerary.xml”
Bm.exe deploy-all -DefinitionFile:”C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.0\Bam\Microsoft.BizTalk.ESB.BAM.Exceptions.xml”