Synergy projects, solutions, and files

This topic includes the following sections:

• Project files and folders
• File types and build actions
• Builds
• Output folders

 

When you develop with Visual Studio, Synergy DBL code files are contained in Synergy projects, and projects are contained in Visual Studio solutions.

• Projects collect all files, settings (compiler settings, environment variables, etc.), data connections, and references needed to build a Synergy program or library. Projects supply this information to the Visual Studio build system (MSBuild) at build time, and they enable Visual Studio’s IntelliSense features to work for Synergy DBL files.
• Solutions collect related projects and enable you to work with these collected projects as a whole. For example, projects in a solution can be built together (or they can be built separately).

• Generally, you will create a project for each program and library that is part of your application, and you will put all projects for an application in a single solution. To create traditional Synergy or Synergy .NET programs, use Synergy projects. See Synergy/DE project templates for information on the types of Synergy projects you can create, and note that you can use the .NET CLI to create and build projects for .NET 6 and higher. See Developing for .NET 6 or Higher for more information.

Unlike projects, solutions are not language specific. A solution can contain a mix of Synergy and non-Synergy projects, it can contain a mix of traditional Synergy and Synergy .NET projects, and projects in a solution can share resources. For example, if you use the same core code for a traditional Synergy application and a Synergy .NET application, you can create a solution with a traditional Synergy project and a Synergy .NET project that both use that code, as illustrated in figure 1 below. In this configuration, the shared code would be included in both projects that use it (at least one project would add it as a link).

Note, however, that Synergy .NET projects cannot reference traditional Synergy projects and libraries, and vice versa. So if you have a solution with both traditional Synergy and Synergy .NET projects, you can build the projects together, but you probably won’t be able to deploy them as a single application.

1. A solution can have different types of projects, and different projects can share source files.

For more information on Synergy .NET projects and how they relate to .NET assemblies, see Projects for Synergy .NET.

Project files and folders

Each Synergy project consists of a project folder, a project file (or files), and other associated files and subfolders—just like projects for other languages in Visual Studio, so see Visual Studio documentation for general information on projects. There are, however, a few differences with Synergy projects:

