Hello world on ESB Toolkit

What is ESB Toolkit and why is it interesting?

ESB Toolkit is a toolkit for BizTalk server that allows you to simplify the development of integration applications.
Despite the fact that it is a powerful tool that allows you to create serious products, the first thing it impresses is the low “threshold of entry” into the development topic for BizTalk. Many tasks that are difficult to solve with orchestrations can be easily solved using the ESB Toolkit.
Microsoft has created excellent documentation that provides examples of how to solve many common problems. But in my example, I realized that this documentation becomes useful when a general idea of ​​working with this tool has appeared. Apparently, the conditioned reflex of a lazy programmer works — not to read the documentation until something working has been done, or a lot of time has been wasted.
Actually the main purpose of this post is to create a simple application so that you can “touch” the ESB Toolkit. Those familiar with BizTalk probably read an example of transferring files from one folder to another using a filter on SendPort. In this post, the example is repeated using static routing in the ESB Toolkit.

Preconditions

For the development will be used BizTalk Server 2010 and Visual Studio 2010.
Before development, you need to install ESB Toolkit and its components for Visual Studio. Installation is described on the Microsoft website, the link is given at the end of the post.

Training

First, we will prepare a new application in which we will use it during development.

')
Let's call the application EsbToolkitTest.


In References, you must add a link to the application Microsoft.Practices.ESB.


In the created application, create the Receive Port and add the Receive Location to it.




We configure the Receive Location to take files from the folder. For example, C: \ ESB \ input.


One should not forget that the BizTalk user should have read and write permissions to this folder. Or configure access on behalf of another user in the Authentication tab.

It is also necessary to create a dynamic SendPort.



Set the following parameters in the Send Port filter:


These parameters will allow our port to receive a message from Itinerary. Please note that the ServiceName here is arbitrary.
Everything, preparation is finished, it is possible to create Itinerary.

Creating Itinerary

Routes (Itinerary) is the main component of the ESB Toolkit. With their help, we determine what will happen with our message. After installing components, you can create routes in many types of projects. In this example, we will create a route in the Itinerary project.
So, in Visual Studio create a new project. On the BizTalk Projects tab, we should have a BizTalk ESB Itinerary Designer project. Let's call our route TestItinerary.


If you do not have such a project template, you need to install it from the folder with the ESB Toolkit. My template is located in the folder C: \ Program Files \ Microsoft BizTalk ESB Toolkit 2.1 \ Tools \ Itinerary Designer. The template is installed by running the Microsoft.Practices.Services.Itinerary.DslPackage.vsix file, then it appears in Visual Studio.

The TestItinerary.ititnerary route should already be added to the created project. Double click to open Itinerary Designer. Naturally, there are no components there now, and it makes us happy with an empty gradient.
The toolbox on the left shows us a list of available components.


In this example, OnRamp, OffRamp, Itinerary Service and, of course, Connector will be useful to us.
On-Ramp is our data source and container for services.
Itinerary Service - here will be our routing logic.
Off-Ramp is our transmitting component. It will need to be tied to the Send Port. Pay attention - the port must be dynamic, because The real address is resolved within the route.

So, we transfer one On-Ramp, two Itinerary Service, one Off-Ramp to the Itinerary Designer area and connect them with connectors as shown in the figure.


To connect two components with a connector, you must first click on the connector in the Toolbox, then click on the first component, then click on the second. Active users of graphic editors sometimes have a hitch here, because they are trying to pull the connector from the first component to the second. Trifle, but can deliver a couple of unpleasant minutes.

Now we need to configure each of the components and the itinerary itself. Select the OnRamp1 component and set the following properties for it:


Those. we specify from which Receive Port of which application you need to receive data, rename the component to TestOnRamp and specify the Extender. Why choose an Extender for On-Ramp every time, if only one “On-Ramp ESB Extender” is available for it is not clear. Apparently, in some situations there may be some other options, but I have not come across this.

Note that until you select the Extender, some properties will not appear.
Advice on setting the properties of components - specify the properties that you see at the moment, and do not pay attention to the fact that some do not exist yet - they will appear during the filling process. This is due to the fact that in the properties you often have to specify the type of the component, and different types have different sets of properties.

