Synergy projects, solutions, and files
This topic includes the following sections:
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 Visual Studio 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 a traditional Synergy or Synergy .NET program, use a Synergy project. See Synergy/DE project templates for information on the types of Synergy projects you can create.
Unlike projects, Visual Studio solutions are not language specific. A Visual Studio 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.
For more information on Synergy .NET projects and how they relate to .NET assemblies, see Visual Studio Projects for Synergy .NET.
Each Synergy project consists of a project folder, a project file (or files), and other associated files and subfolders. Synergy projects have a fairly standard set of files and folders, so see Visual Studio documentation for general information on projects. There are, however, a few differences:
- Synergy project files (.synproj and .synproj.user) are similar to project files for other languages (e.g., C#), but they do contain different settings (XML tags). These settings are undocumented because they are controlled by options in the Visual Studio interface. (For an exception to this rule, see Setting link priority for traditional Synergy in Visual Studio.)
- 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).
By default, Visual Studio treats Synergy project files with the .dbl and .dbc extensions as compilable files, and it treats Synergy project files with the .def or .rec extension as content (non-compilable) files. You can customize this by
- adding 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 for more information.
- 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 only. It is ignored for all others.
- Resource. The file is added as a linked resource (.resx). This setting is for WPF projects only. It is ignored for all others.
- ApplicationDefinition. The file (which must be a XAML or class file) is used to define the application. This setting is for WPF projects only. It is ignored for all others
When you build a project, Visual Studio automatically runs a Synergy compiler (and linker for traditional Synergy) behind the scenes to generate program and library files. These are ELBs and DBRs for traditional Synergy, or .exe and .dll files for Synergy .NET.
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. Project and solution builds are controlled by some project settings and configuration/platform settings. See Build page of Visual Studio project properties and Configurations, platforms, and profiles for more information.
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.
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.
For more information see Configurations, platforms, and profiles.