Environment Variables
Synergy applications frequently use environment variables (which we sometimes refer to as logical names) for various purposes, not least of which is to locate the application data files. These environment variables can be set in a variety of ways:
- SelfHostEnvironment
- appsettings.json
- synergy.ini (on Windows)
When you generate a self-hosting environment, one of the source files that gets created is SelfHostEnvironment.dbl. This file contains a class that has code to prepare the hosting environment for your web services application.
The class defines two main public methods named Initialize and Cleanup. Code in Initialize is used to initialize the environment during service startup, and code in Cleanup called during service shutdown.
The Initialize method, calls a private method named setLogicals, and the purpose of the code in that method is to generate a list of all of the environment variables that are used in the file specifications of all of the data files being exposed by your web services and check if each of them has a defined value in the environment. If any of the environment variables are found not to be set to a value then they are defined as pointing to the SampleData folder.
By the way, the name of the default folder is in turn defined by a user-defined token in the file UserDefinedTokens.tkn (in the main solution directory), like this:
<DATA_FOLDER>SampleData</DATA_FOLDER>
Note that if you generate unit tests then there is a generated file called UnitTestEnvironment.dbl that performs the same functions for your unit testing environment.
If you want to customize the way that the SelfHostEnvironment code sets environment variables then you can do so by adding a partial class and implementing one or more partial methods.
To add custom code to override the setting of environment variables, we suggest adding a source file named SelfHostEnvironmentCustom.dbl to the project, defining a partial class, and then implementing the partial method SetLogicalsCustom, like this:
namespace Services.Host
;;; <summary>
;;; Code to customize the self hosting environment.
;;; <summary>
public partial static class SelfHostEnvironment
;;; <summary>
;;; Code to set custom values for data access environment variables.
;;; This method will be called BEFORE environment variables
;;; are defaulted to the SampleData folder.
;;; <summary>
;;; <param name="logicals">A list of the environment variables to set.</param>
partial static method SetLogicalsCustom, void
required in logicals, @List<string>
proc
endmethod
endclass
endnamespace
As you can see, when we call your partial method we pass to you a collection of the names of all of the environment variables that are required for data file location. You can then add whatever code you need to determine the required values for each of those logical names, and use XCALL SETLOG to set those values.
The partial SetLogicalsCustom method is called before the standard setLogicals method, so if you set values for the environment variables, we will detect that a value has already been set and will not overwrite your value.
There are two other partial methods that can be used to customize the environment, as follows:
namespace Services.Host
public partial static class SelfHostEnvironment
;;; <summary>
;;; Code to perform custom initialization.
;;; This method will be called AFTER standard initialization code.
;;; <summary>
partial static method InitializeCustom, void
proc
endmethod
;;; <summary>
;;; Code to perform custom cleanup.
;;; This method will be called AFTER standard cleanup code.
;;; <summary>
partial static method CleanupCustom, void
proc
endmethod
endclass
endnamespace
The default environment that is created by the Harmony Core solution templates includes two files that can be used to store application settings. These files are:
Services.Host\appsettings.json
Services.Host\appsettings.Development.json
There is also code in the generated Startup class (Services\Startup.dbl) that:
- Sets environment variables based on all application settings.
- Makes the settings available as a service through the dependency injection container.
By default, the appsettings.json files are used to configure the verbosity ports that the Harmony Core service listens on, and the verbosity of the logging environment. The normal appsettings.json file contains:
{
"AppSettings": {
"EnvironmentVariables": {
"HARMONY_TOKEN_DURATION": "1",
"HARMONY_LOG_LEVEL": "2"
}
}
}
While the appsettings.Development.json contains:
{
"AppSettings": {
"EnvironmentVariables": {
"HARMONY_TOKEN_DURATION": "1",
"HARMONY_LOG_LEVEL": "6"
}
}
}
Harmony Core, like many .NET Core applications, uses configuration settings in appsettings.json files. The Startup class that’s generated for a Harmony Core web service includes code that processes the EnvironmentVariables section of the appsettings.json file and sets actual environment variables in the hosting applications runtime environment.
The settings file that is used is determined by the value of the environment variable ASPNETCORE_ENVIRONMENT, which is set in the Services.Host Visual Studio project to a value of Development, thus causing the appsettings.Development.json file to be used.
When your service is started outside of the Visual Studio environment, this environment variable would not be present (unless you set it yourself), and so the appsettings.json file would be used.
If you change the content of the appsettings.json file while your service is running, the ASP.NET Core configuration system will detect the change and will update the application settings on the fly.
For more information about environments, refer to Microsoft’s Use multiple environments in ASP.NET Core, and for more information on appsettings.json files, see Microsoft's Configuration in ASP.NET Core.
On Windows systems, if the environment variable SFWINIPATH is set in your environment before the Synergy Runtime library is loaded for your web service, then the settings in the [synergy] and [colors] sections of the specified synergy.ini will be available for use as environment variables in your service.
Bear in mind though that you can't rely on either of the two mechanisms described above to set the value of the SFWINIPATH environment variable, as both are implemented by running Synergy code, so the Synergy runtime has already been loaded and so it is already too late to set SFWINIPATH and process the synergy.ini file.