Class PersistableHelper

Namespace

Ecng.Serialization

Assembly

Ecng.Serialization.dll

Provides helper methods for persisting, cloning, loading and saving objects.

public static class PersistableHelper

Inheritance

object

PersistableHelper

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

ApplyAsync<T>(T, T, CancellationToken)

Asynchronously applies the state from the clone to the target asynchronous persistable object.

public static ValueTask ApplyAsync<T>(this T obj, T clone, CancellationToken cancellationToken = default) where T : IAsyncPersistable

Parameters

obj T

The target object.

clone T

The object from which to copy the state.

cancellationToken CancellationToken

A token for cancellation.

Returns

ValueTask

A ValueTask representing the asynchronous operation.

Type Parameters

T

The type of the asynchronous persistable object.

Apply<T>(T, T)

Applies the state from the clone to the target persistable object.

public static void Apply<T>(this T obj, T clone) where T : IPersistable

Parameters

obj T

The target object.

clone T

The object from which to copy the state.

Type Parameters

T

The type of the persistable object.

CloneAsync<T>(T, CancellationToken)

Asynchronously clones the specified asynchronous persistable object.

public static ValueTask<T> CloneAsync<T>(this T obj, CancellationToken cancellationToken = default) where T : IAsyncPersistable

Parameters

obj T

The object to clone.

cancellationToken CancellationToken

A token for cancellation.

Returns

ValueTask<T>

A ValueTask with the cloned object.

Type Parameters

T

The type of the asynchronous persistable object.

Clone<T>(T)

Clones the specified persistable object.

public static T Clone<T>(this T obj) where T : IPersistable

Parameters

obj T

The object to clone.

Returns

T

A clone of the object.

Type Parameters

T

The type of the persistable object.

ForceLoad<T>(T, SettingsStorage)

Forces the persistable object to load its state from the given settings storage.

public static void ForceLoad<T>(this T t, SettingsStorage storage) where T : IPersistable

Parameters

t T

The target object.

storage SettingsStorage

The settings storage to load from.

Type Parameters

T

The type of the persistable object.

FromStorage(SettingsStorage)

Converts the settings storage back to an object.

public static object FromStorage(this SettingsStorage storage)

Parameters

storage SettingsStorage

The settings storage.

Returns

object

The object represented by the settings storage.

IsPersistable(Type)

Determines whether the specified type is persistable.

public static bool IsPersistable(this Type type)

Parameters

type Type

The type to evaluate.

Returns

bool

true if the type implements IPersistable or IAsyncPersistable; otherwise, false.

IsSerializablePrimitive(Type)

Determines whether the specified type is a serializable primitive.

public static bool IsSerializablePrimitive(this Type type)

Parameters

type Type

The type to examine.

Returns

bool

true if the type is a primitive or Uri; otherwise, false.

Load(IPersistable, SettingsStorage, string)

Loads the state of the persistable object from the specified settings storage using the given key.

public static void Load(this IPersistable persistable, SettingsStorage settings, string name)

Parameters

persistable IPersistable

The persistable object to load.

settings SettingsStorage

The settings storage.

name string

The name of the value within the storage.

Load(SettingsStorage, Type)

Loads an IPersistable object of the specified type from the settings storage.

public static IPersistable Load(this SettingsStorage storage, Type type)

Parameters

storage SettingsStorage

The settings storage to load from.

type Type

The type of the persistable object.

Returns

IPersistable

The loaded persistable object.

LoadAsync(SettingsStorage, Type, CancellationToken)

Asynchronously loads an asynchronous persistable object using the specified type.

public static ValueTask<IAsyncPersistable> LoadAsync(this SettingsStorage storage, Type type, CancellationToken cancellationToken = default)

Parameters

storage SettingsStorage

The settings storage to load from.

type Type

The type of the asynchronous persistable object.

cancellationToken CancellationToken

A token for cancellation.

Returns

ValueTask<IAsyncPersistable>

A ValueTask with the loaded asynchronous persistable object.

LoadAsync<T>(SettingsStorage, CancellationToken)

Asynchronously loads an asynchronous persistable object of type T.