• Synergy project files (.synproj and .synproj.user) are similar to project files for other languages (e.g., C#), but they do contain some Synergy-specific settings. These settings are undocumented because they are controlled by options in the Visual Studio interface. See Setting link priority for traditional Synergy in Visual Studio for an exception to this rule, and see Builds below for information on setting project and build settings in MSBuild project and target files.
• Strong prototyping is used automatically when developing in Visual Studio, so prototype files (.dbp), which are unique to Synergy, are generated and used behind the scenes by Visual Studio and SDI.
• A file without an extension cannot be compiled.
• By default, files with the .dbl or .dbc extension are compilable files, and files with the .def or .rec extension are content files. See File types and build actions below for more information.
• Synergy .NET files that have been built in debug mode reference .pdb files, which have symbolic debug information. For information on .pdb files, see Visual Studio documentation.

Additionally, note the following:

• Visual Studio projects are not designed to work over mapped drives (i.e., network shares via Samba, NFS, etc.), so keep all files for Visual Studio projects local. This includes repository and .INCLUDE files.
• All project files, except .synproj.user files (which store machine-specific settings), should be included in source control.
• For information on improving performance by excluding SDI files and file locations from virus scanning, see www.synergex.com/synergy-dbl-integration.
• Visual Studio cannot open unencoded (plain text) files with ASCII escape sequences. Attempting to open an unencoded file in Visual Studio will either cause Windows to prompt you for an application to use with the file (e.g., “How do you want to open this file?”) or, if there is a default application associated with the file extension, it will open the file in that application.
• You may be able to improve Visual Studio’s performance for large source files when editing or using Find All References by clearing the “Auto-detect UTF-8 encoding without signature” option on the General options dialog box (Tools > Options > Text Editor > General).
• When you add an assembly reference in Visual Studio, the HintPath setting is rooted to $(ProgramW6432) if the assembly is in Program Files\Common, or it is rooted to $(MSBuildProgramFiles32) if the assembly is in Program Files (x86)\Common. This makes projects with references to assemblies in these locations more portable between systems.

File types and build actions

By default, Visual Studio treats Synergy project files with the .dbl and .dbc extensions as compilable Synergy code files, it treats Synergy project files with .def and .rec extension as content (non-compilable) files, and it treats files with the .rps, .scm, .schema, .sdl, and .sch extensions in repository projects as repository schema files. You can customize this by

• adding Synergy code file or content file extensions to the “Additional Compile File Extensions” and “Additional Content File Extensions” fields in the IntelliSense dialog box for the Synergy DBL text editor (see IntelliSense page of Visual Studio text editor options). Or for repository Schema files, use the File Extensions window of Visual Studio Options (see Repository schema files and colorization).
• changing the Build Action for an individual file as illustrated in figure 2 below. (Right-click the file in Solution Explorer, select Properties from the context menu, and change the Build Action setting in the Advanced area of the Properties window.)

A source file’s Build Action setting determines how it will be treated at build time. You can set the Build Action for a file in a Synergy project to one of the following (files with unrecognized extensions default to None):

• Compile. The file is compiled and added to the build output. (This setting is not supported for files that have no extension. A file without an extension cannot be compiled.)
• Content. The file is copied to the project output (without being processed).
• Embedded Resource. The file is processed by a specified tool and the results are embedded in a manifest resource exclusive to the assembly. This setting is ignored for traditional Synergy projects.
• None. The file is ignored by the build. It is not processed or included in the project output.
• Page. The file is compiled as XAML and is embedded in a shared assembly manifest resource. This setting is for WPF projects, which are no longer supported. It is ignored for all other project types.
• Resource. The file is added as a linked resource (.resx). This setting is for WPF projects, which are no longer supported. It is ignored for all other project types.
• ApplicationDefinition. The file (which must be a XAML or class file) is used to define the application. This setting is for WPF projects, which are no longer supported. It is ignored for all other project types.

2. Changing the Build Action for a specific source file in a project.

Builds

When you build a project in Visual Studio, Visual Studio automatically runs a Synergy compiler (and linker for traditional Synergy) behind the scenes to generate program and library files. For traditional Synergy, these are ELBs and DBRs (.elb and .dbr files by default). And for Synergy .NET, these are executables and DLLs (.exe and .dll by default). Additionally, a solution or project can be built to run as a 32-bit or 64-bit application or library, it can be built in debug or release mode, and it can be built to target an earlier version of Synergy/DE.

These and other aspects of project and solution builds are controlled by project settings and configuration/platform settings in Visual Studio (see Build page of Visual Studio project properties and Configurations, platforms, and profiles). But you can also control them with build settings and targets in project files (.synproj) and in MSBuild .props and .targets files. For example, if you want extensions to be in all capital letters for all files built for a traditional Synergy solution, you could add the following to a Directory.Build.Props file in the root directory for the solution:

<?xml version="1.0" encoding="utf-8"?>

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

<PropertyGroup Condition="'$(OutputType)'=='mainline' OR '$(OutputType)'=='traditional'">

<TargetExt>.DBR</TargetExt>

</PropertyGroup>

<PropertyGroup Condition="'$(OutputType)'=='elb'">

<TargetExt>.ELB</TargetExt>

</PropertyGroup>

<PropertyGroup Condition="'$(OutputType)'=='olb'">

<TargetExt>.OLB</TargetExt>

</PropertyGroup>

</Project>

With the above settings, when the OutputType for a project is set to “mainline” or “traditional”, the file extension for the built file will be .DBR. And if the OutputType for a project is “elb” or “olb”, the extension for built the built file will be .ELB or .OLB.

The next example, however, applies to all projects in a solution if it’s added to a Directory.Build.Props file in the root directory for the solution. For example, when using dotnet publish, it uses the win-x64 platform setting for all project dependencies in the solution:

<?xml version="1.0" encoding="utf-8"?>

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

<PropertyGroup>

<RuntimeIdentifiers>win-x64</RuntimeIdentifiers>

</PropertyGroup>

</Project>

Keep in mind that a setting in an MSBuild property or target file may be overridden by a setting in a project file or a different MSBuild file. Settings in target files (e.g., Directory.Build.Targets) typically override settings in project files (.synproj files), while settings in MSBuild property files (e.g., Directory.Build.Props) do not. This is because MSBuild loads property files before loading the project, but it loads target files after loading the project.

For more information on settings in project files and MSBuild property and target files, see Microsoft documentation (e.g., MSBuild Properties).

Output folders

When a project or solution is built, the output path, which is set on the Build page of project properties, determines where built files for the projects will be located. Build page settings are specific to a platform/configuration combination, so there can be as many output folders as there are platform/configuration combinations. For example, if you have a traditional Synergy solution with Debug, Release, and Test solution configurations and x86 and x64 solution platforms, the default output path settings for these configurations and platforms would result in the output folders shown in figure 3.

3. Output folders for a solution with traditional Synergy projects.

And if you have a Synergy .NET project with Debug, Release, and Test configurations and the Any CPU platform, the default output path settings for these would result in the output folders shown in figure 4.

4. Output folders for a solution with Synergy .NET projects.

For more information see Configurations, platforms, and profiles.