Tutorial 04 01 Implementing Traditional Bridge
Traditional Bridge is a Harmony Core technology that allows you to execute traditional Synergy code (subroutines and functions) during the execution of .NET-based web service endpoints. In some cases, a traditional Synergy routine may provide all the business logic necessary for an entire web service endpoint. But in other cases, the traditional Synergy routine may simply provide supporting functionality, contributing towards some greater functionality.
If you used the harmonydemo solution template to create a fully configured demo solution, that solution will already contain a Traditional Bridge example project named "TraditionalBridge". In that case, you won't be able to follow the steps in this tutorial for that project, though you can still read through this tutorial to understand the code required for a Traditional Bridge implementation.
However, if you followed the steps in Tutorial 2: Building a Service from Scratch, which uses the harmonycore solution template to create a Harmony Core solution, the solution created from that template will not contain Traditional Bridge components. In this case, you can follow the steps in this tutorial to add a sample Traditional Bridge implementation to your solution.
Traditional Bridge is made up of several parts (.NET and traditional Synergy components), many of which are added to your solution when you use the Add Traditional Bridge feature of the Harmony Core GUI tool (which we will do later in this tutorial). This feature adds a traditional Synergy project named TraditionalBridge to your solution, along with the following basic components for a Traditional Bridge implementation:
-
Traditional Synergy library code. This code is primarily concerned with sending and receiving messages via the Dynamic Call Protocol, serializing and deserializing JSON data, and providing helper methods for receiving and returning parameters and return values on the traditional Synergy side of a Traditional Bridge implementation.
-
.NET library code. This code is also primarily concerned with sending and receiving messages via the Dynamic Call Protocol, serializing and deserializing JSON data, and providing helper methods for receiving and returning parameters and return values, but on the .NET side.
-
CodeGen templates. CodeGen templates are used to generate various kinds of content, on both the traditional Synergy and Synergy .NET sides of a Traditional Bridge implementation. Most of these templates are related to xfServerPlus migration, which is what we'll use in this tutorial. But some may be useful when manually creating custom implementations, particularly if complex types (records) are being passed between environments.
Once you've added Traditional Bridge to your solution, you can use the Harmony Core Project Upgrade Tool (discussed in the Updating Traditional Bridge section of this tutorial) to keep the Traditional Bridge components up to date.
There are two ways to implement Traditional Bridge. Depending on your requirements, you may need to use one or a combination of both:
-
xfServerPlus migration. With this method, code for a Traditional Bridge implementation is generated from xfServerPlus methods defined in a Synergy method catalog (SMC). We'll use this method in this tutorial.
-
Custom implementation. For a custom implementation, you supply the code needed for your Traditional Bridge implementation.
In either case, the following must be added to your Harmony Core solution:
-
A Traditional Bridge project with the following:
- Traditional Bridge library code
- Traditional Synergy routines (i.e., the Synergy routines you'll expose as endpoints via Traditional Bridge)
- Dispatcher classes
- A main dispatcher class
- A Traditional Bridge host
- For the .NET side of the implementation, the following need to be added to existing Synergy .NET projects in the Harmony Core solution:
Additionally, you will need to
The first two components listed above (the Traditional Bridge project and Traditional Bridge library code) can be generated automatically by selecting Features > Add Traditional Bridge from the menu of the Harmony Core GUI tool. Dispatcher classes, the Traditional Bridge host, the helper service class, and the controller class are generated automatically if you use xfServerPlus migration, which is what we'll do in this tutorial.
Before you start this tutorial, make sure you have the following:
- Required tools for Harmony Core development
- A Harmony Core solution created by following the steps in Tutorial 2: Building a Service from Scratch
Next topic: Adding a Traditional Bridge Project