Class JsonSettings

Namespace

Nucs.JsonSettings

Assembly

Nucs.JsonSettings.dll

public abstract class JsonSettings : ISavable, IDisposable

Inheritance

object

JsonSettings

Implements

ISavable

IDisposable

Derived

NotifiyingJsonSettings

SettingsBag

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

JsonSettingsAutosaveExtensions.EnableAutosave<TSettings>(TSettings)

JsonSettingsAutosaveExtensions.EnableIAutosave<TSettings, ISettings>(TSettings)

JsonSettingsAutosaveExtensions.SuspendAutosave<TSettings>(TSettings)

FluentJsonSettings.LoadNow<T>(T)

FluentJsonSettings.LoadNow<T>(T, string)

FluentJsonSettings.WithBase64<T>(T)

FluentJsonSettings.WithDefaultValues<T>(T, Action<T>)

FluentJsonSettings.WithEncryptionRawKey<T>(T, byte[])

FluentJsonSettings.WithEncryptionRawKey<T>(T, byte[], EncryptionAlgorithm, KeySize)

FluentJsonSettings.WithEncryptionRawKey<T>(T, Func<T, byte[]>)

FluentJsonSettings.WithEncryptionRawKey<T>(T, Func<byte[]>)

FluentJsonSettings.WithEncryption<T>(T, byte[])

FluentJsonSettings.WithEncryption<T>(T, byte[], EncryptionAlgorithm, KeySize)

FluentJsonSettings.WithEncryption<T>(T, Func<T, byte[]>)

FluentJsonSettings.WithEncryption<T>(T, Func<T, SecureString>)

FluentJsonSettings.WithEncryption<T>(T, Func<T, string>)

FluentJsonSettings.WithEncryption<T>(T, Func<byte[]>)

FluentJsonSettings.WithEncryption<T>(T, Func<SecureString>)

FluentJsonSettings.WithEncryption<T>(T, Func<string>)

FluentJsonSettings.WithEncryption<T>(T, SecureString)

FluentJsonSettings.WithEncryption<T>(T, string)

FluentJsonSettings.WithEncryption<T>(T, string, EncryptionAlgorithm, KeySize)

FluentJsonSettings.WithFileName<T>(T, FileInfo)

FluentJsonSettings.WithFileName<T>(T, string)

FluentJsonSettings.WithModule<T>(T, Module)

FluentJsonSettings.WithModule<T, TMod>(T, params object[])

FluentJsonSettings.WithRecovery<T>(T, RecoveryAction)

Constructors

JsonSettings()

protected JsonSettings()

JsonSettings(string)

protected JsonSettings(string fileName)

Parameters

fileName string

Properties

Encoding

The encoding inwhich the text will be written, by default Encoding.UTF8.

public static Encoding Encoding { get; set; }

Property Value

Encoding

FileName

Serves as a reminder where to save or from where to load (if it is loaded on construction and doesnt change between constructions).
Can be relative to executing file's directory.

[JsonIgnore]
public abstract string FileName { get; set; }

Property Value

string

Modulation

Modulation Manager, handles everything related to modules in this instance.

[JsonIgnore]
public virtual ModuleSocket Modulation { get; }

Property Value

ModuleSocket

OverrideSerializerSettings

If this property is set, this will be used instead of the static SerializationSettings.
Note: this property must be set during construction or as property's default value.

[JsonIgnore]
protected virtual JsonSerializerSettings? OverrideSerializerSettings { get; set; }

Property Value

JsonSerializerSettings

SerializationSettings

public static JsonSerializerSettings SerializationSettings { get; set; }

Property Value

JsonSerializerSettings

Methods

Configure(Type, string)

Create a settings object for further configuration.

public static object Configure(Type intype, string filename = "<DEFAULT>")

Parameters

intype Type

The type of the configuration file.

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

object

A freshly new object or intype.

Configure<T>(string)

Create a settings object for further configuration.

public static T Configure<T>(string filename = "<DEFAULT>") where T : ISavable

Parameters

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

T

Type Parameters

T

Configure<T>(T, string)

Create a settings object for further configuration.

public static T Configure<T>(T instance, string filename = "<DEFAULT>") where T : ISavable

Parameters

instance T

An instance if available.

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

T

A freshly new object or instance.

Type Parameters

T

Construct(Type, params object[])

Constucts a settings object for further configuration.

public static JsonSettings Construct(Type jsonSettingsType, params object[] args)

Parameters

jsonSettingsType Type

args object[]

The arguments that will be passed into the constructor.

Returns

JsonSettings

A freshly new object.

Construct<T>(params object[])

Constucts a settings object for further configuration.

public static T Construct<T>(params object[] args) where T : ISavable

Parameters

args object[]

The arguments that will be passed into the constructor.

Returns

T

A freshly new object.

Type Parameters

T

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

EnsureConfigured()

Runs OnConfigure() exactly once for this instance, blocking any concurrent caller until it completes. Safe to call from multiple threads, and re-entrant from within OnConfigure() itself (the configuring thread falls through rather than blocking).

protected void EnsureConfigured()

Load()

Populate the data in this object from FileName.

public void Load()

Load(object, Action?, string)

Loads a settings file or creates a new settings file.

public static object Load(object instance, Action? configure, string filename = "<DEFAULT>")

Parameters

instance object

The instance inwhich to load into

configure Action

Configurate the settings instance prior to loading - called after OnConfigure

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

object

The loaded or freshly new saved object

Exceptions

JsonSettings

Load(string)

Populate the data in this object from given filename.

public void Load(string filename)

Parameters

filename string

The path to the file inwhich to load, relative pathing allowed to current executing file.

Load(string, Action<JsonSettings>?)

Loads or creates a settings file.

public void Load(string filename, Action<JsonSettings>? configure)

Parameters

filename string

File name, for example "settings.jsn". no path required, just a file name.

configure Action<JsonSettings>

Configurate the settings instance prior to loading - called after OnConfigure

Load(Type, Action?, string, object[])

Loads a settings file or creates a new settings file.

public static object Load(Type intype, Action? configure, string filename, object[] args)

Parameters

intype Type

The type of this object

configure Action

Configurate the settings instance prior to loading - called after OnConfigure

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

args object[]

Returns

object

The loaded or freshly new saved object

Load(Type, object[])

Loads a settings file or creates a new settings file.

public static object Load(Type intype, object[] args)

Parameters

intype Type

The type of this object

args object[]

Returns

object

The loaded or freshly new saved object

Load(Type, string)

Loads a settings file or creates a new settings file.

public static object Load(Type intype, string filename = "<DEFAULT>")

Parameters

intype Type

The type of this object

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

object

The loaded or freshly new saved object

Load(Type, string, object[])

Loads a settings file or creates a new settings file.

public static object Load(Type intype, string filename, object[] args)

Parameters

intype Type

The type of this object

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

args object[]

Returns

object

The loaded or freshly new saved object

LoadDefault(params object[]?)

Populate the data in this object from a newly created copy of GetType().

public void LoadDefault(params object[]? args)

Parameters

args object[]

Remarks

Triggers AfterLoad

LoadDefault<T>(params object[]?)

Populate the data in this object from a newly created copy of type T.

public void LoadDefault<T>(params object[]? args) where T : ISavable

Parameters

args object[]

Type Parameters

T

Remarks

Triggers AfterLoad

LoadJson(string, JsonSerializerSettings?)

Populate this object with given json.

public virtual void LoadJson(string json, JsonSerializerSettings? settings = null)

Parameters

json string

The json, specifying only the properties to change. Unspecified will be left untouched.

settings JsonSerializerSettings

Load<T>(Action<T>?, string)

Loads or creates a settings file.

public static T Load<T>(Action<T>? configure, string filename = "<DEFAULT>") where T : ISavable

Parameters

configure Action<T>

Configurate the settings instance prior to loading - called after OnConfigure

filename string

File name, for example "settings.jsn". no path required, just a file name.

Returns

T

The loaded or freshly new saved object

Type Parameters

T

Load<T>(object[])

Loads or creates a settings file.

public static T Load<T>(object[] args) where T : ISavable

Parameters

args object[]

Returns

T

The loaded or freshly new saved object

Type Parameters

T

Load<T>(string)

Loads or creates a settings file.

public static T Load<T>(string filename = "<DEFAULT>") where T : ISavable

Parameters

filename string

File name, for example "settings.jsn". no path required, just a file name.

Returns

T

The loaded or freshly new saved object

Type Parameters

T

Load<T>(string, Action<T>?)

Loads or creates a settings file.

public static T Load<T>(string filename, Action<T>? configure) where T : ISavable

Parameters

filename string

File name, for example "settings.jsn". no path required, just a file name.

configure Action<T>

Configurate the settings instance prior to loading - called after OnConfigure

Returns

T

The loaded or freshly new saved object

Type Parameters

T

Load<T>(string, Action<T>?, object[])

Loads or creates a settings file.

public static T Load<T>(string filename, Action<T>? configure, object[] args) where T : ISavable

Parameters

filename string

File name, for example "settings.jsn". no path required, just a file name.

configure Action<T>

Configurate the settings instance prior to loading - called after OnConfigure

args object[]

Returns

T

The loaded or freshly new saved object

Type Parameters

T

Load<T>(Type, Action<T>?, string)

Loads a settings file or creates a new settings file.

public static object Load<T>(Type intype, Action<T>? configure, string filename = "<DEFAULT>") where T : ISavable

Parameters

intype Type

The type of this object

configure Action<T>

Configurate the settings instance prior to loading - called after OnConfigure

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

object

The loaded or freshly new saved object

Type Parameters

T

Load<T>(T, Action?, string)

Loads a settings file or creates a new settings file.

public static T Load<T>(T instance, Action? configure, string filename = "<DEFAULT>") where T : ISavable

Parameters

instance T

The instance inwhich to load into

configure Action

Configurate the settings instance prior to loading - called after OnConfigure

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

T

The loaded or freshly new saved object

Type Parameters

T

Load<T>(T, Action<T>?, string)

Loads a settings file or creates a new settings file.

public static T Load<T>(T instance, Action<T>? configure, string filename = "<DEFAULT>") where T : ISavable

Parameters

instance T

The instance inwhich to load into

configure Action<T>

Configurate the settings instance prior to loading - called after OnConfigure

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Returns

T

The loaded or freshly new saved object

Type Parameters

T

OnAfterDeserialize()

protected virtual void OnAfterDeserialize()

OnAfterEncrypt(ref byte[])

protected virtual void OnAfterEncrypt(ref byte[] data)

Parameters

data byte[]

OnAfterLoad(bool)

protected virtual void OnAfterLoad(bool successfulLoad)

Parameters

successfulLoad bool

OnAfterRepopulate(bool)

protected virtual void OnAfterRepopulate(bool successfulPopulate)

Parameters

successfulPopulate bool

OnAfterSave(string)

protected virtual void OnAfterSave(string destinition)

Parameters

destinition string

OnAfterSerialize(ref string)

protected virtual void OnAfterSerialize(ref string data)

Parameters

data string

OnBeforeDeserialize(ref string)

protected virtual void OnBeforeDeserialize(ref string data)

Parameters

data string

OnBeforeLoad(ref string)

protected virtual void OnBeforeLoad(ref string destinition)

Parameters

destinition string

OnBeforeRepopulate()

protected virtual void OnBeforeRepopulate()

OnBeforeSave(ref string)

protected virtual void OnBeforeSave(ref string destinition)

Parameters

destinition string

OnBeforeSerialize()

protected virtual void OnBeforeSerialize()

OnConfigure()

Configurate properties of this JsonSettings, for example - call WithBase64<T>(T) on this.

protected virtual void OnConfigure()

Remarks

Run-once and reentrancy are enforced by EnsureConfigured(); an override should call base.OnConfigure() to fire the fluent Nucs.JsonSettings.JsonSettings.Configurate handlers.

OnDecrypt(ref byte[])

protected virtual void OnDecrypt(ref byte[] data)

Parameters

data byte[]

OnEncrypt(ref byte[])

protected virtual void OnEncrypt(ref byte[] data)

Parameters

data byte[]

OnRecovered()

protected virtual void OnRecovered()

OnTryingRecover(string, JsonException?, ref bool, ref bool)

protected virtual void OnTryingRecover(string fileName, JsonException? exception, ref bool recovered, ref bool handled)

Parameters

fileName string

exception JsonException

recovered bool

handled bool

ResolveConfiguration(JsonSerializerSettings?)

Returns configuration based on the following fallback:
settings ?? this.OverrideSerializerSettings ?? JsonSettings.SerializationSettings ?? JsonConvert.DefaultSettings?.Invoke() ?? throw new JsonSerializationException("Unable to resolve JsonSerializerSettings to serialize this JsonSettings");

protected virtual JsonSerializerSettings ResolveConfiguration(JsonSerializerSettings? settings = null)

Parameters

settings JsonSerializerSettings

If passed a non-null, This is the settings intended to use, not any of the fallbacks.

Returns

JsonSerializerSettings

Exceptions

JsonSerializationException

When no configuration valid was found.

Save()

Save the settings file to a predefined location FileName

public void Save()

Save(string)

The filename that was originally loaded from. saving to other file does not change this field!

public virtual void Save(string filename)

Parameters

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Save(Type, object, string)

Saves settings to a given path using custom password.

public static void Save(Type inType, object boxedJsonSettings, string filename = "<DEFAULT>")

Parameters

inType Type

boxedJsonSettings object

The settings file to save

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Save<T>(T, string)

