Tutorial 04 02 Add Traditional Bridge Project

Tutorial 4: Adding a Traditional Bridge Project

Adding Traditional Bridge to an existing solution typically involves adding a new traditional Synergy project with the traditional Synergy routines you want to expose via endpoints, dispatchers, model classes and other components needed to create the endpoints, and a simple console application (DBR) that we refer to as the "Traditional Bridge host program". This is the kind of project we'll create in this tutorial. Note, however, that you can organize and deploy some of this code via additional ELB projects. It really depends on how complex your environment is.

For this tutorial, the Traditional Bridge host program will

• listen for request messages from Harmony Core, sent via standard in (TT:).
• decode requests to determine which routine is to be called and to determine values for any inbound parameters.
• execute subroutines and functions as directed, passing needed parameters.
• construct a response message based on the return values and the value of any out parameters.
• send the response back to Harmony Core via standard out (TT:).

The format of the request and response messages is defined by a standard protocol called JSON RPC 2.0. This mechanism is described in more detail in the Dynamic Call Protocol topic.

In this tutorial, the Traditional Bridge environment will be implemented on Windows and in the same solution as the Harmony Core services. But keep in mind that this is not a requirement. Traditional Bridge code can be built and run on Windows, UNIX, Linux, or OpenVMS.

Add a Basic TraditionalBridge Project

1. Open a Windows command prompt and navigate to the directory with the .sln file for your Harmony Core solution.

2. Enter the following command to open the Harmony Core GUI tool:

   harmonycore gui
   

   A message will briefly display indicating that the solution is being loaded.

3. When the "Loading solution" message disappears, select Features > Add Traditional Bridge from the menu. (Do not select the Add Traditional Bridge and SMC menu entry. We'll specify an SMC and set up xfServerPlus migration in a subsequent step.)

   A message will briefly display, indicating that Traditional Bridge is being added to the solution.

4. Open your Harmony Core solution in Visual Studio and open Solution Explorer (if it's not already open). Notice that there is now a TraditionalBridge project with subfolders:

   

   Also notice that Source > Bridge has a number of files. These files contain the Traditional Bridge library code, which is pre-written helper code to help with JSON data, JSON-RPC messages, and more.

   

   Unless you have changed the .NET projects in your Harmony Core solution since you followed the steps in Building a Service from Scratch, these projects will be set build for Any CPU by default. However, the TraditionalBridge project that you just added defaults to being built for x86 (32-bit). We'll make sure the environment builds the code for x64 (64-bit):

5. In Solution Explorer, right-click on the solution and select Configuration Manager. The Configuration Manager will open:

   

6. Make sure the TraditionalBridge Platform is set to x64 and the checkbox in the Build column is selected.

7. Change the Active solution configuration to Release, then once again make sure the TraditionalBridge Platform is set to x64 and the checkbox in the Build column is selected.

8. Click the Close button to save your changes and close the dialog.

Your solution now has the basic scaffolding for Traditional Bridge.

Specify an SMC and Enable xfServerPlus Migration

Next, we'll set up xfServerPlus migration, which generates Traditional Bridge components from interface definitions in a Synergy method catalog (SMC).

We'll start by creating a sample SMC (with an interface that defines three methods):

9. In Solution Explorer, right-click the MethodCatalog folder (in the TraditionalBridge project) and select Add > Class. Then in the Add New Item dialog, select XML File, name the file MethodDefinitions.xml, and click Add. This will create a MethodDefinitions.xml file in the MethodCatalog folder.

10. Copy the following code and paste it into the file you just made, replacing the default code for the file.

 <?xml version='1.0'?>
 <component name="MethodDefinitions" repository="D:\HarmonyCoreProjectTemplates\ProjectTemplates\dotnet-new-harmonydemo-synergy\Repository\bin\Debug" smc="D:\HarmonyCoreProjectTemplates\ProjectTemplates\dotnet-new-harmonydemo-synergy\TraditionalBridge\MethodCatalog" smcrev="5">
   <interface name="BridgeMethods">
      <method name="AddTwoNumbers" id="AddTwoNumbers" routine="AddTwoNumbers" elb="EXE:BridgeMethods">
         <comment>
            <line1>Add two numbers</line1>
         </comment>
         <param name="number1" type="decimal" size="28" precision="10">
            <comment>
               <line1>First number</line1>
            </comment>
         </param>
         <param name="number2" type="decimal" size="28" precision="2">
            <comment>
               <line1>Second number</line1>
            </comment>
         </param>
         <param name="result" type="decimal" size="28" precision="10" dir="out">
            <comment>
               <line1>Resulting number</line1>
            </comment>
         </param>
      </method>
      <method name="GetEnvironment" id="GetEnvironment" routine="GetEnvironment" elb="EXE:BridgeMethods">
         <comment>
            <line1>Get environment string</line1>
         </comment>
         <methodresult type="string" size="0">
            <comment>
               <line1>Returned environment string</line1>
            </comment>
         </methodresult>
      </method>
      <method name="GetLogicalName" id="GetLogicalName" routine="GetLogicalName" elb="EXE:BridgeMethods">
         <comment>
            <line1>Get a logical names value</line1>
         </comment>
         <methodresult type="string" size="0"/>
         <param name="aLogicalName" type="string" size="0">
            <comment>
               <line1>Logical name</line1>
            </comment>
         </param>
      </method>
   </interface>
</component>

11. Save the file.

12. In the Harmony Core GUI tool, select Features > Enable SMC Import from the menu.

13. In the "Load SMC" dialog, navigate to the MethodCatalog folder (i.e., in the lower pane of the dialog, double-click /TraditionalBridge, and then double-click /MethodCatalog). Then select the SMC you just created (MethodDefinitions.xml) and click Open.

14. A message will be displayed, indicating that the SMC has been selected. Click OK to close the message. Then select File > Quit from the menu to close the Harmony Core GUI tool.

---

Next topic: Updating Traditional Bridge

---