Developing a traditional Synergy application in Visual Studio

This topic includes the following sections:

 

Synergy DBL Integration for Visual Studio (SDI) includes support for traditional Synergy development. This means you can use Visual Studio to develop traditional Synergy libraries and executables for Windows, Unix, and OpenVMS. Note the following:

Basic development steps in Visual Studio

The following steps outline the Visual Studio development process and requirements for a traditional Synergy application. Most of these steps are for Visual Studio procedures, so see Visual Studio documentation for more information.

1. Start by setting options for your Visual Studio environment. For example, you can control the behavior of the Visual Studio code editor (indentation, tab size, etc.), the way IntelliSense works for Synergy DBL files, and which file types are automatically treated as compile or content files. See Options for Synergy/DE projects for more information.
2. Create a solution for your application, and create projects for the mainline program, libraries, and (optionally) repositories and Toolkit window libraries for the application. To create these projects, use the following project templates:

For example, to create a program with a single .dbr file, select File > New Project in Visual Studio. Then select the “Traditional Application (DBR)” template. (You can use the New Project dialog’s search field to find this.) See Synergy projects, solutions, and files for more information, and note the following:

  • When creating a library for shared code, use an ELB rather than an OLB. (An OLB project should be referenced by only one project in the solution. Referencing an OLB project from multiple projects causes the OLB code to be compiled into multiple files for the application.)
  • You can create an ELB that builds directly from an OLB. See Executable Library (ELB).
  • If your application uses files generated by gennet/gennet40, create a separate ELB or OLB project for these files, and in step 2 below add the source files and the .inc file generated by gennet/gennet40 to this project. (Add the source files as compile files, and add the .inc file as a content file.) Then in step 3 below, add a reference to this project in the mainline (DBR) project, and set the “Concat source files (-qconcat)” option on the Compile page of project properties.
  • For Unix and OpenVMS development, use the project templates listed above. See Unix development with Visual Studio and OpenVMS development with Visual Studio.
  • For information on creating a multiple mainline project with programs that reference different source files with the same name, see Creating a project for multiple mainline programs that use different source files with the same name.
3. Build out and configure your projects by setting project properties, adding code and other items, referencing other projects and files as necessary, setting environment variables, and setting up build configurations. For more information, see

Note the following:

  • For Multiple Mainline projects, the “Startup object” field on the Application page of project properties determines which mainline is used as the starting point when you select a Visual Studio debug or run option. You can also set this by right-clicking a source file in Visual Studio’s Solution Explorer and selecting “Set as Startup Object” from the context menu.
  • The “Target Synergy runtime” setting on the Build page of project properties specifies the version of the Synergy runtime that the executable or library will target, enabling you to build an assembly for systems with earlier versions of the Synergy runtime.

If you deploy to systems with older versions of Synergy/DE, target these versions when you build, and then use remote debugging to test on other systems (e.g., on virtual machines) with these versions of Synergy/DE.

4. Build the solution or an individual project — e.g., by using a build or rebuild command in Visual Studio. For example, you can rebuild the entire solution by selecting Build > Rebuild Solution from the Visual Studio menu. Note the following:
  • Make sure the configuration and platform settings on the Visual Studio toolbar are correct for the build. See Configurations, platforms, and profiles for more information.
  • To build or rebuild (or clean) a project without affecting other projects in the solution (even referenced projects), use a Project Only menu entry — e.g., Build > Project Only > Rebuild Only Project. See SDI features for information.
  • You can control the link order for referenced items for a traditional Synergy program by setting priority levels for these items. See Setting link priority for traditional Synergy in Visual Studio.

The Visual Studio Error List (View > Error) lists any errors encountered in the build. You can filter this list so that it is limited to the current project (which can be very helpful), the current document in the editor, or all documents open in the editor. You can also use the search feature for the Error List to find specific words or phrases in the list, and you can filter out errors, warnings, or messages. To clear only Synergy-related errors and warnings from the Error List, select Tools > Clear Error List from the Visual Studio menu.