public static ValueTask<T> LoadAsync<T>(this SettingsStorage storage, CancellationToken cancellationToken = default) where T : IAsyncPersistable, new()

Parameters

storage SettingsStorage

The settings storage to load from.

cancellationToken CancellationToken

A token for cancellation.

Returns

ValueTask<T>

A ValueTask with the loaded object of type T.

Type Parameters

T

The type of the asynchronous persistable object.

LoadEntire<T>(SettingsStorage)

Creates and initializes an object from the specified settings storage.

public static T LoadEntire<T>(this SettingsStorage storage) where T : IPersistable

Parameters

storage SettingsStorage

The settings storage used to create the object.

Returns

T

The created and initialized object.

Type Parameters

T

The type of the persistable object.

LoadFromString(ISerializer<SettingsStorage>, IPersistable, string)

Loads the state of the persistable object from a string using the provided serializer.

public static void LoadFromString(this ISerializer<SettingsStorage> serializer, IPersistable persistable, string value)

Parameters

serializer ISerializer<SettingsStorage>

The serializer to use.

persistable IPersistable

The persistable object to load.

value string

The string representation of the state.

LoadFromString<TSerializer>(IPersistable, string)

[Obsolete("Use overload with serializer param.")]
public static void LoadFromString<TSerializer>(this IPersistable persistable, string value) where TSerializer : ISerializer<SettingsStorage>, new()

Parameters

persistable IPersistable

value string

Type Parameters

TSerializer

LoadFromString<TValue>(ISerializer<TValue>, string)

Loads a value of type TValue from a string using the provided serializer.

public static TValue LoadFromString<TValue>(this ISerializer<TValue> serializer, string value)

Parameters

serializer ISerializer<TValue>

The serializer to use.

value string

The string representation of the value.

Returns

TValue

The deserialized value.

Type Parameters

TValue

The type of the value to load.

LoadFromString<TSerializer>(string)

[Obsolete("Use overload with serializer param.")]
public static SettingsStorage LoadFromString<TSerializer>(this string value) where TSerializer : ISerializer<SettingsStorage>, new()

Parameters

value string

Returns

SettingsStorage

Type Parameters

TSerializer

LoadIfNotNull(IPersistable, SettingsStorage)

Loads the state of the persistable object from the specified settings storage if the storage is not null.

public static bool LoadIfNotNull(this IPersistable persistable, SettingsStorage storage)

Parameters

persistable IPersistable

The persistable object to load.

storage SettingsStorage

The settings storage.

Returns

bool

true if the state was loaded; otherwise, false.

LoadIfNotNull(IPersistable, SettingsStorage, string)

Loads the state of the persistable object from the specified settings storage using the given key if it is not null.

public static bool LoadIfNotNull(this IPersistable persistable, SettingsStorage settings, string name)

Parameters

persistable IPersistable

The persistable object to load.

settings SettingsStorage

The settings storage.

name string

The name of the value within the storage.

Returns

bool

true if the state was loaded; otherwise, false.

Load<T>(SettingsStorage)

Loads an IPersistable object of type T from the settings storage.

public static T Load<T>(this SettingsStorage storage) where T : IPersistable

Parameters

storage SettingsStorage

The settings storage to load from.

Returns

T

The loaded object of type T.

Type Parameters

T

The type of the persistable object.

RegisterAdapterType(Type, Type)

Registers the adapter type for the given type.

public static void RegisterAdapterType(this Type type, Type adapterType)

Parameters

type Type

The type for which the adapter is registered.

adapterType Type

The adapter type to register.

RegisterCustomSerializer<T>(Func<T, SettingsStorage>, Func<SettingsStorage, T>)

Registers a custom serializer for a specific type.

public static void RegisterCustomSerializer<T>(Func<T, SettingsStorage> serialize, Func<SettingsStorage, T> deserialize)

Parameters

serialize Func<T, SettingsStorage>

A function to serialize the object to a settings storage.

deserialize Func<SettingsStorage, T>

A function to deserialize from a settings storage to the object.

Type Parameters

T

The type for which to register the serializer.

RemoveAdapterType(Type)

