High-Level Intrinsic Configuration

From OPC Labs Knowledge Base

Introduction

Many parameters of the software can be configured externally, without you having to write a specific code for it. The external configuration can be provided by multiple means, e.g. settings file (such as appsettings.json), environment variables, or Azure App configuration, and the functionality for it is already built-in to the components. This feature belongs to High-Level Configuration, and allows tweaking of component parameters for experiments, testing, and in production. Its main benefit is that the component parameters can be changed without somebody having to implement the code for it first, and/or without having to change and rebuild the application (which may come really handy if rebuilding the application is not an option for you, e.g. in many restricted production environments).

Where the configuration is read from (the "configuration providers") is determined by the default settings for your application host. For the usual hosts, these defaults are described here:

Since this is a standard mechanism used by software libraries and applications, you will be able to place the configuration settings for QuickOPC component alongside with configuration settings for other parts of the software.

By far, the most commonly used configuration provider will probably the JSON configuration provider, and you will place your configuration data into the appsettings.json or appsettings.Environment.json file (e.g. appsettings.Production.json).

Warning-icon.png

Warning: Configuration of the software is security critical. In some cases, secrets can be contained in the configuration. The configuration can also be modified to cause the software to output security sensitive information (e.g. in event tracing), or behave insecurely. You should always properly secure access to the configuration data used by the software, so that it cannot be read, or modified, by unauthorized actors.

Where is this used?

For example:

Changing the Configuration Providers

If your application requires a set of configuration providers different from the default, you can configure them differently through IHostBuilder interface by accessing the result value of StaticHost.GetHostBuilder() (StaticHost is in the OpcLabs.BaseLib.Extensions.Hosting namespace).

Of course, changing the configuration providers *does* require a code change; the configuration providers cannot be changed externally on an application that is already built.

Some applications built with QuickOPC already add configuration providers over those that are available by default. For example, the OpcCmd Utility adds the INI and XML configuration providers, and you can therefore use configuration files like these in the examples below with the OpcCmd utility.

Example: Adding and using the INI configuration provider

For example, to support a possibility to configure component parameters by key pairs from INI files, reference the Microsoft.Extensions.Configurations.Ini NuGet package, and add the following code at the beginning of your program:

StaticHost.GetHostBuilder().ConfigureAppConfiguration((hostingContext, config) =>
{
    IHostEnvironment hostEnvironment = hostingContext.HostingEnvironment;
    config
        .AddIniFile("appsettings.ini", optional: true, reloadOnChange: false)
        .AddIniFile($"appsettings.{hostEnvironment.EnvironmentName}.ini",
            optional: true, reloadOnChange: false);
});

The contents of the INI file which corresponds to the JSON example given earlier is as follows:

[OpcLabs.EasyOpc.UA.EasyUAClient:InstanceParameters:GdsEndpointDescriptor]
UrlString="opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer"

Example: Adding and using the XML configuration provider

For example, to support a possibility to configure component parameters by elements read from XML files, reference the Microsoft.Extensions.Configurations.Xml NuGet package, and add the following code at the beginning of your program:

StaticHost.GetHostBuilder().ConfigureAppConfiguration((hostingContext, config) =>
{
    IHostEnvironment hostEnvironment = hostingContext.HostingEnvironment;
    config
        .AddXmlFile("appsettings.xml", optional: true, reloadOnChange: false)
        .AddXmlFile($"appsettings.{hostEnvironment.EnvironmentName}.xml",
            optional: true, reloadOnChange: false);
});

The contents of the XML file which corresponds to the JSON example given earlier is as follows:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <OpcLabs.EasyOpc.UA.EasyUAClient>
    <InstanceParameters>
      <GdsEndpointDescriptor>
        <UrlString>opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer</UrlString>
      </GdsEndpointDescriptor>
    </InstanceParameters>
  </OpcLabs.EasyOpc.UA.EasyUAClient>
</configuration>