(For more resources related to this topic, see here.)
Creating a Bridge
In WABS, a bridge is used for transporting a message from one place to another. Unlike BizTalk Server, a message entering a bridge will always be routed to one destination only.
All bridges have an HTTPS entry point. Additional entry points, such as FTP and SFTP, can be added.
The following is a list of what can happen in a bridge:
- Receiving a message (message format could be XML, Flat File, or any custom format such as JSON, since custom Message Inspectors can be created). Message Inspectors are not covered in this article, but several examples can be found on the Internet. Refer to the following link on how to include custom code in bridges: http://msdn.microsoft.com/en-us/library/windowsazure/dn232389.aspx
- Decode the message to XML (from Flat File or custom formats).
- Validate the message with the Schemas specified in the bridge.
- Enrich the message by writing metadata to the message (similar to Property Promotion in BizTalk Server).
- Transform the message using Maps.
- Encode the message from XML to the target format (Flat File or custom format).
A bridge can also send messages to another bridge for further processing. A bridge will always act as one whole step, meaning that if a bridge cannot submit to its destination, the message will not be removed from the source.
Let us create a very simple bridge that picks up a text message from an FTP folder and drops the file in another FTP location.
For this example you will need an FTP site and three folders:
- In: This is used for submitting files to the bridge
- Out: This is used for dropping files from the bridge
- AltOut: This is used as an alternative file drop from the bridge
Also, a username that has full access to these folders and a corresponding password will be required.
- Open Visual Studio, create a new project, and choose Visual C# | BizTalk Services | BizTalk Service.
- Choose the Location C:\BTS2013CertGuide\Chapter09\Projects, name the Solution Chapter09.Example01, and name the Project Chapter09. Example01.SimpleBridge.
- Click on OK.
- You should now have a project with a blank canvas where a text reads Drag a bridge to this diagram…, and a toolbox that resembles the following screenshot:
- Drag a Pass-Through Bridge from the toolbox to the empty canvas.
- Check the Properties for the created bridge and notice that the default Entity Name and Relative Address have been given the name PassThroughBridge1.
- Change both names to MySimpleBridge.
- We now need to create an FTP source so that the bridge will automatically pick up messages, whenever they are submitted from this source. In the toolbox, choose Sources | FTP Source and drag it onto the canvas to the left of your bridge.
- Once dragged onto the canvas, notice that the source has a yellow exclamation mark, indicating that the source needs to be connected to a bridge. To do this, choose Bridges | Connector in the toolbox.
- The connector is not used by dragging it to the canvas, but rather just selecting it and then dragging and connecting from the FTP Source to the bridge. You need to be precise when doing this, connecting from the red dot to the other red dot, as shown in the following screenshot:
- Rename the FTPSource1 by selecting it, and change FTPSource1 to MySimpleFTPPickup under Properties | Entity Name.
- We now need to configure the FTP Source; select the source and configure the following properties.
[The FTP User's password]
[The FTP Server address]
[The FTP Username]
- Your FTP Source properties should now look somewhat similar to this:
Note that the Initial Status is by default Start, which will have the source polling from the FTP folder as soon as the project is deployed. To gain better control of when the polling starts, we will set it to Stop instead and then manually start it using a PowerShell command.
- In the toolbox, choose Destinations | FTP Destination and drag it onto the canvas on the right side of the bridge.
- Connect the bridge to the destination.
- Change the name of the FTP Destination from FTPDestination1 to MySimpleMainFTPDest.
- Set the appropriate properties, making it point to the Out folder; with a few variations your properties should resemble the following:
As of now, the only place we can configure the FTP properties are in Visual Studio. In the future, other configuration options in the Azure Portal might be possible. This also means that, for now, if a password changes, you will need to change this in the Visual Studio project, and then redeploy the project.
- Try building your project. You should receive a warning about the FTP destination name not being set and two errors stating something about filter conditions. Let's fix these issues.
Filter Condition and Route Ordering
A bridge can have from one to many destinations. Unlike a publish-subscribe engine, the message will only be routed to one of these destinations. This is done by setting a filter condition on each connection to the destinations and then prioritizing the destinations in the bridge's Route Ordering Table property.
All destination connections need a filter condition (which is also the reason we received the two errors before), and a bridge will always have each of its destinations in a prioritized Route Ordering Table.
When a message leaves the bridge, the filter condition for the destination connections will be evaluated in the order they appear in the Route Ordering Table. The first positive match will get the message, and the algorithm will stop, so that no more than one destination will get the message.
In our rather simple example from before, all we have is one destination, and we naturally want all messages to evaluate to that destination's Filter Condition.
- Select the connection from the bridge to the FTP destination and locate the Filter Condition property.
- Click on the ellipsis of the Filter Condition property, and click on the Match All radio button.
- Click on OK. Notice that the Filter Condition now reads 1 = 1, which will naturally always evaluate to true!
Setting the FTP filename
We are now left with a single warning message when building the project:
FTP Filename property needs to be specified at the Route Action stage
Although this is only a warning and the project will build and deploy, the solution would not work since the FTP destination will not have any name to assign to the file it is writing to the Out folder.
For now, we will just hardcode the output.txt filename. Later, we will change the solution so that the original filename is used, by using the Enrich feature in the bridge.
To set the FTP filename used by the FTP destination, we need to create a Route Action on the connection to the destination, by using the following steps:
- Select the connection from the bridge to the FTP destination and locate the Route Action property.
- Click on the ellipsis, and then click on Add.
- In Property (Read From), select Expression and type 'output.txt'. Notice that single quotes are needed around the name.
- In Property (Write To), choose Ftp and FileName.
- Click on OK twice.
- Build the project again, and verify that we are left with no warnings.
Deploying a Bridge
To deploy a project to the BizTalk Service in Azure, we need the following:
- The name of the BizTalk Service
- The name of the Access Control Namespace gathered earlier
- The Default Issuer
- The Default Key
To deploy, perform the following steps:
- Click somewhere on an empty space on the canvas where the bridge, FTP source, and destination reside.
- Under Properties, locate the BizTalk Service URL.
- Replace servicename with the name of your BizTalk Service.
- Right-click on the project and click on Deploy.
- In Acs Namespace, type the namespace of the Acs.
- Set Shared Secret to the token fetched previously from the Azure Portal.
- Leave the Refresh server after…checkbox unchecked, as we will refresh the service manually from PowerShell if needed.
- Click on Deploy.
- Confirm that two items were successfully deployed (the bridge and the source).
Now we need to verify that the bridge and the source have been deployed in the WABS, and then start the source so that it will commence picking up files from the In FTP folder.
This article has dealt with some of the basics of BizTalk Server and BizTalk Services in Azure. We have seen how to create accounts and Servers in Azure, how to use them, how to set up an EDI agreement for exchanging messages with partners in the cloud, and even how to route messages from Azure to your local on-premise applications.
Resources for Article:
- Microsoft Biztalk server 2010 patterns: Operating Biztalk [Article]
- Microsoft DAC 2012 [Article]
- Setting up a BizTalk Server Environment [Article]