Removes the registered adapter type for the given type.

public static bool RemoveAdapterType(this Type type)

Parameters

type Type

The type whose adapter registration is removed.

Returns

bool

true if the adapter was removed; otherwise, false.

Save(IPersistable)

Saves the state of the persistable object to a settings storage.

public static SettingsStorage Save(this IPersistable persistable)

Parameters

persistable IPersistable

The persistable object to save.

Returns

SettingsStorage

A settings storage containing the saved state.

SaveAsync(IAsyncPersistable, CancellationToken)

Asynchronously saves the state of the asynchronous persistable object to a settings storage.

public static ValueTask<SettingsStorage> SaveAsync(this IAsyncPersistable persistable, CancellationToken cancellationToken = default)

Parameters

persistable IAsyncPersistable

The asynchronous persistable object.

cancellationToken CancellationToken

A token for cancellation.

Returns

ValueTask<SettingsStorage>

A ValueTask with the settings storage containing the saved state.

SaveEntire(IPersistable, bool)

Saves the entire state of the persistable object into a new settings storage.

public static SettingsStorage SaveEntire(this IPersistable persistable, bool isAssemblyQualifiedName)

Parameters

persistable IPersistable

The persistable object to save.

isAssemblyQualifiedName bool

A value indicating whether the type name should be assembly qualified.

Returns

SettingsStorage

A settings storage containing the saved state.

SaveToString(ISerializer<SettingsStorage>, IPersistable)

Saves the state of the persistable object to a string using the provided serializer.

public static string SaveToString(this ISerializer<SettingsStorage> serializer, IPersistable persistable)

Parameters

serializer ISerializer<SettingsStorage>

The serializer to use.

persistable IPersistable

The persistable object to save.

Returns

string

A string representing the saved state.

SaveToString<TSerializer>(IPersistable)

[Obsolete("Use overload with serializer param.")]
public static string SaveToString<TSerializer>(this IPersistable persistable) where TSerializer : ISerializer<SettingsStorage>, new()

Parameters

persistable IPersistable

Returns

string

Type Parameters

TSerializer

SaveToString<TValue>(ISerializer<TValue>, TValue)

Saves the settings to a string using the provided serializer.

public static string SaveToString<TValue>(this ISerializer<TValue> serializer, TValue settings)

Parameters

serializer ISerializer<TValue>

The serializer to use.

settings TValue

The settings to save.

Returns

string

A string representing the settings.

Type Parameters

TValue

The type of the settings.

SaveToString<TSerializer>(SettingsStorage)

[Obsolete("Use overload with serializer param.")]
public static string SaveToString<TSerializer>(this SettingsStorage settings) where TSerializer : ISerializer<SettingsStorage>, new()

Parameters

settings SettingsStorage

Returns

string

Type Parameters

TSerializer

SetValue(SettingsStorage, string, IPersistable)

Adds a persistable object's state as a value in the settings storage.

public static void SetValue(this SettingsStorage storage, string name, IPersistable persistable)

Parameters

storage SettingsStorage

The settings storage to update.

name string

The name of the setting.

persistable IPersistable

The persistable object whose state is added.

ToMember(SettingsStorage)

Converts the settings storage to a MemberInfo.

public static MemberInfo ToMember(this SettingsStorage storage)

Parameters

storage SettingsStorage

The settings storage to convert.

Returns

MemberInfo

The converted MemberInfo.

ToMember<T>(SettingsStorage)

Converts the settings storage to a member of type T.

public static T ToMember<T>(this SettingsStorage storage) where T : MemberInfo

Parameters

storage SettingsStorage

The settings storage to convert.

Returns

T

The converted member of type T.

Type Parameters

T

The expected type of the member.

ToRefFive<T1, T2, T3, T4, T5>(SettingsStorage)

Converts the settings storage to a RefFive tuple of the specified types.

public static RefFive<T1, T2, T3, T4, T5> ToRefFive<T1, T2, T3, T4, T5>(this SettingsStorage storage)

Parameters

storage SettingsStorage

The settings storage to convert.

Returns

RefFive<T1, T2, T3, T4, T5>

A RefFive tuple containing the converted values.