5. Create unit tests by using the “Traditional Unit Test” project template. See Unit testing for traditional Synergy.
6. Debug the project or solution. To debug a project or solution, it must be built in Debug mode. See Debugging traditional Synergy with Visual Studio for more information, and note the following:
7. Deploy the application. For information on requirements for traditional Synergy applications, see System Requirements.

Adding code and other items in Visual Studio

You can add a new or existing item (a code file, a text file, etc.) by right-clicking the project node in Visual Studio’s Solution Explorer and selecting one of the following from the context menu: Add > New Item, Add > Existing Item, or Add > Reference Existing Item. (The Add > Existing Item command copies the file into the Visual Studio project. Add > Reference Existing Item adds a relative-path reference to the item.) Note the following:

Referencing projects and files in Visual Studio

References enable a project to use other projects (libraries and repositories) and external files. Referencing a library is equivalent to linking to a library — i.e., adding a library to a dblink command — when developing outside of Visual Studio.

You can add a reference by right-clicking the Reference node in Visual Studio’s Solution Explorer and selecting Add Reference from the context menu. Note the following:

Basic .NET CLI development steps

The following steps outline a basic procedure for using the .NET CLI (i.e., "dotnet" commands) and Visual Studio to create a traditional Synergy application. Most of these steps outline .NET CLI procedures, so see Microsoft documentation on the .NET CLI for more information.

1. Make sure your development machine meets the requirements listed in Synergy .NET Requirements and the Synergy DBL Integration Requirements page.
2. Use the following commands to install the Synergy project and item templates, which are available in nuget.org: 
dotnet new install Synergex.Projects.Templates
dotnet new install Synergex.ProjectItem.Templates

If you get an error such as “Synergex.ProjectItem.Templates could not be installed, the package does not exist”, the problem could be that the NuGet feed (https://api.nuget.org/v3/index.json) is not set up as a package source on your system. See Microsoft documentation on package sources for information on adding this package source.

3. Use the “dotnet new template_shortname” command (where template_shortname is one of the names listed in the “Short name” column below) to create a project for each .NET Framework assembly that will be in your application. And put all the projects for your application in one solution (e.g., by using “dotnet new sn -n solutionName” to create a solution, and by using “dotnet sln add projectPathAndName” to add a project to a solution).
Template name Short name
Executable Library (ELB) synELB
Multiple Mainline (DBR) synMultiMain
Object Library (OLB) synOLB
Script synScriptProj
Synergy/DE Repository synRepoProj
Traditional Application (DBR) synTradApp
Traditional Application (DBR) synTradUnitTestProj

For example, the following command creates a traditional Synergy multiple mainline project named MyTradMultiMain:

dotnet new synMultiMain -n MyTradMultiMain
4. Once you’ve created projects and a solution, you can add DBL code, resources, and other items to the projects, and you can set project properties. It’s generally best to do this in Visual Studio (see Basic development steps in Visual Studio above), but you can use .NET CLI commands, modify project files, etc.
5. Do preliminary builds, running, and debugging in Visual Studio. Alternatively, you can do some of these tasks with the .NET CLI (e.g., you can use “dotnet run” to run the built project).
6. For the final, deployable build, you can use the “dotnet publish” command.
7. Deploy to machines that meet deployment requirements (including licensing requirements) listed in Synergy .NET Requirements.

Unix development with Visual Studio

For Unix, there are two Visual Studio development paths:

In either case, use the same project templates you would use for Windows (see step 2 above), and note the following:

To debug a Unix application, you’ll need to run the application on a Unix machine and then use remote debugging to debug the application from Visual Studio, or use standard traditional Synergy debugging on the Unix machine. See Debugging traditional Synergy with Visual Studio for more information.

OpenVMS development with Visual Studio

For OpenVMS, you can develop and build with Visual Studio in Windows, and you may also be able to run and debug your code on Windows, but you will not be able to deploy files built in Visual Studio. For final deployable builds, you will need to move the code you developed in Visual Studio to an OpenVMS development machine and build the application there.