Developing for .NET Framework

SDI enables you to create Synergy applications and libraries for .NET Framework on Windows x86 or x64. This topic, which includes the following sections, outlines the basic Synergy development steps for .NET Framework.

Basic development steps in Visual Studio
Basic .NET CLI development steps
Creating a NuGet package for a Synergy .NET Framework application

Basic development steps in Visual Studio

The following steps outline the Visual Studio development process and requirements for desktop and server applications for .NET Framework on Windows x86 or x64. Most of these steps outline Visual Studio procedures, so see Visual Studio documentation for more information.

Start by reviewing Synergy .NET Requirements and SDI Requirements, Compatibility, and Upgrades. Then set options for your Visual Studio environment as necessary. 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.

In Visual Studio, create a project for each assembly in your application, and put all the projects for your application in one solution. You can use the following project templates for .NET Framework development:

ASP.NET Server Control Library

Class Library (.NET Framework)

Class Library (.NET Standard)

Console App (.NET Framework)

Empty Project

Interop

Multiple Mainline (.NET Framework)

Synergy/DE project templates

Synergy Custom Action

Synergy/DE Repository

Unit Test Project (.NET Framework)

WCF Service Library

Windows Service

For example, to create a console application (an application that runs from the command line), select File > New > Project in Visual Studio. Then select the “Console App (.NET Framework)” 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:

You can include Synergy projects in a solution for another .NET language (e.g., in a C# solution), and a solution with Synergy projects can include projects written in other .NET languages. See Projects for Synergy .NET for more information.
For portability, put logic in .NET Standard libraries. A Synergy .NET Standard library can target .NET Framework or .NET 6 or higher. For more information, see Developing .NET Standard Libraries.
For information on creating a multiple mainline project with programs that reference different source files with the same name, see Modifying a multiple-mainline project for multiple mainlines that use different source files with the same name.
In addition to being available in Visual Studio, Synergy project and project item templates are distributed in the following NuGet packages for use with the .NET CLI (e.g., the “dotnet” command): Synergex.Projects.Templates and Synergex.ProjectItem.Templates.

Add DBL code, references to any needed assemblies, and other items to the projects for your application. See Synergy/DE item templates for information on new items you can add to a project, and note the following:

For information on which Synergy features are supported for Synergy .NET, see Synergy DBL Support for .NET.
For information on adding references or dependencies to Synergy repositories, see Using Synergy repositories in Visual Studio.
See Performing Common Synergy .NET Coding Tasks for information on instantiating and using a .NET class, inheriting and overriding a .NET class, and more.
Synergy projects for Windows desktop and server applications automatically reference synrnt. This is required. See Synergy runtime and build libraries for more information.
Device licensing is optional with .NET Framework. To use device licensing, an assembly in your application must implement device licensing, and that assembly must be built with the “Enable device licensing” option on the Compile page of project properties. See Device Licensing (Windows).
To use the XML API for .NET Framework development, you must add a reference to Synergex.SynergyDE.synxml.dll. For .NET Standard (and other SDK-style projects), use the Synergex.SynergyDE.synxml NuGet package.
To use the Repository subroutine library for .NET Framework development, you must add a reference to Synergex.SynergyDE.ddlib.dll. For .NET Standard (and other SDK-style projects), use the Synergex.SynergyDE.ddlib NuGet package.
For Interop projects, Synergy global structures used as attribute arguments must be defined in an assembly outside of a namespace.
You are not limited to the standard file extensions for Synergy DBL files (e.g., .dbl for code files). You can add files with other extensions if you specify those extensions in the Visual Studio IntelliSense dialog box for the Synergy DBL text editor. See IntelliSense page of Visual Studio text editor options.
Use ASYNC routines for communication across networks and the internet. See Asynchronous processing (.NET).
To generate documentation from comments in code, use ;;; to identify documentation comments in your code, and select the “XML documentation file” option on the Build page of project properties.

Set project properties, which include settings for licensing, deployment, and building/compiling. See Synergy/DE project properties. For information on setting environment variables for a project, see Environment variables and Visual Studio development.

Note that 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.

Build and debug the solution in Visual Studio using Visual Studio build and debug commands. See Visual Studio documentation for information on build features and the debugger. See Debugging Synergy .NET Code for debugging information specific to Synergy .NET. And see the Project Only information in SDI features for information on commands that enable you to build or rebuild (or clean) an individual project without affecting other projects in the solution, even referenced projects.

Deploy your application to machines that meet deployment requirements listed in Synergy .NET Requirements. Note that you can create a NuGet package for a Synergy project for .NET Framework; see Creating a NuGet package for a Synergy .NET Framework application below.

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 Synergy application for .NET Framework. Most of these steps outline .NET CLI procedures, so see Microsoft documentation on the .NET CLI for more information.

Make sure your development machine meets the requirements listed in Synergy .NET Requirements and the SDI requirements page.

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.

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
ASP.NET Server Control Library	synWebControlLib
Class Library (.NET Framework)	synNETFrameworkLib
Class Library (.NET Standard)	synNETStandardLib
Console App (.NET Framework)	synNETFrameworkApp
Empty Project	synEmptyProj
Interop	synInterop
Multiple Mainline (.NET Framework)	synNETFrameworkMultiMain
Synergy Custom Action	synCustomAction
Synergy/DE Repository	synRepoProj
Unit Test Project (.NET Framework)	synUnitTestProj
WCF Service Library	synWCFServiceLib
Windows Service	synWinService

For example, the following command creates a Synergy .NET Framework class library named MyNetFmwkClass:

dotnet new synNETFrameworkLib -n MyNetFmwkClass

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 step 3 and step 4 in Basic development steps in Visual Studio above), but you can use .NET CLI commands, modify project files, etc.

Do preliminary builds, running, and debugging in Visual Studio. See step 5 in Basic development steps in Visual Studio above. Alternatively, you can do some of these tasks with the .NET CLI (e.g., you can use “dotnet run” to run the built project).

For the final, deployable build, you can use the “dotnet publish” command.

Deploy to machines that meet deployment requirements (including licensing requirements) listed in Synergy .NET Requirements. For information on creating a NuGet package for a Synergy project, see Creating a NuGet package for a Synergy .NET Framework application below.

Creating a NuGet package for a Synergy .NET Framework application

The following steps outline the process for creating a NuGet package for a Synergy project that targets .NET Framework. For more information, see Microsoft documentation on the nuget.exe CLI.

In the directory for the Synergy project, run the nuget spec command to create a .nuspec file. For example:

nuget spec

This creates a .nuspec file with the default name Package.nuspec. You can specify different name by appending it to the command. The following example creates a file with the name Abc.Dbl.Base.nuspec:

nuget spec Abc.Dbl.Base

Open the .nuspec file in an editor and edit the author, package name, versions, etc., as needed. For example, if the file includes a dependency on a .NET Standard library that isn’t necessary, you can remove it.

Run the nuget pack command to generate the package from the .nuspec file. You can override the output location or other properties as needed. The following example generates a NuGet package named BcNet.Dbl.Base.nupkg:

nuget pack Abc.Dbl.Base.nuspec