With Synergy .NET, you can create console applications and libraries for .NET 6 and higher on Windows and Linux. This topic, which includes the following sections, outlines the basic development steps for .NET 6 and higher:
Version 6 and higher of .NET are generally updated more quickly than .NET Framework, and applications for .NET 6 and higher generally take less memory, run faster, and make for smaller deployments than equivalent .NET Framework applications. Additionally, if you create a self-contained deployment, changes to .NET versions on deployment machines will not affect your application. For more information, see Microsoft documentation for .NET (e.g., .NET fundamentals documentation.)
Basic development steps in Visual Studio
The following steps outline the basic procedure for using Visual Studio to create a Synergy application for .NET 6 or higher. Most of these steps outline Visual Studio procedures, so see Visual Studio documentation for more information.
| 1. | Start by reviewing Synergy .NET Requirements and the Synergy DBL Integration Requirements page. 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. |
| 2. | 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: |
Console App (.NET)
Console App SDK (.NET)
Class Library (.NET)
Class Library SDK (.NET)
Class Library (.NET Standard)
Multiple Mainline (.NET)
Multiple Mainline SDK (.NET)
Synergy/DE Repository
Synergy/DE Repository SDK
Unit Test (.NET)
For example, to create a console application, select File > New > Project in Visual Studio. Then select the “Console Application SDK (.NET)” template. (You can use the New Project dialog’s search field to find this.) See Synergy projects, solutions, and files and Synergy/DE project templates for more information, and note the following:
- For information on the differences between SDK and non-SDK templates, see SDK vs. non-SDK project templates.
- 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.
- For portability, put logic in .NET Standard class libraries. A .NET Standard class library can run on multiple platforms. See Developing .NET Standard Libraries for more information.
- 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.
|
Synergy projects for .NET 6 and higher automatically include the Synergex.SynergyDE.synrnt and Synergex.SynergyDE.Build NuGet packages, which are required for building and running the projects. The Synergex.SynergyDE.synrnt package is automatically included and required for both SDK and non-SDK projects, while the Synergex.SynergyDE.Build package is automatically included and required only for non-SDK projects. When a new project is created, the latest (non–pre-release) versions of the required packages are downloaded to a local NuGet repository for that project. To update NuGet packages for existing projects, use the NuGet Package Manager or a .NET CLI command (e.g., dotnet ...). For more information, see Microsoft documentation such as Install and manage packages in Visual Studio using the NuGet Package Manager. |
| 3. | Add DBL code, resources, and other items to the Visual Studio projects for your application, and make sure each project references any needed assemblies. 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, see Synergy DBL Support for .NET.
- See Performing Common Synergy .NET Coding Tasks for information on instantiating and using a .NET class, inheriting and overriding a .NET class, and more.
- For information on adding references or dependencies to Synergy repositories, see Using Synergy repositories in Visual Studio.
- Use ASYNC routines for communication across networks and the internet. See Asynchronous processing (.NET) for more information.
- Synergy .NET 6 and higher assemblies require traditional Synergy licensing. (Device licensing is not supported only for .NET Framework.) See Licensing .NET assemblies.
- To use the Repository subroutine library, use the Synergex.SynergyDE.ddlib NuGet package. To use the XML API, use the Synergex.SynergyDE.synxml NuGet package.
- 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.
| 4. | 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.
| 5. | Create preliminary builds and debug the project in Visual Studio using Visual Studio build and debug commands. |
- SDK projects can be built on Linux with the “dotnet build” command. See Building on Linux.
- For debugging information specific to Synergy .NET, see Debugging Synergy .NET Code.
- For information on Build menu commands that enable you to build or rebuild (or clean) an individual project without affecting other projects in the solution (even referenced projects), see the “Project Only” information in SDI features.
- For more information on building and debugging, see Microsoft documentation.
| 6. | For the final, deployable build, use the “publish” command. See Microsoft documentation (e.g., Publish .NET apps with the .NET CLI). Note that the publish command enables you to create self-contained or framework-dependent builds. For example, when the following command is run in the same directory as the solution, it creates a self-contained build (an .exe file) for Windows x64: |
dotnet publish -c Release -r win-x64
| 7. | Deploy to machines that meet deployment requirements (including licensing requirements) listed in Synergy .NET Requirements. |
Note that you can create a NuGet package for a Synergy .NET 6 or higher project by using the nuget pack command. For example:
nuget pack MyProject.synproj
For more information, see Microsoft documentation on the nuget.exe CLI.
Basic .NET CLI development steps
The following steps outline a basic procedure for using the .NET CLI (i.e., “dotnet” commands) to create a Synergy application for .NET 6 or higher. Most of these steps outline .NET CLI procedures, so see Microsoft documentation on the .NET CLI for more information.
| 1. | Whether you deploy to Windows or Linux, you'll develop on a Windows machine. Make sure that 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 assembly in your application. And put all the projects for your application in one solution (e.g., by using “dotnet new sln -n solutionName” to create a solution, and by using “dotnet sln add projectPathAndName” to add a project to a solution). |
| Template name | Short name |
|---|---|
|
synNETApp |
|
| Console App SDK (.NET) |
synNETAppSDK |
|
synNETLib |
|
| Class Library SDK (.NET) |
synNETLibSDK |
| Class Library (.NET Standard) | synNETStandardLib |
|
synNetMultiMainline |
|
| Multiple Mainline SDK (.NET) |
synNetMultiMainlineSDK |
|
synRepoProj |
|
| Synergy/DE Repository SDK |
synRepoProjSDK |
| Unit Test (.NET) | synNETUnitTest |
For example, the following command creates a new Synergy .NET console app named TestApp:
dotnet new synNETApp -n TestApp
| 4. | Once you have 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. |
| 5. | 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. For example, you can use “dotnet run” to run the built project, and with an SDK project, you can build on Linux with “dotnet build”. |
| 6. | For the final, deployable build, use the “dotnet publish” command, or for SDK projects, you can use the “dotnet build” command on Linux. See step 6 in Basic development steps in Visual Studio above. |
| 7. | 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 step 7 in Basic development steps in Visual Studio above. |
