Synergy DBL Integration - Requirements, Compatibililty & Upgrades

This page lists system requirements for installing Synergy DBL Integration for Visual Studio (SDI), changes you may need to make when upgrading to the latest version of SDI, and basic Visual Studio, .NET, and Synergy/DE runtime compatibility information.

The SDI installer enables you to install two sets of SDI components: MSBuild Components and Visual Studio Components. MSBuild Components enable you to build Synergy projects from the command line with MSBuild and are included and required for every SDI installation. MSBuild Components can be installed without the Visual Studio Components, but Visual Studio Components are required for developing and building Synergy projects in Visual Studio.

The SDI installer is available from the Downloads area of the Synergex Resource Center. We recommend installing the latest version of SDI and Synergy/DE. The latest version of SDI is the only supported version of SDI, and the latest version of Synergy/DE provides the best development experience.

System requirements for SDI

The following are required and must be installed on a 64-bit (x64) Windows machine before SDI is installed on that machine. See Compatibility, current version below, and note that SDI can be installed only on x64 systems.

  • One of the following versions of Windows:
    • Windows 10 or higher
    • Windows Server 2012 or higher
  • .NET Framework 4.7.2 and 4.8
  • 32-bit and 64-bit Synergy/DE 10.3.3d or higher. See Synergy/DE Requirements below.
  • Visual Studio 2022 17.4 or higher. Note the following:
    • The “.NET desktop development” workload is required for all Synergy development in Visual Studio. For .NET Core, .NET 6 and higher, and .NET Standard development, the “.NET Core cross-platform development” workload is also required. If the ".NET Core cross-platform development" workload is not available for your version of Visual Studio, go to into the .NET area on the "Individual Components" tab in the Visual Studio Installer, select whichever .NET platforms you may need to develop for, and install those:

    • The SDI installer option “MSBuild Components” does not require Visual Studio. This option enables you to use MSBuild to build Synergy projects from the command line. If you install “MSBuild Components” on a machine that does not have Visual Studio, you must install Microsoft’s Build Tools for Visual 2022 (or the full Visual Studio IDE) to use MSBuild to build Synergy projects.

Additionally, note the following:

  • We recommend installing SDI on a machine with more than 8 GB of memory. This makes multi-core processing possible when loading large Synergy projects.
  • Synergy projects that use device licensing or asynchronous processing must target .NET Framework 4.7.2 or higher.
  • For better performance, exclude the following programs from virus scanning: dbl.exe, dblink.exe, dblnet.exe, dblnet64.exe, dblproto.exe, devenv.exe, rpsutl.exe, and sdiscript.exe. Also exclude the location used for prototype files (.dbp), and temporary Visual Studio files from virus scanning. (Alternatively, you can exclude the .dbp extension and the extensions of .include files and repository files--e.g., .ism and .is1.)

Synergy/DE requirements

We recommend installing the latest version Synergy/DE along with the latest version of SDI on development machines.

  • Before you install SDI, both the 32-bit and the 64-bit versions of Synergy/DE 10.3.3d or higher must be installed.
    • Synergy/DE 11.1.1d or higher is required to create or run traditional Synergy unit test projects.
    • Synergy/DE or higher is required to develop Script projects.
  • If you're running a pre-11 version of Synergy/DE, the REV11 licensing upgrade package must be installed on your license server machine. See the Synergy/DE REV11 Licensing FAQ for more information and Using the licensing upgrade package on Windows in the Synergy/DE documentation for installation instructions.

Compatibility, current version

The following list basic Visual Studio, .NET, and Synergy/DE runtime compatibility information for the current version of SDI:

  • Visual Studio: 
    • Lowest supported version: 2022, version 17.4
    • Highest tested version: 2022, version 17.8.5
  •  .NET:
    •  Lowest .NET Framework version that Synergy projects can target: 4.7.2.
    • Lowest .NET version that Synergy projects can target: 6 
  •  Synergy/DE runtime:
    •  Lowest version that traditional Synergy projects can target: 9.5.1
    •  Lowest version that Synergy .NET projects can target: 10.3.1b 
    •  Highest tested version: 12.2.1 (see note below)
    •  Default target version: 12.1.1

 Note the following: 

  • The "Target Synergy runtime" drop-down list (on the Build page of project properties for a traditional Synergy project) does not include a "12.2.1" selection. To target the runtime for 12.2.1 feature release, select "Latest" in the drop-down list. 
  • Synergy .NET projects that target a Synergy/DE runtime version that is lower than the minimum are automatically set to the lowest supported version when they are opened in Visual Studio. [tr#39699]
  • Synergy projects that target a version of .NET Framework that is lower than the lowest supported version are automatically upgraded to the lowest supported version when opened in Visual Studio. [tr#39446]
  • If a Synergy project targets a version of .NET Core that is lower than the lowest supported version of .NET Core, you must manually update the project to the lowest supported version of .NET Core. [tr#39223]

Visual Studio compatibility for previous versions

The following table lists information on Visual Studio versions (the lowest supported version and the highest tested version) supported by past versions of SDI:

SDI Lowest version Highest tested version

2023.12.1823 through 2024.02.1066

2022, version 17.4

2022, version 17.8.2


2022, version 17.2

2022, version 17.7.6


2022, version 17.2

2022, version 17.5.0

2023.03.1019 through 2023.08.1404

2019, version 16.11

2022, version 17.5.0

Upgrading SDI

You can upgrade to the current version of Synergy DBL Integration (SDI) from any previous version.
  • For existing .NET Core, .NET 5 and higher, and .NET Standard projects, you must use the NuGet Package Manager to update the NuGet packages Synergex.SynergyDE.synrt and Synergex.SynergyDE.Build after upgrading SDI. This will update Synergy build and runtime tools.
  • For existing Repository and Script projects, you must update the Synergex.SynergyDE.Build NuGet package after upgrading SDI.
  • The license product code used by SDI is PSDE. (Prior to SDI 2021.09.3540, it was PSW.)

Installer pop-up windows and innocuous errors due to workaround

Visual Studio versions 17.3.5 through 17.4.3 have a bug that disables the SDI extension when SDI is installed or upgraded on a machine with one of those versions. To prevent this from occurring, we implemented a workaround in the SDI installer. When SDI is installed or upgraded on a machine with Visual Studio 2022 17.3.5 - 17.4.x, the workaround runs the VSIX portion of the installation in interactive mode. This prevents the SDI installation from being disabled, but it also results in extraneous information being displayed in the installer window and one or more extraneous pop-up windows with checkboxes for Visual Studio versions. Note the following:

  • The additional information displayed in the installer window may include errors. These are expected and will not prevent SDI from installing successfully.
  • Do not deselect any Visual Studio versions in the pop-up windows. This may prevent the extension from installing correctly.

If you install or upgrade SDI on a machine with Visual Studio 2022 17.3.5 - 17.4.x, ignore the errors mentioned above and leave Visual Studio version checkboxes selected in the pop-up windows to ensure that SDI is successfully installed.

Re-enabling the SDI Extension

If you have already experienced the Visual Studio bug described above, you can re-enable the SDI extension by doing the following:

  1. Open Visual Studio and select Extensions > Manage Extensions from the Visual Studio menu.
  2. In the “Manage Extensions” window, select the “Installed” tab.
  3. Scroll through the list of installed extensions and find the SynergyDBLIntegration extension.
  4. Click the “Enable” button for the SynergyDBLIntegration extension.

This will re-enable SDI. You will then need to reload all Synergy projects in solutions that were opened while the extension was disabled.

Recommended Changes

When upgrading SDI from... Former usage Change for current version of SDI Explanation/comments

a version earlier than 2023.09.1521

If you use Visual Studio 2019...

Upgrade to Visual Studio 2022 17.2 (or higher)

SDI no longer supports Visual Studio 2019.

a version earlier than 2022.07.1273

If you have Synergy .NET projects with FOR-FROM loops that use a BY variable that is modified in the loop body…

Update FOR-FROM loops as necessary for this change in behavior: the current value of the BY variable is now saved before entering the loop, and that value is used for the increment, which keeps the BY value the same for the duration of the loop.

The behavior of the FOR-FROM loop changed for Synergy .NET in 2022.07.1273 to avoid unexpected iteration results when using a BY variable that is modified in the loop body. Prior to this change, incrementing or modifying the BY variable with a Synergy descriptor type in the body of a FOR-FROM loop would immediately affect the increment value used for the next iteration. With this change, however, the current value of the BY variable is saved before entering the loop, and that value is used for the increment. This keeps the BY value the same for the entire duration of the loop, which matches the behavior for traditional Synergy. This change may break existing code that relies on the previous behavior (the pre-2022.07.1273 behavior). [tr#39806]

a version earlier than 2022.02.1048

If you have Repository projects with project references or service references…

Remove any existing references in Repository projects.

We no longer support adding project references or service references for Repository projects. These options have been disabled. [tr#37607]

a version earlier than 2022.03.1110

If you have Synergy projects that target .NET Framework and that target a runtime version prior to 10.3.1b…

If you want any of these projects to target a version other than the minimum (10.3.1b), specify that version on the Build page of project properties.

The minimum Synergy/DE runtime target for .NET Framework projects is now 10.3.1b. Existing .NET Framework projects that target a runtime version prior to this version will automatically be set to target this version when they are opened in Visual Studio. If you want an existing project to target a different version of the runtime, specify that version on the Build page of project properties. [tr#39699]

a version earlier than 2021.12.3567

If you have .NET Interop projects that use the Equals operator to compare two objects containing groups…

Update the code to account for the fact that the Equals method on the groups themselves will now be called. (In versions prior to 2021.12.3567, the “!=” operator was used in this situation.)

This change is due to a fix for .NET in 2021.12.3567: using the Equals method to compare two objects containing groups will now call the Equals methods on the groups themselves, instead of using the "!=" operator. This change may break your existing code if you were relying on the older, incorrect behavior. [tr#39518]

a version earlier than 2022.01.1003

If you have assemblies that use boxed descriptor types and were compiled using -qrntcompat 11010104 or greater…

Recompile all assemblies that use boxed descriptor types and were compiled using -qrntcompat 11010104 or greater.

This change is due to a fix for the issue that caused an ^AS of a boxed descriptor to always return non-null for -qrntcompat values of 11010104 or greater. [tr#39627]
IMPORTANT: HarmonyCore users who are using recent HarmonyCore versions with the 22.1.1003 Synergex.SynergyDE.Build NuGet package may be affected. Make sure you update your HarmonyCore NuGet packages at the same time as the Synergex.SynergyDE.Build package.

a version earlier than 11.1.1

If you have a Synergy Portable Class Library (PCL) project…

Replace it with a Synergy .NET Standard project:

  1. Use the Synergy Class Library (.NET Standard) template to create a new project.
  2. Add all the files, references, etc., from the PCL project to the new .NET Standard Class Library project.
  3. In code, replace occurrences of the D_PORTABLE define with D_NETSTANDARD.
  4. Build and test.

See Developing .NET Standard libraries in the Synergy/DE documentation for more information.

We removed the Portable Class Library (PCL) template from SDI because Microsoft deprecated this project type. Existing projects will continue to work, but you will not be able to create new ones. A .NET Standard project offers more functionality. [tr#38177]

a version earlier than 10.3.3d

If you have an application with subroutines and functions that have been added only to a default namespace…

Correct your code by adding a single class to the namespace or by removing the IMPORT statement. Then regenerate all .dbp files.

Subroutines and functions in traditional Synergy are now automatically added to the global namespace. As a result, the SYNDEFNS environment variable is no longer used to set a default namespace, and its value must now be a semicolon-delimited list of namespaces to implicitly import. This change may break compiles for traditional Synergy programs and libraries. [tr#37211]

a version earlier than 10.3.1

If you have projects with classes that are partially compiled…

After upgrading, fully compile all classes.

We made a number of improvements to the way structures and records are aligned. This change may break your code if you have classes that are partially compiled. [tr#35442]

a version earlier than 10.1.1d

If you use the “Generate Synergy Interop Code” menu entry (under Tools)…

Don’t. Just build the project instead.

This menu option has been removed because code generation is now integrated with the build. [tr#34927]

a version earlier than 10.1.1c

If you have Interop projects…

  1. Once you have installed SDI, create a new Interop project.
  2. Copy the SynergyRoutines.dbl file from the project folder for the new Interop project and paste it into the project folder for each of your existing Interop projects.
  3. Rebuild your Interop projects with Build > Rebuild Solution, which generates Interop code. (The Build Solution and Clean Solution options will not work for this step because they do not generate Interop code.)

You must update SynergyRoutines.dbl from a newly created project (as described) or Interop projects will fail to build. This is due to a number of improvements we made for Synergy Interop projects, including improvements in performance and the way code is Generated. [tr#34816]

a version earlier than 10.1.1c

If you have a project with a reference to an enum type on the Settings page of project properties…

Regenerate Settings.designer.dbl by changing any value on the Settings page and saving the file. This will cause Visual Studio to regenerate the code-behind file.

We fixed an issue that caused references to enum types on the Settings page to be generated as boxed references, which could result in runtime errors. [tr#34955]