Synergy DBL Integration for Visual Studio - System Requirements & Upgrade Information

The installation file for SDI 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.

  • See the release notes (available from the Downloads area of the Synergy Resource Center) for information on fixes, new features, and important notes and warnings for the latest version of SDI.
  • For information on development and deployment requirements for Synergy .NET, see Synergy .NET Requirements in the Synergy/DE documentation.
  • For information on using SDI to develop Synergy applications in Visual Studio, see Synergy in Visual Studio and Synergy .NET Development in the Synergy/DE documentation.

System requirements for SDI

The following are required and must be installed on a 64-bit Windows machine before SDI is installed on that machine. SDI can be installed only on 64-bit systems.

  • One of the following versions of Windows:
    • Windows 8 or higher
    • Windows Server 2012 or higher
  • .NET Framework 4.7.2 or higher
  • 32-bit and 64-bit Synergy/DE 10.3.3d or higher. See Synergy/DE Requirements below.
  • Visual Studio 2022 (x64 only) or 2019 16.9 or higher (x86 only). (The SDI installer is 32-bit for all versions of Visual Studio.) Note the following:
    • The “.NET desktop development” workload is required for all Synergy development in Visual Studio. For .NET Core, .NET 5 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 includes an option, “MSBuild Components,” that 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 Studio 2019 or 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.

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 result 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, as 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 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]