Preparing Existing Code for Synergy .NET

In addition to using Synergy DBL to create entirely new applications for Microsoft .NET Framework (on Windows) or Mono (on Android, iOS, or Linux), you may also be able to use existing traditional Synergy code to create .NET applications.

Whether you are planning to migrate an entire application, port frequently used functionality, or simply make some Synergy routines available to other .NET programs, you can begin with an existing traditional Synergy solution.

The following steps outline the basic procedure for a typical application. This is an iterative process; you start with global entities, move to common code, and then work up to code that’s specific to certain functionality. The goal is to organize code into useful projects and avoid circular dependencies and forward references, which are not allowed in DLLs (see step 7), while making code compatible with .NET.

Unlike traditional Synergy,

To prepare existing traditional Synergy code for .NET,

1. Start by creating a Synergy class library project as a new solution (i.e., create the project when no solution is open in Visual Studio). Select File > New Project from the Visual Studio menu, and then select a class library project template (under Installed Templates > Synergy/DE in the New Project window).

For more information on project templates, see Synergy/DE project templates, and note that for portability, put as much logic as possible in portable class libraries. Portable class libraries can target some or all supported platforms (Microsoft .NET Framework on Windows and Mono on Android, iOS, and Linux).

2. Once you’ve selected a template, specify a name, location, etc., for the project, and click OK to create it.
3. In the .dbl file for the project, create a subroutine and add all global entities for your application into the subroutine:
4. Set project properties as necessary. See Synergy/DE project properties.
5. Build the project. If you get errors, it is probably because the code includes something that is not supported in the .NET environment. (By double‑clicking an error message in the Visual Studio Error List, you can go directly to the line of code that is causing the error.) Analyze the code causing the problem, and ask yourself the following questions:

Don’t be alarmed if your initial compilations result in a number of errors and warnings. Most of the errors and warnings will involve only minor fixes, and solving one will most likely also resolve several others. Also keep in mind that many of these issues would result in runtime failures—and they may already be causing runtime errors in your current application.

See Feature Support for information on Synergy features that are not supported in Synergy .NET.

6. Repeat the process (step 1 through step 5) for your application’s core routines, and add a project reference to the project for global structures, commons, etc.
7. Repeat the process again, but for sets of routines that are specific to certain areas of your application, and this time add project references to the project for core routines and the project for globals. For example, if your application has general ledger (GL) functionality and order entry functionality, you could create a class library project for the GL routines and another class library project for the order entry routines, making sure they reference existing projects:

1. Create class libraries for routines specific to certain areas of your application.

Create class libraries for routines specific to certain areas of your application

With Synergy .NET, only forward references are supported (i.e., circular references are not allowed). For example, if you have core routines and order entry routines in separate projects and the order entry routines call the core routines, the core routines cannot reference anything in the order entry routines. There is an exception: you can use XSUBR for a “backward reference” if necessary, but this can adversely affect performance.

2. Use only forward references with Synergy .NET (unless you use XSUBR).

Use only forward references with Synergy .NET

8. Create projects for the routines that make up the programs that call the routine libraries and add project references to those libraries. These programs will be executable assemblies, so create application projects for these programs. Then repeat the process described in step 5 for these projects.

3. Create application projects for programs that call libraries.

Create application projects for programs that call libraries
9. Once compile errors have been corrected for the assemblies, you should be able to run and debug the application.

Converting xfServerPlus routines for native .NET access

If you use xfNetLink .NET to access Synergy routines, you can access these routines natively in Microsoft .NET Framework on Windows by generating an assembly for the Synergy routines and then accessing that assembly (rather than the assembly generated by gencs). Once you make this change to your application, it will no longer be a distributed application that accesses Synergy routines remotely. Rather, those routines will be built into a DLL, which will be referenced locally by the .NET application (the application that was the xfNetLink .NET client). Neither xfNetLink nor xfServerPlus will be involved.

This conversion can be of benefit if your xfNetLink client application is a Windows application (e.g., written in C# or VB.NET). It should improve performance and enable you to use seamless in‑process debugging from your client code through to the Synergy .NET code. It should also help you prepare for future .NET development. For a web application, you can either continue to access Synergy routines remotely from your .NET client, or if your web server is Windows based, you can convert to run natively without xfServerPlus / xfNetLink .NET.

Important

For web services (IIS and WCF), globals, channels, and server connections must be isolated by AppDomain. For more information, see Using Synergy .NET in Multi‑Threaded Applications, available on the Synergex blog, and see SynNetAspAppDomainOnlyInterop.zip, available from Synergy CodeExchange in the Resource Center on the Synergex web site.

To convert xfServerPlus routines for native .NET access,

1. Create a Synergy/DE interop project in Visual Studio. (In the New Project window for Visual Studio, select Synergy/DE > Interop.) You can add this project directly to the client solution, or you can create a separate solution (and later add a reference to it from the client).

The project will include the file SynergyRoutines.dbl, which has stub routines for XFPL_LOG and SET_XFPL_TIMEOUT so that if your Synergy code calls these two xfServerPlus API routines, it won’t break. SynergyRoutines.dbl also includes some datetime conversion routines that are used by the generated classes. Do not alter these routines and do not remove this file from the project.

Note

If your xfNetLink client program calls XFPL_REGCLEANUP directly, you will need to find some other way to incorporate that functionality. For example, you could change your code to directly call the cleanup routine that was called by XFPL_REGCLEANUP.

2. Add the source files that contain the Synergy routines currently accessed by your xfNetLink .NET application to the project.
3. If your Synergy routines have not yet been modified to use attributes, parameter modifiers, and (optionally) documentation comments, do so now. See Using attributes to define Synergy methods.

Only the interface property of the xfMethod attribute is required when attributing code in an interop project, but you may need other properties, such as method name, depending on your code. The elb, id, and encrypt properties are unnecessary. Pay special attention to how methods are named so that you do not break existing code. If you’ve already attributed your code, including properties such as elb and id, you can leave it as is; these are not necessary when using the interop project type, but they do no harm.

Pay special attention if you choose to rely on default sizes for return values when attributing code, as the data type conversion from Synergy to C# types sometimes depends on the defined size. See Appendix B: Data Type Mapping for xfNetLink Java for details on data type mapping.

Note

If you used the alternate interface name feature, you will need to specify the alternate name for the interface property when you attribute your code. For example, if the interface for the login routine was Cust in the SMC and you always changed it to Customer when you generated classes, you would use Customer for the interface property in the xfMethod attribute. Or, if you generated classes once with Cust and a second time with Vendor, you’d create two xfMethod attributes for the login routine, one for each interface. See Attribute examples for an example.

If your Synergy routines pass structures as ordinary parameters or as arrays, redefine them as structfields.

As with return values, if you rely on default sizes for parameters when attributing code, you should pay special attention, as the data type conversion from Synergy to C# types sometimes depends on the defined size. See Appendix B: Data Type Mapping for xfNetLink Java for details on data type mapping.

4. Set project properties.
5. Set environment variables used by the Synergy routines. See Using environment variables with Synergy .NET. If your application passes structures as parameters, be sure to specify the location of the repository files. See Using Synergy/DE repositories in Visual Studio.
6. Build the interop project to generate the wrapper classes and the assembly. Fix any issues reported by the compiler (see step 4 for more information). The generated classes are added to the project. Note that the classes and assembly are generated in one step rather than two as they were in Workbench.
Important

If you previously edited the generated classes, you will need to find some other way to include the added (or altered) functionality into your application. Because classes are generated and the assembly is built all in one step, any changes you make to the classes will be overwritten when you rebuild.

7. Update your client application: