Skip to main content

Technical configuration of the application

The archITekt platform uses its own application configuration mechanism, which is an extension of the standard .NET application configuration mechanism, making the configuration and deployment of the final application simpler.

Technical configuration mechanism:

  1. Enables central application configuration and use of variables and expressions in *.config files of .NET applications.
  2. Provides a built-in Health Check mechanism for application components.

Application configuration mechanism​

  1. Application configuration mechanism is based on the use of variables and expressions in the *.config files of the launched application.
  2. At the time of application launch, the values of variables and expressions are resolved in such a way that the internal .NET configuration mechanism already receives the correct values in the configuration files.
  3. The resolving of variables works only at the very beginning of the application launch, at the stage when the configuration has not yet been loaded by the internal .NET mechanisms, and does not interfere with the application configuration at a later stage.
  4. This means that changing the application's configuration requires restarting the application, just as when using the standard .NET configuration mechanism.

Using variables in the application​

Wanting to use a variable in the configuration file (*.config) we write its name using the notation {variable_name}

Below is an example of writing the ConnectionStrings section, which uses several variables to define connections to databases:

<connectionStrings>
<add name=”CONNECT_STRING” 
connectionString=”{common.connection.db_data}”
providerName=”System.Data.SqlClient” />
>add name=”VSFE.CONFIG_DB” 
providerName=”System.Data.SqlClient” 
connectionString=”{common.connection.db_config}” />
<add name=”ADConnectionString” 
connectionString=”{common.connection.provider_ad}” />
[..]

For some sections, the .NET configuration mechanism performs validation of the types and values entered in the configuration and the use of the braces mechanism is impossible (it ends up throwing an exception). In these special cases, we are forced to use an alternative way of saving the configuration - as attributes hidden in a comment to the element.

Below is an example of a Security.config section configuration using the comment mechanism:

<SecurityConfig RedirectWhiteList=””
ForceHttps=”false”
EnableBusinessLimitsFilter=”false”
RunDiagnosticsMethods=”true”
ErrorLevel=”Normal”
SecureCookies=”__RequestVerificationToken,ASP.NET_SessionId,.AspNet.ApplicationCookie”>
<!--VCONFIG EnableBusinessLimitsFilter = {www.param.enable_business_limits_filter}-->
<!--VCONFIG ForceHttps = {common.param.force_https}-->
<!--VCONFIG RunDiagnosticsMethods = {common.param.run_diagnostics_methods}-->
<!--VCONFIG ErrorLevel = {www.param.security_error_level}-->
</SecurityConfig>

In the above example, the attribute values will be replaced by the values of the variables stored in the comment tags starting with !--VSONFIG. For example, as indicated - the value of the attribute ForeHttps will be replaced by the value of the variable common.param.force_https

Variables and expressions​

Within the mechanism of configuration variables, we can use:

  1. variable values e.g. {common.param_forece.https}, whose value must be defined in the variable sources,
  2. a static property class call e.g. {#System.DateTime.UtcNow} - in this case, the current UTC date will be returned,
  3. expressions e.g. {#IsHttps({address}) ? 'bindingDlaHttps' : 'bindingDlaHttp'} - in this case the operation will be identical to that of the <condition>?&:<false> operator known from the C# language.

Below are practical examples of using the above notations:

Using a variable:

<appSettings>
<add key=”WINDOWS_AUTHENTICATION” value=”{www.param.windows_authentication}” />

For the above:

  1. www.param.windows_authentication - variable equal to "true"
  2. VSFE.NODE_NAME key value will be equal to "true"

Using static property from the code:

<appSettings>
<add key=”VSFE.NODE_NAME”
value=”{#VSoft.Framework.Environment.Environment.PhysicalMachineName}_VBP_WEB” />

For the above:

  1. VSoft.Framework.Environment.Environment.PhysicalMachineName - a static property in the code returning "MY_COMPUTER"
  2. the value of the VSFE.NODE_NAME key will be equal to "MY_COMPUTER_VBP_WEB".

Using the expression:

<client>
<endpoint address= ”http://invalid.url/” 
bindingConfiguration=”webHttp” 
binding=”wsHttpBinding” 
contract=”EntryPointService”’ 
name=”EntryPointService”>
  <!--VCONFIG: bindingConfiguration={IsHttps({specyfic.url})?’webHttp’:’webHttpSecure’}-->
  <!--VCONFIG: address={specyfic.url}/WebServices/EntryPoint.svc-->
</endpoint>

For the above:

  1. speciffic.url - variable with the value https://my.address.com
  2. the value of the expression IsHttps({specific.url}) is "true"
  3. the value of the attribute bindingConfiguration will be equal to webHttpSecure
warning

In the above example, initial formally valid values are given for the address and bindingConfiguration attributes, which will be exchanged for the target values when the configuration starts.

This approach is required because part of the configuration is checked by internal .NET code (unmanaged or managed) even before the value swap mechanism is started, and encountering invalid values in the swapped attributes will cause the program to stop at startup.

In this particular case:

  1. property adress is of type URI in the object-oriented configuration model does not tolerate the { character at the beginning of the text,
  2. property bindingConfiguration (or behavior) referring to other files must initially have values leading to existing entries in other parts of the configuration.

For list expressions, the possible functions to use are:

  1. IsHttps(...) - checks whether the specified address is SSL protected ("https://") or not ("http://"). Returns true if the address starts with "https://"
  2. IsEmpty(...) - whether the argument is resolvable to an empty string (null or whitespace). Works analogously to the .NET Framework method "String.IsNullOrWhiteSpace()"
  3. IsBraced(...) - whether the given argument is a recognized technical configuration key. Note: Experimental function.

The mechanism does not provide the ability for the developer to add his own functions.

Defining the values of variables​

The variables used for the configuration mechanism are read from:

  1. file [application name].exe.config.ini
  2. configuration database,
  3. appSettings section of the local configuration, In this case, the name of the variable will be the value of the key attribute, and the value of the variable will be the value of the value attribute.
  4. the connectionStrings section of the local configuration, In this case, the name of the variable will be the value of the "name" attribute, and the value of the variable will be the value of the connectionString attribute.
  5. environment variables - after setting the appSettings key VSFE.CONFIG_ENV_ORDER:
  • to the value "First" - then their value is more important than the values from the .ini
  • to the value "Last" - then the order of resolving the values is after the database source

If the VSFE.CONFIG_ENV_ORDER key is not set, then this variable provider is not enabled.

tip

The use of environment variables can also be enabled in code by setting the ConfigReplacer.EnvReplacerOrder property very early.

  1. The above list has been sorted in the order of priority of the entries.
  2. Entries found in the source listed at a higher position overwrite the variable definition found in the source at a lower position.
  3. For example, if the variable environmentName is defined in the appConfig section and in the file [application name].exe.config.ini then the value from the file [application name].exe.config.ini will be used in the application.

Defining variable values in the .config.ini file​

If there is a file named "[application name].exe.config.ini" in the application directory (i.e., for example, for a Web application it will be the file "Web.config.ini") then the values of the variables will be taken from it.

An example of how to build a file:

; This file is in the form of the Key=Value line.
; In the standard .NET configuration (xml) you can use {Keys} and they will be substituted at the start.
; Keys with sensitive content (with passwords, etc...) should be placed in the [SecuritySensitive] section.
; Keys can also be in the form of .NET references, such as:
; {#System.Environment.MachineName} 
; {#System.AppDomain.CurrentDomain.BaseDirectory} -- the directory from which the program/module was started
; {#System.DateTime.Now} -- current date and time
; {#System.DateTime.UtcNow} -- current UTC date and time
studio.mode = InProc
studio.winAuth = true

; connection to the database
[SecuritySensitive]
common.connection.db_config = data source=RBABICZ10\SQLEXPRESS;initial catalog=ARCHITEKT_DEMO_191_CONFIG;User Id=xxx;Password=xxx;MultipleActiveResultSets=True;
[SecuritySensitive]
my.secrect.password = very_secret_123

By placing the values of the variables in the SecuritySensitive sections in the *.ini file, we cause their values not to be written to the log.

Defining the values of variables in the database​

An application using the configuration mechanism retrieves the values of variables from the database if a connection to the database named VSFE.CONFIG_DB is defined in the connectionStrings section.

If such a connection exists, then the definition of variables from the CONFIG_KEYS table is loaded.

The table is set up through standard VSoft archITekt scripts. Its individual columns:

  1. CK_KEY - stores the name of the variable.
  2. CK_VALUE - stores the value of the variable
  3. CK_NODE_NAME - if it is empty, then the value of the variable is valid for all components of the environment. If not, then the value of the variable is valid on components with the name indicated in this column (you can use regular expressions, such as ^MyServer_.*$ )
  4. CK_SENSITIVE - a value of 1 means that the variable is sensitive; it works identically to the SecuritySensitive attribute in the *.config.ini file (the variable is hidden from key listings). The flag does not encrypt the value - an encrypted value (ENC1:) is decrypted regardless of the flag. The column is set by the installation scripts - see Sensitive keys
  5. CK_DESCRIPTION - description of the meaning of the variable
  6. CK_PUBLIC - a value of 1 means that the variable will appear in the edited view ENV_CONFIGURATION
tip

Wildcards can be used in the CK_NODE_NAME column, i.e., for example, writing the node name as DB_* will cause the variable value to be visible on all nodes whose name begins with DB_

The ENV_CONFIGURATION view storing part of the variables is used when you want the end system administrator to narrow the view of only part of the variables for configuration. In that case, you should arrange with him to use this view and not directly from the CONFIG_KEYS table.

For the purposes of installation/upgrade scripts, stored procedures have been provided:

  1. EnsureConfigKey - which creates a new entry in the database and updates the description for existing keys (does not change the value of a key if one already exists)
  2. GetConfigKey - which returns the value of a given key
  3. SetConfigKey - which sets the value of a key in the database

Defining values in appConfig and connectionString sections​

The entries in the appConfig and connectionString sections are treated as variables that can be used in the technical configuration mechanism.

  1. In the case of appConfig, the name of the variable is the "key" attribute, the value is the "value" attribute.
  2. For connectionString, the variable name is the "name" attribute, the value is the connectionString attribute.

Restrictions​

The mechanism works only for the main app.config / web.config file and the files that are its children. It does not support *.config files that are independent of the app.config / web.config file, such as:

  1. NLog.config, when loaded by NLog's internal mechanism and enabled in the application with:
<nlog>
<include file=”${basedir}/Configuration/Environment/NLog.config” />
</nlog>
  1. Web.Config files located in subdirectories of the web application. In this case, in a given subdirectory, all sites use the basic .NET configuration mechanism with unresolved variable values.

Variable naming convention​

In order to keep variable names used in technical configuration in order, it is suggested to use the following naming convention:

{component name}.{entry type}.{entry name}

Individual fields should be filled with values:

  1. component name: the name of the component in which the configuration variable is used. If the variable is used in several components, common should be specified as the component name,
  2. component type: the type should be correlated with what the variable stores. The most commonly used variable types are: url, restapi, connection, id, cert, param. When using a specific, unique, type of variables, param should be specified as the type,
  3. entry name - the name should clearly describe what the variable is used for.

In addition, taking care of ease of configuration, care should be taken to provide a clear comment in the field CK_DECRIPTION what the key is used for, if necessary, also what values are necessary to enter.

Health Check mechanism​

The archITekt platform has a built-in health check mechanism.

The mechanism:

  1. causes cyclic reporting by individual components of information on whether they are working stored in the database,
  2. enables from the level of the central database to run self-diagnostic functions in components at different levels of detail.

NODES table​

The mechanism works on the basis of the NODES table located in the configuration database, which is created using standard archITekt scripts.

The NODES table contains columns:

  1. N_NAME - the name of the NODE, a value that is configured in the appConfig section in the VSFE.NODE_NAME key. The value should be unique for each NODE.
  2. N_STATUS_AUTO - displays information about the life of the component in a clear way. The value is calculated from the fields N_STATUS, N_STATUS_DT
  3. N_COMMAND_INPUT - field into which you can enter command data to run diagnostics.
  4. N_COMMENT - information about the node. Text can be entered into this field by the user, they are not modified in any way by the component.
  5. N_HOSTNAME - the name of the host on which the component is installed.
  6. N_IP - the IP address of the first network interface of the computer on which the component runs.
  7. N_PID - the process number of the running component.
  8. N_START_DT - the startup time of the component. Updated during the next (re)start of the component.
  9. N_PASSIVE_URL - component access address for web components.
  10. N_DIR_PATH - network path leading to the component's binaries directory.
  11. N_STATUS - information about the operation status of the component.
  12. N_STATUS_DT - the time when the component last updated the table.

Cyclic component life confirmation​

The application components periodically update information about their status in the NODES table by updating the N_STATUS and N_STATUS_DT fields. Based on this, the value of the N_STATUS_AUTO field is calculated.

Controlling the operation of the health check mechanism​

The health check mechanism is controlled by the settings of the configuration keys.

Key nameDescriptionAction in case of no key
VSFE.NODES_DBSetting this key in connectionStrings, will cause the NODES table to be searched for in the indicated database.Failure to set the key will result in the use of a connection from the VSFE.CONFIG_DB key
VSFE.NODE_NAMEThe name of the node, must be unique for each component of the application, otherwise errors will be regularly reported in the logs regarding nt duplicate node detection.Failure to set the key will disable the health check mechanism for the component..
VSFE.POLLING_INTERVALThe key specifies every how many seconds in the to start the mechanism reporting the current state of the node NODES table. Attempt to communicate with the node database (default is 30).If the key is not set, the default setting will be used - the mechanism will report every 30 seconds.
VSFE.CONFIG_RECHECK_MODEThe mode of reporting when the value of the configuration keys changes.Acceptable values: NONE, REPORT_USED_CONFIG_ONLY, REPORT_ALL. No key setting will result in the use of the default setting - REPORT_USED_CONFIG_ONLY.

Values for the VSFE.CONFIG_RECHECK_MODE variable:

  1. A value of REPORT_ALL means that a change in any configuration key (even one not used in .config files) causes reporting.
  2. A value of REPORT_USED_CONFIG_ONLY causes a reaction only when the value of the key used by the .config files has changed.

Running the diagnostics procedure

  1. Running the diagnostics procedure is done by updating the NODES table for the selected node - enter the value "DIAG n" in the N_COMMAND_INPUT column, where n is the number to be passed to the registered diagnostics factories
  2. VSoft.Framework.Environment.Diagnostics.IDiagnosableFactory.Create
  3. The results of the created diagnostics procedures will be recorded in the technical logs of the component.
  4. Custom procedures for responding to entries in the N_COMMAND_INPUT column can be recorded in EnvNode.CommandHandlers. The prefix "DIAG" is one such registration.

SMTP configuration - common.param.smtp_​

The following options need to be configured in order to be able to send emails. All SMTP mail server settings have a common core name common.param.smtp_

List of variables:

Variable nameDefault valueDescription
common.param.smtp_serverSMTP mail server address
common.param.smtp_port25SMTP mail server address
common.param.smtp_securityAutoConnection security method
common.param.smtp_ignore_certificate_errorsNoneChange not recommended. Allows you to ignore some server certificate errors.
common.param.smtp_usernameUser name for the SMTP service. Used when common.param.smtp_authentication is set to UserPassword
common.param.smtp_passwordUser password for the SMTP service. Used when common.param.smtp_authentication is set to UserPassword
common.param.smtp_authenticationUserPasswordSMTP server authentication mode. When the key value is empty the system will use the default value UserPassword. Valid values: UserPassword- User name and password are required to authenticate. Default value. Anonymous- Anonymous access. Server does not require authentication.

Variables without a specified default value are mandatory to configure.

tip

The variables common.param.smtp_server, common.param.smtp_username and common.param.smtp_password are sensitive by definition - their values given in the configKeys parameter of the installation scripts are stored encrypted and are not written to the logs. See: Sensitive keys.

common.param.smtp_server​

Specifies the DNS address of the SMTP mail server, e.g. "mail.contoso.com".

  1. Mandatory value.
  2. No default value.

common.param.smtp_port​

Specifies the port of the SMTP service.

  1. The default value is 25.
  2. The default value does not depend on other settings.
  3. The default value will be set when the variable has an empty value.
  4. An invalid key value will cause a program execution error (exception).

common.param.smtp_security​

Set the security of the connection to the SMTP server.

  1. The default value is Auto.
  2. The default value will be set when the variable has an empty value
  3. An invalid key value causes a program execution error (exception).

The variable accepts values from the enum type VTS2.Core.Blocks.Output.SmtpConnectionSecurity

ValueDescription
NoneUnsecured connection.
StartTlsThe application requires the server to support the STARTTLS protocol extension. In the initial phase, the connection will not be secured.
StartTlsWhenAvailableThe application will use the STARTTLS extension if it is supported by the SMTP server. If not, the connection will remain unsecured and emails will be sent without encryption. Depending on the server configuration, it works as StartTls or as None.
tip

The available options are a copy from SecureSocketOptions in MailKit v2.9. More information may be available documentation on the project website: http://www.mimekit.net/.

smtp_ignore_certificate_errors​

tip

Changing the default value is not recommended or even discouraged.

The setting allows you to ignore certain SMTP server certificate configuration errors.

  1. The default value is None.
  2. The default value will be set when the variable has an empty value.
  3. An invalid key value causes a program execution error (exception).

The available values come from the enum type VTS2.Core.Blocks.Output.IgnoreCertificateErrors

ValueDescription
NoneThe only recommended value for this key. Any other in practice reduces the security level of the connection to zero.
AllThe application will ignore all errors related to the certificate. The equivalent of setting all flags.
RemoteCertificateNotAvailable(flag) The certificate was not available.
RemoteCertificateNameMismatch(flag) The certificate was published for a different server address than the connection address defined in the common.param.smtp_server key.
RemoteCertificateChainErrors(flag) The certificate could not be validated correctly. This usually means that a trusted certificate (e.g. belonging to a certification authority) was not found in the certificate's trust chain. Typically, the error affects working certificates (e.g. self-signed.).

You can combine two or more flagged values by separating them with a comma, for example:

RemoteCertificateNameMismatch, RemoteCertificateChainErrors will allow you to connect to a server that identifies itself with a working certificate issued for a different address than the connection address.

tip

The values of the RemoteCertificate... flags correspond directly to the values of SslPolicyErrors. More information about when and why these errors are reported may be available on Microsoft's website.

common.param.smtp_authentication​

The authentication mode for the SMTP server.

  1. The default value is UserPassword.
  2. The default value will be set when the variable has an empty value.
  3. An invalid key value causes a program execution error (exception).

The variable accepts values from the enum type VTS2.Core.Blocks.Output.SmtpAuthentication

ValueDescription
UserPasswordAuthentication using the username and password specified in the common.param.smtp_username and common.param.smtp_password variables.
AnonymousAllows access without logging in SMTP protocol when the server does not require authentication.

common.param.smtp_username​

The user name to connect to the SMTP server.

  1. Value used when common.param.smtp_authentication is set to UserPassword
  2. No default value.

common.param.smtp_password​

The password of the user to connect to the SMTP server.

  1. Value used when common.param.smtp_authentication is set to UserPassword.
  2. No default value.

See also​

Database Upgrader

Troubleshooting

Management of the installed application