Saves settings to a given path using custom password.

public static void Save<T>(T pSettings, string filename = "<DEFAULT>") where T : ISavable

Parameters

pSettings T

The settings file to save

filename string

File name, for example "settings.jsn". no path required, just a file name.
Without path the file will be located at the executing directory

Type Parameters

T

ToJson(JsonSerializerSettings?, Type?, Formatting?)

Serializes this object to json.

public virtual string ToJson(JsonSerializerSettings? settings = null, Type? serializeAsType = null, Formatting? formatting = null)

Parameters

settings JsonSerializerSettings

serializeAsType Type

formatting Formatting?

The formatting to serialize JSON as. By default it'll take settings

Returns

string

Events

AfterDecrypt

Called after Decrypt.

public virtual event AfterDecryptHandler? AfterDecrypt

Event Type

AfterDecryptHandler

AfterDeserialize

Invoked after deserialization of this instance was successful.

public virtual event AfterDeserializeHandler? AfterDeserialize

Event Type

AfterDeserializeHandler

AfterEncrypt

After encryption successful.

public virtual event AfterEncryptHandler? AfterEncrypt

Event Type

AfterEncryptHandler

AfterLoad

Invoked at the end of the loading progress.

public virtual event AfterLoadHandler? AfterLoad

Event Type

AfterLoadHandler

AfterRepopulate

Raised after every JSON populate of this instance, from a finally -- including a populate that threw halfway (the recovery path), which has still replaced some values that subscribers must observe while the exception unwinds. successfulPopulate is true only when the populate ran to completion.

public virtual event AfterRepopulateHandler? AfterRepopulate

Event Type

AfterRepopulateHandler

Remarks

A false report means the object graph may be part old values, part replacements. The library's own subscribers deliberately behave identically either way -- the autosave loading gate must drop and the NotificationBinder must track the surviving instances regardless -- so consult the flag when acting on the loaded DATA rather than on graph identity. Handler order is subscription order.

AfterSave

Invoked after saving this object.

public virtual event AfterSaveHandler? AfterSave

Event Type

AfterSaveHandler

AfterSerialize

public virtual event AfterSerializeHandler? AfterSerialize

Event Type

AfterSerializeHandler

BeforeDeserialize

Invoked after file was read and decrypted successfully right before deserializing into an object.

public virtual event BeforeDeserializeHandler? BeforeDeserialize

Event Type

BeforeDeserializeHandler

BeforeLoad

Invoked after path has been resolved and before reading.
FileInfo can be modified now.

public virtual event BeforeLoadHandler? BeforeLoad

Event Type

BeforeLoadHandler

BeforeRepopulate

Raised immediately before a JSON populate rewrites this instance's properties -- on every LoadJson(string, JsonSerializerSettings?), which is where Load(), LoadDefault(), recovery and versioning reloads all funnel their populate.

public virtual event BeforeRepopulateHandler? BeforeRepopulate

Event Type

BeforeRepopulateHandler

Remarks

This pair is the only per-populate signal in the pipeline: BeforeDeserialize/AfterDeserialize fire once per successful FILE load (never for LoadDefault() or a direct LoadJson(string, JsonSerializerSettings?) call), and AfterLoad fires once per Load() however many populates recovery ran underneath it. Between this event and AfterRepopulate the instance is half-populated, so handlers must not save. The library subscribes here itself: SuspensionModule brackets its autosave loading gate, and the autosave package's NotificationBinder resyncs its nested-change subscriptions.

BeforeSave

Invoked before saving this object.

public virtual event BeforeSaveHandler? BeforeSave

Event Type

BeforeSaveHandler

BeforeSerialize

public virtual event BeforeSerializeHandler? BeforeSerialize

Event Type

BeforeSerializeHandler

Decrypt

Called during loading right after BeforeLoad to decrypt the readed bytes, if Encrypt is not implemented - no reason to perform decryption.

public virtual event DecryptHandler? Decrypt

Event Type

DecryptHandler

Encrypt

After serializing, encryption can be applied now.

public virtual event EncryptHandler? Encrypt

Event Type

EncryptHandler

Recovered

Triggers when an object has recovered/defaulted successfully.

public virtual event RecoveredHandler? Recovered

Event Type

RecoveredHandler

Remarks

For example, used by VersioningModule to fill the right version on default load.

TryingRecover

When parsing JSON fails, this event is called.

public virtual event TryingRecoverHandler? TryingRecover

Event Type

TryingRecoverHandler

Remarks

handled=true will prevent other recovery mechanisms from trying to recover. recovered=false will throw the error.