Imaging.Common.Configuration 1.1.1

Imaging.Common.Configuration(Use ICC instead for short below) gives the application, no matter console app or web app or desktop app, the ability to consume pre-defined configuration files automatically as per its running environment(Dev, QA or Production).
The typical scenario is that, the developer delivers appplication that contains some configuration files for Development envrionment, system admin deploys the application to QA/Prod envrionment. During deploying, system admin changes the configuration file to get the application adapted to QA/Prod envrionment, such as the database connection string. The change action may lead in humman error and higher time costs that would be excpect as shorter as possible. ICC will eliminate the configuration file change during deploying. All configuration values for specified environment will be treat as code managed in development action and be well defined for every objective evvrionment. So ICC introduces a no humman error, no time costs configuration procedure during deploying, and it is can be considered CD(continuous deployment) ready for Devops.

Get Started

Prerequisite

The first step is mark the environment on each server that hosts your applications. In general, you can simply create a file as D:\services\devops\ImagingDevOps.properties.

# Envrionment may be DEV, DEVELOPMENT, QA, PROD, PRODUCTION etc. any flag string you prefer.
ENV=DEV 
# Machine name is the machine or the container that runs your application
MACHINE_NAME=machine_name_or_any_running_container_name
# Mode is used in some specific scenarios. 
# The typical one is for setting a all new envrionment. 
# You can set mode to testing(any flag string you prefer) when you work on the preparing tasks for all new envrionment, 
# this will provide flexible for testing purpose so that ICC could consume the testing/pre-online configuration values. When everything is done, set it blank, 
#ICC will switch to consume the normal env/machine configuration value. 
#Mode is optional.
MODE=

Default usage

IIC works in its default setting if there is other no custom trick.

1. Installs Imaging.Common.Configuration to your application.
2. Creates app configuration files with file name in appsettings_{ENV}_{MODE}.yml or appsettings_{MACHINE_NAME}_{MODE}.yml format under appRootfolder/ImagingConfig folder, _{MODE} is optional. e.g. appsetting_Jim_PC.yml, Jim_PC is machine name, appsetting_DEV.yml, DEV is environment name. Json and yml are supported for now.
3. Uses IIC in your code.

// init ICC
var configuration = new ConfigurationBuilder()
               .AddImagingConfiguration()
               .Build();
// retrieve the value from a key
var config1 = configuration["Yml_3:Yml_3_1"];

4. Builds your project with copping configuration files defined previous step.
5. You can deploy the applicaiton to any envrionment without any configuration changes now.

Note, the value of a key from machine level configuraiton file will override the value of the same key from env level. If mode is specified, mode configuration file will be used. Mode is optional.

Advance usage

Commonly, there are two ways to tell IIC in which envrionment the application is running.
The first one is to use envrionment file and define envrionment label in it, the default path is D:\services\devops\ImagingDevOps.properties. You can also specific the Envrionment file path.
Another way is to use environment variables, the default prefix is ImagingDevOps_. For instance, ImagingDevOps_MACHINE_NAME. Also, you can specific the prefix. Note, IIC will read envrionment label from Envrionment file first, and then read from Environment Variables. So, environment variable will override envrionment file.

Custom Envrionment file and Environment Variables prefix

In some cases, you may not like the default environment file and environment variables prefix. ICC provides two way to use your own environment file and environment variables prefix.

• In coding. Builds option when initializing ICC.

var configuration = new ConfigurationBuilder()
               .AddImagingConfiguration(buildOptionAction: option => {
                   option.EnvFile = "new path";
                   option.EnvVarPrefix = "new prefix";
                   // for now, json and yaml file are supported.
                   option.ConfigurationFileExtension = ".yml";
                   // you can specific a config file explicitly, the setting will override all above settings
                   option.SpecifiedConfigFile = "A specific config file path";
               })
               .Build();

• Use meta file ImagingConfiguration.meta, the file can be put at any direct subfolder of app root folder. CII will detect the file name ImagingConfiguration.meta in all subfolders, once the file name is found, the contained folder will be considered as the configuration root folder.

# ImagingConfiguration.meta demo
ENVIRONMENT_FILE=env file path
ENVIRONMENT_VAR_PREFIX=env var prefix
CONFIGURATION_FILE_EXTENSION=.yml
# you can specific a config file explicitly, the setting will override all above settings
SPECIFIED_CONFIG_FILE=A specific config file path

Note, the meta file is the recommended way to do customizing. SpecifiedConfigFile is the highest priority for IIC to consume. It will ignore all env/machine configuration files so it is for testing or some special purpose.

Legacy support

Microsoft introduces a new Configuration Builder functinality starting from .NET Framework 4.7.1 that enables tradional application based on .NETFX to enjoy modern configruation system.
ICC creates its own builder extended KeyValueConfigBuilder to provide the support for leagcy configuration file known as app.config and web.config.

Install

Install-Package Imaging.Common.Configuration.LegacySupport

Note, if nuget cannnot resolve Microsoft.Configuration.ConfigurationBuilders, you need to install it manually.

Install-Package Microsoft.Configuration.ConfigurationBuilders.Base -Version 2.0.0-beta

Typical usage

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, System.Configuration, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>
  <configBuilders>
    <builders>
    
      <add name="ImagingBuilder" envFile="" envVarPrefix="" specifiedConfigFile="" imagingConfigurationFileExtension="" mode="Expand" tokenPattern="\$\{(\S+)\}"  type="Imaging.Common.Configuration.LegacySupport.ImagingLegacyConfigurationBuilder, Imaging.Common.Configuration.LegacySupport, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
    </builders>
  </configBuilders>
  <appSettings configBuilders="ImagingBuilder">
    <add key="rr" value="qq" />
    <add key="Expand1" value="${Expand_key1}" />
    <add key="Expand2" value="${Expand_key2}" />
    <add key="Expand_4_1" value="${Expand_key4:Expand_key4_1}" />
    
    <add key="Strict_key1" value="~~~~~" />
    <add key="Strict_key2" value="~~~~~" />
    <add key="Expand4" value="${Expand_key4}" />
    
  </appSettings>
<configuration>