After On-Ramp, go to ItineraryService1. We give it the following properties:


Those. the container for this service will be our on-ramp, the Extender will be the Messaging Extender. In the Service Name, specify Microsoft.Practices.ESB.Services.Routing - this service will be responsible for routing. And rename the component to “Routing”.

In addition to defining properties, we need to add a resolver to the routing service. In our case, it will resolve the address. Resolver will be static - its properties will be hard coded and will not dynamically change.
So, right click on our Routing service and select Add-> Resolver


If you call the context menu not of the entire component, but of its specific resolver, the following menu will appear:


The highlighted item here is similar to the previous one and there is no difference between them.
Let's call our resolver staticResolver and give it the following properties:


I remind you that the BizTalk user must have write access to the folder specified in Transport Location. A static resolver allows you to set the properties of SendPort in some detail, but for example, we only need the transport type and destination address.
Everything, we defined properties of service of routing. Go to the component Off-Ramp. Component ItineraryService2 while skipping.
For the Off-Ramp component, we set the following properties:


Those. we tied our Off-Ramp to the previously created Send port. Off-Ramp we also gave a more harmonious name: “TestOffRamp”.
Now go to the ItineraryService2 component. This component will play the role of Off-Ramp service. We give it the following properties:


Those. we indicated that this is an Off-Ramp service for TestOffRamp, and renamed it.
Everything, we have configured all the components, and our Itinirary Designer should look like this:


It remains to set the properties of the Itinerary itself. To do this, click on the place free from the components and press F4. We set the following properties:


Let us examine in more detail the properties that we changed:
1. Model Exporter - we specified the Database Itinerary Exporter, i.e. Our route will not be exported to XML, but immediately to the database, from where it will take BizTalk.
2. Require Encryption Certificate - False, because we do not need it now.
3. Itinerary Status - Deployed. If you leave the route Published, it will be in the database, but will not be available. Those. BizTalk cannot call it.
You also need to pay attention to the Name property - this is the name of our route by which it should be searched. Copy it to the clipboard - it is useful to us now.
Save the created route, then right-click the component-free spot and select the “Export model” item. Now our route has been exported to the database and is available for calling from BizTalk.

Configure the Receive Port

Once again, go to the BizTalk Server Administration Console and open the properties of the Receive Location we created. We did not change the pipeline and it remained PassThruReceive. It's time to change it and customize the selection of our Itinerary.
Select the ItinerarySelectReceivePassthrough pipeline and open its properties.
In the Stage 1: Decode - Component: ESB Itinerary Selector section, you must specify the properties to select the Itinerary.
In ItineraryFactKey, specify Resolver.Itinerary, and in ResolverConnectionString, specify ITINERARY: \\ name = TestItinerary;


The Name parameter sets the name of our route. Now we used a static route selection, but we can also use dynamic, for example, based on business rules.

Start, finish and conclusions

Run the application in the BizTalk Server Administration Console.
In the folder C: \ ESB create a test document. For example, such:
<?xml version="1.0" encoding="utf-8"?>
Hello world


Copy the document into the folder C: \ ESB \ input and see how it appears in the folder C: \ ESB \ output.
Everything, our application fulfilled, it is possible to rejoice.
The first conclusion that comes to mind from this example, the ESB Toolkit, is something cumbersome and the same result can be achieved much easier. But it is necessary to take into account - everything that we asked here statically can be determined dynamically. Those. only by slightly complicating the task, we get dynamic content-based routing and transformation. And even the choice of the route can be dynamic. If this topic is interesting, then in the next post I will give an example of a dynamic solution based on business rules.

The main link

I wanted to call “Useful links”, but I realized that only one would be useful:
Microsoft ESB Toolkit
Here you can find all the most important things about the ESB Toolkit, it says what it is, links to the documentation and to downloading the toolkit are given. By the way, I recommend downloading a poster - a very useful and visual thing. Resource in English. Unfortunately, I could not find a Russian equivalent.