Synergy/DE project templates

Synergy DBL Integration for Visual Studio (SDI) includes project templates, which enable you to create Synergy/DE applications. Templates are available for both traditional Synergy and Synergy .NET projects. They can be accessed directly from Visual Studio (via the New Project dialog) or installed as a NuGet package for use with the .NET CLI. For an overview of Synergy projects, their structure, and how Visual Studio builds them, see Synergy projects, solutions, and files.

This topic includes the following sections:

• SDK vs. non-SDK project templates
• Installing and using project templates
• Traditional Synergy project templates
• Synergy .NET project templates
• Updating projects to use SDK packages
• Special considerations for multiple-mainline projects

SDK vs. non-SDK project templates

There are two types of Synergy project templates, SDK templates and non-SDK templates. SDK project templates (which have “SDK” in their names) are the updated and recommended project type, designed to align with current .NET development practices.

SDK project templates

Synergy SDK project templates are identified by “SDK” in the template name. They enable you to create projects that can be built on Windows and Linux. SDK projects are an overhaul of the packaging of build tools for traditional Synergy and Synergy .NET projects, bringing them in line with modern .NET practices. They give tighter control over which versions of the tools you target, make projects smaller, and enable cross-platform build scenarios because the tooling is self-contained. The SDK NuGet packages associated with our SDKs come packaged with either cross-platform .NET code, or the native-built components required to build your code.

Windows requirements

• Synergy/DE 12.1 or higher
• SDI 2025.03.1285 or higher
• .NET 8+ SDK

An internet connection is required when developing SDK projects.

Linux requirements

• Synergy/DE 12.1 or higher
• .NET 8+ SDK

Building on Linux

In addition to ensuring your system meets the requirements listed above, ensure your Synergy environment is set up with setsde or your own script. This should include a correctly defined DBLDIR and a running license server. Then use “dotnet build” to build your solution.

Non-SDK project templates

Non-SDK templates are developed and built on Windows. They do not require an internet connection and may be useful in environments where network access is restricted. For information on converting an existing non-SDK project to an SDK project, see Updating projects to use SDK packages below.

Installing and using project templates

Synergy project templates are available in the Visual Studio New Project dialog (e.g., via File > New > Project) and via the Synergex.Projects.Templates NuGet package.

See the following for more information on using project templates:

• Developing for .NET 6 or Higher

• Developing for .NET Framework

• Developing a traditional Synergy application in Visual Studio

Using Synergex.Projects.Templates

To install the NuGet package, run

dotnet new install Synergex.Projects.Templates

If you see an error such as “Synergex.Projects.Templates could not be installed, the package does not exist”, verify that the NuGet feed (https://api.nuget.org/v3/index.json) is configured as a package source.

After installation, you can create a new project by using “dotnet new...”

dotnet new shortname -n MyProjectName

For example, to create a Synergy .NET console application that runs on .NET 6 or higher:

dotnet new SynNETApp -n MySynNetApp

When you use an SDK project template to create a project, if there isn't a global.json file in the solution directory, one will be automatically added to that directory. For SDK projects to work, this file must be in the solution directory and must specify SDK package versions for the types of SDK projects in the solution. See Step 1: Create global.json below for more information. Also note that you should keep package versions up to date with the latest versions in NuGet. You must update this file manually; it is not updated automatically.

See Microsoft .NET CLI documentation for more information.

Traditional Synergy project templates

For information on using these templates to develop traditional Synergy applications and libraries, see Developing a traditional Synergy application in Visual Studio.

Template	Short name	Description
Executable Library (ELB) Executable Library SDK (ELB)	synELB synELBSDK	For creating a traditional Synergy executable library (ELB), which is a collection of traditional Synergy routines that can be used in traditional Synergy OLBs, DBRs, and other ELBs. Note the following: You can build an ELB directly from an OLB. To do this, open the ELB project and add a reference to the OLB project. Then remove any source files from the ELB project, and build the ELB. To include gennet40/gennet-generated source files in an ELB, add the source files as compile files, add the .inc file generated by gennet40/gennet as a content file, and set the “Concatenate source files (-qconcat)” option on the Compile page of project properties before compiling the project. For OpenVMS development, use this template for code that will become a shared library. See OpenVMS development with Visual Studio. Projects created with this template can reference traditional Synergy ELB, OLB, and Repository projects. See the Synergex YouTube video Using the ELB Project Template.
Multiple Mainline (DBR) Multiple Mainline SDK (DBR)	synMultiMain synMultiMainSDK	For creating a traditional Synergy application that results in multiple mainline programs (each containing a MAIN routine) within a single project. Use this to create an application that is distributed as a number of DBRs (which are typically linked against common libraries). Note that each source file results in a separate .dbr file, and each source file can be run and debugged separately. To do this, right-click the source file in Solution Explorer and then select “Start Debugging” or “Start Without Debugging” from the context menu. To specify which program in a multiple mainline project is the entry point for the application, set the “Startup object” option on the Application page of project properties, or right-click the source file in Solution Explorer and select “Set as Startup object” from the context menu. (The program set as the startup object is displayed in bold text in Solution Explorer.) For more information, see Application page of Visual Studio project properties (traditional Synergy). For information on associating source files with mainline files, see Special considerations for multiple-mainline projects below. Projects created with this template can reference traditional Synergy ELB, OLB, and Repository projects. See the Synergex YouTube video Using the Multiple Mainline Project Template.
Object Library (OLB) Object Library SDK (OLB)	synOLB synOLBSDK	For creating a traditional Synergy object library (OLB) that can be linked to or referenced by other libraries and applications. Note the following: To build only sources that have been added or changed since the last build, select a Build option from the Visual Studio Build menu. To rebuild the entire project or solution, select a Rebuild option from the Visual Studio Build menu. You will need to do this if you remove a source module and you want the build to reflect that change. 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.) When creating a library for shared code, use an ELB rather than an OLB. To include gennet40/gennet-generated source files in an OLB, add the source files as compile files, add the .inc file generated by gennet40/gennet as a content file, and set the “Concatenate source files (-qconcat)” option on the Compile page of project properties before compiling the project. Projects created with this template can reference source files and Repository projects. For information on building an ELB directly from an OLB, see Executable Library (ELB) above. See the Synergex YouTube video Using the OLB Template.
	synScriptProj	For creating a UI Toolkit window library. Script projects accept window script source files and compile those sources to produce the result. May reference Repository projects to automatically supply RPSMFIL and RPSTFIL to the Script compiler.
Synergy/DE Repository Synergy/DE Repository SDK	synRepoProj synRepoProjSDK	For creating a repository that can be referenced by traditional Synergy and Synergy .NET projects. Repository projects replace RPSMFIL and RPSTFIL settings and enable the build system to know when a project should be rebuilt due to a repository change. See Using Synergy repositories in Visual Studio and Repository page of Visual Studio project properties for more information. See the Synergex YouTube video Using the Repository Project Template.
Traditional Application (DBR) Traditional Application SDK (DBR)	synTradApp synTradAppSDK	For creating a traditional Synergy program with a single .dbr file. (Only one source file will contain a MAIN.) Projects created with this template can reference traditional Synergy ELB, OLB, and Repository projects.
Unit Test (Traditional) Unit Test SDK (Traditional)	synTradUnitTestProj synTradUnitTestProjSDK	For creating an MSTest unit test project for traditional Synergy unit tests. When built, a traditional Synergy unit test project results in a traditional Synergy unit test library, which is an ELB. See Unit testing for traditional Synergy for more information.

Synergy .NET project templates

For information on using the following templates to develop Synergy .NET applications and libraries, see Developing for .NET Framework, Developing for .NET 6 or Higher, and Developing .NET Standard Libraries.

Updating projects to use SDK packages

You can convert non-SDK projects into SDK projects by centralizing target versions in a single global.json file (simplifying configuration) and replacing legacy imports in project files.

Step 1: Create global.json

At the solution level (i.e., in the root directory for the solution), add a global.json file to define the SDK versions for all SDK projects in the solution. This file is required, and the SDK names in this file must match the identifiers used in the <Project Sdk="..."> attribute (e.g., Synergy.Traditional, Synergy.Net). The following example shows how these targets are defined. Note, however, that the versions listed here were the latest at the time of publication. You should specify the latest versions of these packages in NuGet and keep them up to date. You must update this file manually; it is not updated automatically.

{

"msbuild-sdks": {

"Synergy.Traditional": "1.0.0.1-pr4",

"Synergy.Traditional.UnitTest": "1.0.0.1-pr4",

"Synergy.Net": "1.0.0.1-pr1",

"Synergy.Repository": "1.0.0.1-pr4",

}

}

Step 2: Edit project files

Traditional Synergy projects

Start with the Project tag near the top of the file. Change the Project line from something like this:

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

to this:

<Project Sdk="Synergy.Traditional" DefaultTargets="Restore;Build" >

Then look for the following and remove it.

<Import Project="$(MSBuildExtensionsPath)\Synergex\dbl\Synergex.SynergyDE.Traditional.targets" />

Synergy .NET projects

Start with the Project tag near the top of the file. Change the Project line from something like this:

<Project Sdk="Microsoft.Net.Sdk" DefaultTargets="Restore;Build">

to this:

<Project Sdk="Synergy.Net" DefaultTargets="Restore;Build" >

Then look for the following block and remove it.

<PackageReference Include="Synergex.SynergyDE.Build" Version="25.*" />

Repository projects

Start with the Project tag near the top of the file. Change the Project line from something like this:

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

to this:

<Project Sdk="Synergy.Repository" DefaultTargets="Restore;Build" >

After the Project tag, repository projects have a few different variations. Look for any of the following blocks to remove.

<Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">

<PropertyGroup>

<ErrorText>This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them.  For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>

</PropertyGroup>

<Error Condition="!Exists('$(USERPROFILE)\.nuget\packages\synergex.synergyde.build\24.9.2004\build\rps\Synergex.SynergyDE.Build.targets')" Text="$([System.String]::Format('$(ErrorText)', '$(USERPROFILE)\.nuget\packages\synergex.synergyde.build\24.9.2004\build\rps\Synergex.SynergyDE.Build.targets'))" />

