Class JsonConfigurationService

A service for loading configuration settings from JSON files, strings etc. into memory, and for getting and setting their (in-memory) values. Note that saving settings to JSON files is not supported.

This is the default configuration service for worker systems, but it can also be used stand-alone. See AConfig Configuration Facility and AConfig for further details.

Note that multiple calls to the Load*() methods can be made, which is useful when loading a mix of mandatory and optional files.

On a modern computer, GetValue() can retrieve more than 10 million string settings per second, and retrieve and parse more than 1 million date settings per second. While very fast, do cache the values where appropriate, e.g. if accessing a setting once per dataflow row.

Inheritance

Object

JsonConfigurationService

Implements

IConfigurationService

Namespace: actionETL.Configuration

Assembly: actionETL.dll

Syntax

public class JsonConfigurationService : IConfigurationService

Constructors

JsonConfigurationService()

Initializes a new instance of the JsonConfigurationService class, without loading any configuration files.

Declaration

public JsonConfigurationService()

Properties

Items

Gets all configuration items.

This property is thread-safe.

Declaration

public IEnumerable<IConfigurationServiceItem> Items { get; }

Property Value

Type	Description
IEnumerable<IConfigurationServiceItem>

Methods

DefaultFileNames()

Returns the default configuration file names that LoadAnyDefault() attempts to load. This can be used to customize the loading of the default files, e.g. mandating that at least one file is found.

This method is thread-safe.

Declaration

public static IEnumerable<string> DefaultFileNames()

Returns

Type

Description

IEnumerable<String>

The following file names, in this order: "actionetl.aconfig.json", including the path to the application directory (if available), i.e. normally the same path as the executable or (e.g. for test frameworks) DLL running the worker system. The path and name of the application executable or DLL, but with the suffix ".aconfig.json" added, e.g. ending in the filename "MyApp.exe.aconfig.json", "MyApp.dll.aconfig.json" or "testhost.dll.aconfig.json" (e.g. for test frameworks), or (for .NET Framework web applications) "web.aconfig.json".

LoadAll(IEnumerable<String>)

Loads all specified JSON configuration files.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadAll(IEnumerable<string> fileNames)

Parameters

Type	Name	Description
IEnumerable<String>	fileNames	The file names to load.

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
ArgumentNullException	fileNames
Exception	(Various JsonReaderException JSON parsing exceptions.)
FileNotFoundException	Configuration file not found.
IOException	An I/O error occurred.
SecurityException	The caller does not have the required permission.
UnauthorizedAccessException	The access requested is not permitted by the operating system for the specified path.

LoadAll(String[])

Loads all specified JSON configuration files.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadAll(params string[] fileNames)

Parameters

Type	Name	Description
String[]	fileNames	The file names to load.

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
Exception	(Various JsonReaderException JSON parsing exceptions.)
FileNotFoundException	Configuration file not found.
IOException	An I/O error occurred.
SecurityException	The caller does not have the required permission.
UnauthorizedAccessException	The access requested is not permitted by the operating system for the specified path.

LoadAny(IEnumerable<String>)

Loads any of the specified JSON configuration files, if they can be found and accessed.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadAny(IEnumerable<string> fileNames)

Parameters

Type	Name	Description
IEnumerable<String>	fileNames	The file names to load.

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
ArgumentNullException	fileNames
Exception	(Various JsonReaderException JSON parsing exceptions.)
IOException	An I/O error occurred.

LoadAny(String[])

Loads any of the specified JSON configuration files, if they can be found and accessed.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadAny(params string[] fileNames)

Parameters

Type	Name	Description
String[]	fileNames	The file names to load.

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
Exception	(Various JsonReaderException JSON parsing exceptions.)
IOException	An I/O error occurred.

LoadAnyDefault()

Gets the default JSON configurations by loading any of the default configuration files (see DefaultFileNames()) that can be found.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadAnyDefault()

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
Exception	(Various JsonReaderException JSON parsing exceptions.)
IOException	An I/O error occurred.

LoadText(TextReader)

Loads configurations in the JSON format from the specified TextReader.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadText(TextReader textReader)

Parameters

Type	Name	Description
TextReader	textReader	The text reader to load from.

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
ArgumentNullException	textReader
Exception	(Various JsonReaderException JSON parsing exceptions.)
IOException	An I/O error occurred.

LoadText(String)

Loads configurations from the specified JSON string.

This method is thread-safe.

Declaration

public JsonConfigurationService LoadText(string text)

Parameters

Type	Name	Description
String	text	The JSON string to load from.

Returns

Type	Description
JsonConfigurationService	The configuration instance itself, which allows chaining method calls.

Exceptions

Type	Condition
ArgumentNullException	text
Exception	(Various JsonReaderException JSON parsing exceptions.)
IOException	An I/O error occurred.

SetValue(String, String, String)

Creates or updates a configuration value.

This method is thread-safe.

Declaration

public IConfigurationService SetValue(string configurationName, string applyTo, string valueString)

Parameters

Type	Name	Description
String	configurationName	Name of the configuration.
String	applyTo	What part of the worker hierarchy this configuration applies to. Use null or an empty string to set a value that applies globally.
String	valueString	The value as a string.

Returns

Type	Description
IConfigurationService	The IConfigurationService instance itself, to allow chaining multiple calls together.

Exceptions

Type	Condition
ArgumentException	configurationName cannot be null or only whitespace.

ToString()

Returns a String that represents this instance.

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

Object.ToString()

TryGetValue<T>(String, String, CultureInfo)

Attempts to get a configuration value, returning an IGetValueOutcome instance describing the outcome. To instead throw an exception on any failure, use the AConfig GetValue and GetValueWithDefault methods.

On success, ApplyToMatched describes whether ApplyTo was both used and matched, or not. This is typically used to give configurations with ApplyTo higher precedence vs. non-ApplyTo configurations.

This method is thread-safe.

Declaration

public IGetValueOutcome TryGetValue<T>(string configurationName, string applyTo, CultureInfo culture)

Parameters

Type	Name	Description
String	configurationName	Name of the configuration. Cannot be null or only whitespace.
String	applyTo	What part of the worker hierarchy the configuration applies to. If set, first looks for a matching configurationName with a matching applyTo. If not found, then looks for a matching configurationName without any applyTo. Use null or an empty string to only look for a global configuration value without an applyTo.
CultureInfo	culture	The culture to use when converting a string to a typed value. Defaults to InvariantCulture if null.

Returns

Type

Description

IGetValueOutcome

The outcome is returned in a class instance with the marker interface IGetValueOutcome: GetValueOutcome.Succeeded on success, with the value available in Value. ApplyToMatched describes whether 'ApplyTo' was both used and matched, or not. GetValueOutcome.NotFound if the configurationName parameter either cannot be found at all, or it was found but only with a non-matching applyTo. GetValueOutcome.ParseError if parsing the string to the target type failed, with Exception describing the failure GetValueOutcome.NotSupported if converting to the target type T is not supported Typical usage is to call TryGetValue and switch on the type of the returned instance.

Type Parameters

Name

Description

T

The target value type. The following are supported: Value types: Boolean, Byte, DateTime, Decimal, Double, Guid, Int16, Int32, Int64, Single Enum enumeration value types Nullable versions of above value types Reference types: Byte arrays from Base64 strings, String Types supporting TypeConverter conversions from a string Types with a static FromString(string) method returning an instance of the type

Exceptions

Type	Condition
ArgumentException	configurationName cannot be null or only whitespace.

TryLoadAll(String[])

Loads any specified JSON configuration files, returning an OutcomeStatus reporting any file reading errors.

This method is thread-safe.

Declaration

public OutcomeStatus TryLoadAll(params string[] fileNames)

Parameters

Type	Name	Description
String[]	fileNames	The file names to be loaded.

Returns

Type	Description
OutcomeStatus	OutcomeStatus.Succeeded on success. OutcomeStatus.Error if at least one file could not be found, including from not having sufficient permissions to read the file. OutcomeStatus.Fatal on other exceptions (parsing errors etc.)

Implements

IConfigurationService

See Also

IConfigurationService