NamespaceSystemLibrary.Common.Framework SystemLibrary.Common.Framework.Net.dll

Loads and reads configuration files (.xml, .json, or .config), applies transformations, and decrypts encrypted properties.

Configs can be placed in:

~/*.json, ~/*.xml, ~/Configs/**, ~/Configurations/**, or appended to appsettings.json.

Transformations use the ASPNETCORE_ENVIRONMENT variable.

Set ASPNETCORE_ENVIRONMENT in:

- launchSettings.json (IIS Express/Kestrel)

- web.config (IIS/IIS Express)

- mstest.runsettings (unit tests)

- command-line --configuration (executables)

Remarks

X

Config is a singleton, loaded once.

See documentation for EnvironmentConfig.Name for environment setup examples.

An encrypted property such as ApiToken {get;set;} can be automatically decrypted by adding a matching property ApiTokenDecrypt {get;set;} or mark it with [ConfigDecryptAttribute].

Environment variables like UserName apply only when reading appSettings, not custom config files.

WARNING: Generic type T cannot be a nested class.

Config<T>

public abstract class Config<T> where T : class

Inheritance

object

Config<T>

EnvironmentConfig<T, TEnvironmentNameEnum>

Type Parameters

Name	Description
T	T is the class inheriting Config<>, also referenced as 'self'. Note that T cannot be a nested class

Examples

X

• Create new file '~/TestConfig.json'
• Can also be placed under ~/Configs/ or ~/Configurations/

{
    "Name": "Hello World",
    "Number": 1234,

    "Options": {
        "Url": "https://....",
    },
    "ValidPhoneNumbers": [0,1,2,3]
    "password": "/HjLI26feCvCwaBOmXfu6ZFK1KLR33YbAdDZIlzuM5I=",
}

• Create C# class with same name as your newly created json file and inherit Config<>:

public class TestConfig : Config<TestConfig> 
{
   public string Name { get; set; }

   public int Number { get; set;}

   public ApiOptions Options { get; set; }

   public int[] ValidPhoneNumbers { get; set; }

   public class Password { get; set; } // Contains encrypted value
   public class PasswordDecrypt { get; set; } // Contains decrypted Password at runtime
}

public class ApiOptions 
{
    public string Url { get; set; }
}

Usage:

var testConfig = TestConfig.Current;
var name = testConfig.Name;
// name is now Hello World

Add transformation per 'environmnet' to our newly created TestConfig.json

• Add transformation for an environment, lets call it 'dev'

• Create TestConfig.dev.json file, place it in same folder as TestConfig.json

  • Visual Studio should mark the new file as 'IsTransformFile=true' and 'DependentUpon=TestConfig.json'
    • If not, try dragging "TestConfig.dev.json" in under "TestConfig.json" via Solution Explorer

• Define only variables that we want to transform:

{
    "Name": "Hello Dev!",
}

Here are three ways of specifying the environment, by either launchSettings.json, web.config or mstest.runsettings.

1 launchSettings.json with IIS:

{ 
	...
	{
		"profiles": {
			"IIS": {
				"environmentVariables": {
					"ASPNETCORE_ENVIRONMENT": "Dev",
				}
			}
		}
	}
	...
}

2 web.config with IIS or IISExpress:

<configuration>
  <location path = "." inheritInChildApplications="false">
	</system.webServer>
	  <aspNetCore processPath = "bin\Demo.exe" arguments="" stdoutLogEnabled="false" hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name = "ASPNETCORE_ENVIRONMENT" value="Dev" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

3 mstest.runsettings if running through Test Explorer (unit tests):

• Note: add mstest.runsettings to your csproj-variable: 'RunSettingsFilePath'
• Tip: View source code of SystemLibrary.Common.Framework.Tests inside the repo SystemLibrary.Common.Framework on github

<RunSettings>
  <RunConfiguration>
      <EnvironmentVariables>
          <ASPNETCORE_ENVIRONMENT>Dev</ASPNETCORE_ENVIRONMENT>

Usage:

• Assume IISExpress and web.config setup above:

var testConfig = TestConfig.Current;
var name = testConfig.Name;
// name is now equal to 'Hello Dev!', which is our transformed value

Arguments

X

Generic types

Name	Description
T	T is the class inheriting Config<>, also referenced as 'self'. Note that T cannot be a nested class

Fields

Gets the current configuration as a singleton object, always instantiated, thread-safe, and should not throw exceptions.

Remarks

X

Config is a singleton, loaded once.

See documentation for EnvironmentConfig.Name for environment setup examples.

An encrypted property such as ApiToken {get;set;} can be automatically decrypted by adding a matching property ApiTokenDecrypt {get;set;} or mark it with [ConfigDecryptAttribute].

Environment variables like UserName apply only when reading appSettings, not custom config files.

WARNING: Generic type T cannot be a nested class.

public static T Current

X

Field Value

Type	Description
T

Extension Methods

ObjectExtensions.Json(object, bool)

ObjectExtensions.Json(object, JsonSerializerOptions, bool, params JsonConverter[])

ObjectExtensions.Json(object, params JsonConverter[])

ObjectExtensions.Xml(object)

}