</Target>

<Import Project="$(MSBuildExtensionsPath)\Synergex\dbl\Synergex.SynergyDE.Traditional.targets" />

Traditional Synergy unit test projects

Start with the Project tag near the top of the file. Change the Project line from something like this:

<Project ToolsVersion="4.0" DefaultTargets="restore;Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

to this:

<Project Sdk="Synergy.Traditional.UnitTest" DefaultTargets="Restore;Build" >

Then look for the following and remove it.

<Import Project="$(MSBuildExtensionsPath)\Synergex\dbl\Synergex.SynergyDE.Traditional.UnitTest.targets" />

Special considerations for multiple-mainline projects

Multiple mainline projects are designed for applications that consist of several mainline programs that share settings and produce several DBRs or EXEs from one project. The project created from a multiple-mainline project template handles much of the functionality for this, but there are aspects you may need to handle manually:

• Modifying a multiple-mainline project for multiple mainlines that use different source files with the same name

• Multiple mainline file naming differences between traditional Synergy and .NET

Modifying a multiple-mainline project for multiple mainlines that use different source files with the same name

If you have a Synergy application with the following:

• A number of mainline programs that reference source files (instead of ELBs or OLBs) and are built with these source files
• Referenced source files that share the same name but have different code—e.g., different implementations of a subroutine for different mainlines.

the SDI functionality described below is designed to enable you to develop a multiple mainline project for that application in Visual Studio. (As an alternative, you may be able to create a project for each mainline, but this is generally less convenient than a multiple mainline project, and if there are too many projects, Visual Studio might not be able to load the solution.)

The following XML attribute and tags enable a multiple mainline project to support this type of application. All three are required in the .synproj file for the project and are illustrated in the example code below.

• DependencyFiles – This attribute for the Compile tag accepts a semicolon-delimited list of source files to associate with the mainline program that the Compile tag is for. Add this attribute to the Compile tag for each mainline that uses other source files.
• Link – In each Compile tag, add a Link tag to specify the name of the mainline as it will appear in Solution Explorer.
• None Include – For each file in each DependencyFiles list for the project, add a “None Include” tag to the .synproj file (e.g., at the end of the .synproj file).

For example, if you have a project with two mainlines that each reference two different source files but with the same names (e.g., ABC.DBL and XYZ.DBL), the .synproj file would need to include something like the following:

...

<Compile Include="..\..\SRC1\MAIN1.DBL" DependencyFiles="..\..\SRC1\ABC.DBL; ..\..\SRC1\XYZ.DBL">

<Link>MAIN1.DBL</Link>

</Compile>

<Compile Include="..\..\SRC2\MAIN2.DBL" DependencyFiles="..\..\SRC2\ABC.DBL; ..\..\SRC2\XYZ.DBL">

<Link>MAIN2.DBL</Link>

</Compile>

...

<None Include="..\..\SRC1\ABC.DBL" />

<None Include="..\..\SRC1\XYZ.DBL" />

<None Include="..\..\SRC2\ABC.DBL" />

<None Include="..\..\SRC2\XYZ.DBL" />

In Solution Explorer, ABC.DBL and XYZ.DBL would appear as subnodes under MAIN1.DBL, and MAIN2.DBL, but they would be for different source files from different directories.

Multiple mainline file naming differences between traditional Synergy and .NET

File naming conventions and conflicts in multiple mainline projects are handled differently in traditional Synergy than they are in Synergy .NET.

In traditional Synergy multiple mainlines,

• If multiple programs have the same name, TargetExt must be set on all compile includes for those programs in the .synproj file of their multiple mainline project. For example, for Program1.abc and Program1.xyz, the following would build successfully:

<Compile Include="Program1.abc" TargetExt="abc" />
<Compile Include="Program1.xyz" TargetExt="xyz" />

while the following would fail:

<Compile Include="Program1.abc" TargetExt="abc" />
<Compile Include="Program1.xyz"  />

or

<Compile Include="Program1.abc" />
<Compile Include="Program1.xyz"  TargetExt="xyz"/>

or

<Compile Include="Program1.abc"/>
<Compile Include="Program1.xyz" />

• If all compile includes are unique, the TargetExt attribute is not necessary. For example,

<Compile Include="Program1.abc" />
<Compile Include="Program2.abc" />

• TargetExt="dbl" is not allowed and will cause a build failure.

In Synergy .NET multiple mainlines,

• The TargetExt attribute is not supported. For example, the following will result in a build failure:

<Compile Include="Program1.abc" TargetExt="abc" />
<Compile Include="Program1.xyz" TargetExt="xyz" />

• Due to a .NET limitation, each compile include must have a unique name. For example,

<Compile Include="Program1.abc" />
<Compile Include="Program2.xyz"/>

not

<Compile Include="Program1.abc" />
<Compile Include="Program1.xyz" />

Duplicate compile includes, such as the following, will fail in both traditional Synergy and Synergy .NET:

<Compile Include="Program1.abc" />
<Compile Include="Program1.abc" />