This topic includes the following sections:
- Notes on ELBs and OLBs
- Precedence for environment variables and references
- Environment bleed in Visual Studio
When developing Synergy applications and libraries in Visual Studio, you can set environment variables that will be used by Visual Studio development tools (e.g., IntelliSense and MSBuild) and at runtime.
The location of an environment variable setting determines what it is used for.
|
Location |
Written to... |
Scope for development tools (including builds) |
Runtime scope |
|---|---|---|---|
| Environment | System environment | System-wide | System-wide |
| synergy.ini/synuser.ini (Windows only) | N/A (settings remain in synergy.ini or synuser.ini) | All Synergy projectsa | All Synergy applications in the current process |
|
Environment Variables page of Visual Studio project properties |
Project file (.synproj) | Project-specific (with some exceptions; see Environment bleed in Visual Studio below) | Not available |
| Common properties file (.props) | All projects in a solution that use the common properties file (with some exceptions; see Environment bleed in Visual Studio below) | Not available | |
|
Debug page of Visual Studio project properties (SDK-style projects only) |
N/A | Not available | Project-specific |
| App.Config / Runtime Settings page of project properties (Synergy .NET only)
See Runtime Settings page of Visual Studio project properties (Synergy .NET) for more information. |
App.Config
(renamed to ApplicationName.exe.config when the project is built) |
Not available | Application-wide for Windows desktop/server systems (.NET Framework and .NET 6 and higher only).b |
a. If an environment variable is used for builds, it is generally better to set it on the Environment Variables page or the Common Properties page of project properties than in synergy.ini or synuser.ini.
b. If an environment variable is shared by multiple Synergy .NET executables, we recommend setting it in one shared synergy.ini file and then setting the SFWINIPATH environment variable in the application configuration (App.Config) files to point to the synergy.ini file.
If an environment variable is set in more than one location, the setting used depends on location precedence and whether the Synergy runtime is involved (see Precedence for environment variables and references below).
Notes on ELBs and OLBs
The Synergy tab of the Reference Manager dialog makes it easy to add references to ELBs and OLBs in a location specified by an environment variable.
For an ELB project, if you specify an environment variable in the “Output path” field on the Build page of project properties, that field will be used for any project references to the ELB project.
See Referencing ELBs and OLBs for more information on environment variables and ELBs and OLBs.
Precedence for environment variables and references
If an environment variable is set in more than one location, the location and whether the Synergy runtime is involved determines which setting is used.
Whenever the Synergy runtime is involved (e.g., at runtime or at build time for a Synergy/DE Repository project), the order of precedence is as follows, with settings higher in the list overriding settings lower in the list:
- Settings on the Runtime Settings page of project properties (Synergy .NET only)
- Settings in synergy.ini and synuser.ini
- References to repository projects (which override RPSMFIL, RPSTFIL, and RPSDAT in locations lower in this list)
- Settings on the Environment Variables page of project properties
- Settings on the Common Properties page of project properties
- System-level settings
When using Visual Studio or MSBuild without involving the Synergy Runtime, the order of precedence is as follows, with settings higher in the list overriding settings lower in the list:
- Settings on the Debug page in project properties (SDK-style projects only)
- References to repository projects (which override RPSMFIL, RPSTFIL, and RPSDAT in locations lower in this list)
- Settings on the Environment Variables page of project properties
- Settings on the Common Properties page of project properties
- System-level settings
- Settings in synergy.ini and synuser.ini
Environment bleed in Visual Studio
An environment variable set on the Environment Variables page is specific to the project it is set in, and an environment variable set on the Common Properties page is specific to projects that use the common properties file it is set in. This is true at runtime and for MSBuild when it is run from the command line. It is also generally true for Visual Studio development tools and builds in Visual Studio, but there are exceptions.
In Visual Studio, an environment variable set on one of these pages becomes part of the solution’s environment in Visual Studio when a project that has the setting is opened or built. At that point, the environment variable setting is no longer specific to a project or set of projects that use a common properties file; it is instead available to all projects in the solution. For example, if MY_ENVVAR is set on the Environment Variables page for a project named ProjectA, that setting will be available to other projects in the solution as soon as ProjectA is opened or built in Visual Studio. This is called “environment bleed” and can cause the following:
- A global setting may be unexpectedly overwritten at build time. If a project-specific setting overrides a setting in synergy.ini or synuser.ini, that override may be used for other projects in the solution. For example, if a project-specific MY_ENVVAR setting for ProjectA overrides a MY_ENVVAR setting in synergy.ini, that override will be used for other projects in the solution once ProjectA is opened or built.
- A project that builds in Visual Studio may fail to build from the MSBuild command line. This happens when environment bleed supplies a missing environment variable setting. The build will work in Visual Studio (because of environment bleed), but when MSBuild is run from the command line, the project-specific environment variable will be available only to the project it is set in. For example, if ProjectB relies on the MY_ENVVAR setting, but MY_ENVVAR is set only for ProjectA, the solution may build without a problem in Visual Studio, but if you attempt to build it with the MSBuild command line, ProjectB will not build.
You can eliminate environment bleed by using Common Properties to set all environment variables used in your solution and including the common properties file in all projects in the solution.