Type Parameters

T1

The type of the first element.

T2

The type of the second element.

T3

The type of the third element.

T4

The type of the fourth element.

T5

The type of the fifth element.

ToRefPair<T1, T2>(SettingsStorage)

Converts the settings storage to a RefPair of the specified types.

public static RefPair<T1, T2> ToRefPair<T1, T2>(this SettingsStorage storage)

Parameters

storage SettingsStorage

The settings storage to convert.

Returns

RefPair<T1, T2>

A RefPair containing the converted values.

Type Parameters

T1

The type of the first element.

T2

The type of the second element.

ToRefQuadruple<T1, T2, T3, T4>(SettingsStorage)

Converts the settings storage to a RefQuadruple of the specified types.

public static RefQuadruple<T1, T2, T3, T4> ToRefQuadruple<T1, T2, T3, T4>(this SettingsStorage storage)

Parameters

storage SettingsStorage

The settings storage to convert.

Returns

RefQuadruple<T1, T2, T3, T4>

A RefQuadruple containing the converted values.

Type Parameters

T1

The type of the first element.

T2

The type of the second element.

T3

The type of the third element.

T4

The type of the fourth element.

ToRefTriple<T1, T2, T3>(SettingsStorage)

Converts the settings storage to a RefTriple of the specified types.

public static RefTriple<T1, T2, T3> ToRefTriple<T1, T2, T3>(this SettingsStorage storage)

Parameters

storage SettingsStorage

The settings storage to convert.

Returns

RefTriple<T1, T2, T3>

A RefTriple containing the converted values.

Type Parameters

T1

The type of the first element.

T2

The type of the second element.

T3

The type of the third element.

ToStorage(IRefTuple)

Converts a tuple implementing IRefTuple to a settings storage.

public static SettingsStorage ToStorage(this IRefTuple tuple)

Parameters

tuple IRefTuple

The tuple to convert.

Returns

SettingsStorage

A settings storage representing the tuple.

ToStorage(object, bool)

Converts an object to a settings storage with type and value.

public static SettingsStorage ToStorage(this object value, bool isAssemblyQualifiedName = false)

Parameters

value object

The object to convert.

isAssemblyQualifiedName bool

A value indicating whether the type name should be assembly qualified.

Returns

SettingsStorage

A settings storage representing the object.

ToStorage<T>(T, bool)

Converts the specified member to a settings storage.

public static SettingsStorage ToStorage<T>(this T member, bool isAssemblyQualifiedName = false) where T : MemberInfo

Parameters

member T

The member to convert.

isAssemblyQualifiedName bool

A value indicating whether the type name should be assembly qualified.

Returns

SettingsStorage

A settings storage representing the member.

Type Parameters

T

The type of the member.

TryDeserialize<T>(SettingsStorage, out T)

Tries to deserialize a settings storage into an object of type T using a registered custom serializer.

public static bool TryDeserialize<T>(this SettingsStorage storage, out T value)

Parameters

storage SettingsStorage

The settings storage containing serialized data.

value T

When this method returns, contains the deserialized object if successful.

Returns

bool

true if deserialization was successful; otherwise, false.

Type Parameters

T

The type to deserialize.

TryGetAdapterType(Type, out Type)

Tries to get the registered adapter type for the given type.

public static bool TryGetAdapterType(this Type type, out Type adapterType)

Parameters

type Type

The type to check.

adapterType Type

When this method returns, contains the adapter type if found.

Returns

bool

true if found; otherwise, false.

TrySerialize<T>(T, out SettingsStorage)

Tries to serialize an object using a registered custom serializer.

public static bool TrySerialize<T>(this T value, out SettingsStorage storage)

Parameters

value T

The object to serialize.

storage SettingsStorage

When this method returns, contains the resulting settings storage if serialization was successful.

Returns

bool

true if serialization was successful; otherwise, false.

Type Parameters

T

The type of the object to serialize.

UnRegisterCustomSerializer<T>()

Unregisters the custom serializer for a specific type.

public static void UnRegisterCustomSerializer<T>()

Type Parameters

T

The type for which to unregister the serializer.