Tutorial 04 01 Implementing Traditional Bridge

Tutorial 4: 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 (a "TraditionalBridge" project). 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 solution.

But 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 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 Components

Traditional Bridge is made up of several parts (.NET and traditional Synergy), 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 useful helper methods for receiving and returning parameters and return values on the traditional Synergy side of a Traditional Bridge implementation.

  • https://github.com/Synergex/HarmonyCore/tree/master/TraditionalBridge

• .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 useful helper methods for receiving and returning parameters and return values, but on the .NET side.

• CodeGen templates. Various CodeGen templates are used to generate various kinds of useful content, on both the traditional Synergy side and the Synergy .NET side. Most of these templates are related to xfServerPlus migration, which is what we'll use in this tutorial (as discussed below). But some may be useful when manually creating custom solutions, particularly if complex types (records) are being passed between environments.

  • https://github.com/Synergex/HarmonyCore/tree/master/Templates/TraditionalBridge
  • https://github.com/Synergex/HarmonyCore/tree/master/Templates/SignalR

And note that once you've added Traditional Bridge to your solution, you can use the Harmony Core Project Upgrade Tool (discussed in Updating Traditional Bridge) to keep the Traditional Bridge components up to date.

Implementing Traditional Bridge

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 code implementation is generated from xfServerPlus methods defined in a Synergy method catalog (SMC).

• Custom implementation. With this method, you supply the code needed to access your traditional Synergy routines via Traditional Bridge.

In either case, the following must be added to your Harmony Core solution:

• A Traditional Bridge project with the following:
  • Traditional Bridge library code (these are added by the Add Traditional Bridge feature in the Harmony Core GUI tool)
  • Traditional Synergy routines
  • Dispatcher classes
  • A main dispatcher class
  • A Traditional Bridge host
• For the .NET side of the implementation, the following will need to be added to existing Synergy .NET projects in the Harmony Core solution:
  • A helper service class
  • A controller class Additionally, you will need to
• configure the Traditional Bridge environment.
• test Traditional Bridge.

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. The dispatcher classes, Traditional Bridge host, helper service class and controller class can be generated automatically if you use xfServerPlus migration, which is what we'll do in this tutorial.

Before You Start...

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: Add Traditional Bridge Project

---