Environment variables and Visual Studio development

This topic includes the following sections:

 

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. Note, however, that environment variable settings are not used at runtime for Synergy .NET applications on device platforms (UWP, Android, and iOS), except when set with the SETLOG routine or translated with the GETLOG routine. (With any type of Synergy .NET application, including device and Linux applications, SETLOG and GETLOG can be used for internal program communication and for opening files.)

The location of an environment variable setting determines what it is used for.

Environment Variable Setting Locations

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 processb
Environment Variables page of Project Designer

See Environment Variables page, Project Designer for more information.

Project file (.synproj) Project-specific (with some exceptions; see Environment bleed in Visual Studio below) Not available
Common Properties page of Project Designer

See Common Properties page, Project Designer for more information.

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
App.Config / Runtime Settings page of Project Designer (Synergy .NET only)

See Runtime Settings page, Project Designer (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. Not available for other platforms (e.g., UWP)c

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 Designer than in synergy.ini or synuser.ini.

b. For Synergy .NET, these settings are available only if the application is a Windows desktop/server application (not UWP).

c. 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).

The Synergy tab of the Reference Manager dialog enables you to easily add references to ELBs and OLBs in a location specified by an environment variable. And for an ELB project, if you specify an environment variable in the “Output path” field on the Build page of Project Designer, that field will be used for any project references to the ELB project. See Referencing ELBs and OLBs for more information.

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:

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:

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 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:

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.