Class BaseDistributeCache<T>

Namespace

Arc4u.Caching

Assembly

Arc4u.Caching.dll

Base class of the ICache implementations built on top of a Microsoft IDistributedCache (memory, Redis, SQL Server). Values are serialized with an IObjectSerialization before being stored, and each operation is traced with an Arc4u ActivitySource when an IActivitySourceFactory is registered. A derived class must set DistributeCache and SerializerFactory and set IsInitialized in its Initialize(string) override; every data operation throws a CacheNotInitializedException until then.

public abstract class BaseDistributeCache<T> : ICache, IDisposable

Type Parameters

T

The type of the derived cache, used as the category of the logger.

Inheritance

object

BaseDistributeCache<T>

Implements

ICache

IDisposable

Derived

MemoryCache

RedisCache

RedisSentinelCache

SqlCache

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Constructors

BaseDistributeCache(ILogger<T>, IServiceProvider)

Initializes a new instance of the BaseDistributeCache<T> class.

protected BaseDistributeCache(ILogger<T> logger, IServiceProvider container)

Parameters

logger ILogger<T>

The logger.

container IServiceProvider

The service provider, used to resolve the IObjectSerialization and the optional IActivitySourceFactory.

Exceptions

ArgumentNullException

logger or container is null.

Fields

DefaultOption

The entry options used by the Put overloads that have no timeout. By default no expiration is defined.

protected DistributedCacheEntryOptions DefaultOption

Field Value

DistributedCacheEntryOptions

_container

The service provider used to resolve the serializer.

protected readonly IServiceProvider _container

Field Value

IServiceProvider

_lock

The lock used by derived classes to make Initialize(string) thread safe.

protected readonly object _lock

Field Value

object

Properties

Container

Gets the service provider used to resolve the serializer.

protected IServiceProvider Container { get; }

Property Value

IServiceProvider

DistributeCache

Gets or sets the underlying distributed cache.

protected IDistributedCache? DistributeCache { get; set; }

Property Value

IDistributedCache

IsInitialized

Gets or sets a value indicating whether the cache is initialized and can be used.

protected bool IsInitialized { get; set; }

Property Value

bool

NotInitializedReason

Gets or sets the reason why the cache is not initialized; it is the message of the CacheNotInitializedException thrown by the operations.

protected string NotInitializedReason { get; set; }

Property Value

string

SerializerFactory

Gets or sets the serializer used to convert the values to and from bytes.

protected IObjectSerialization SerializerFactory { get; set; }

Property Value

IObjectSerialization

Exceptions

NullReferenceException

The getter is used before a serializer has been set.

Methods

CheckIfInitialized()

Throws when the cache is not initialized.

protected void CheckIfInitialized()

Exceptions

CacheNotInitializedException

The cache is not initialized; the message is NotInitializedReason.

Dispose()

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

public void Dispose()

Dispose(bool)

Disposes the underlying distributed cache when it is disposable.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true when called from Dispose(); false when called from a finalizer.

GetAsync<TValue>(string, CancellationToken)

Asynchronously gets the value stored for the key and deserializes it.

public Task<TValue?> GetAsync<TValue>(string key, CancellationToken cancellation = default)

Parameters

key string

The key of the value.

cancellation CancellationToken

A token to cancel the operation.

Returns

Task<TValue>

The value, or the default of TValue when the key does not exist.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

DataCacheException

The cache or the deserialization failed; the original exception is the inner exception.

Get<TValue>(string)

Gets the value stored for the key and deserializes it.

public TValue? Get<TValue>(string key)

Parameters

key string

The key of the value.

Returns

TValue

The value, or the default of TValue when the key does not exist.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

DataCacheException

The cache or the deserialization failed; the original exception is the inner exception.

Initialize(string)

Initializes the cache. This must be called once every time a cache is created.

public virtual void Initialize(string store)

Parameters

store string

The name of the cache, as declared in the configuration; it identifies the options and the store used.

PutAsync<TValue>(string, TimeSpan, TValue, bool, CancellationToken)

Asynchronously serializes the value and stores it with an absolute or a sliding expiration.

public Task PutAsync<TValue>(string key, TimeSpan timeout, TValue value, bool isSlided = false, CancellationToken cancellation = default)

Parameters

key string

The key of the value.

timeout TimeSpan

The validity period of the value.

value TValue

The value to store; it cannot be null. The default of a value type (0, false) is stored.

isSlided bool

true to use a sliding expiration (the period restarts each time the value is read); false for an absolute expiration relative to now.

cancellation CancellationToken

A token to cancel the operation.

Returns

Task

A task that completes when the value is stored.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

ArgumentNullException

value is null.

DataCacheException

The cache or the serialization failed; the original exception is the inner exception.

PutAsync<TValue>(string, TValue, CancellationToken)

Asynchronously serializes the value and stores it with the DefaultOption (no expiration by default).

public Task PutAsync<TValue>(string key, TValue value, CancellationToken cancellation = default)

Parameters

key string

The key of the value.

value TValue

The value to store; it cannot be null. The default of a value type (0, false) is stored.

cancellation CancellationToken

A token to cancel the operation.

Returns

Task

A task that completes when the value is stored.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

ArgumentNullException

value is null.

DataCacheException

The cache or the serialization failed; the original exception is the inner exception.

Put<TValue>(string, TimeSpan, TValue, bool)

Serializes the value and stores it with an absolute or a sliding expiration.

public void Put<TValue>(string key, TimeSpan timeout, TValue value, bool isSlided = false)

Parameters

key string

The key of the value.

timeout TimeSpan

The validity period of the value.

value TValue

The value to store; it cannot be null. The default of a value type (0, false) is stored.

isSlided bool

true to use a sliding expiration (the period restarts each time the value is read); false for an absolute expiration relative to now.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

ArgumentNullException

value is null.

DataCacheException

The cache or the serialization failed; the original exception is the inner exception.

Put<TValue>(string, TValue)

Serializes the value and stores it with the DefaultOption (no expiration by default).

public void Put<TValue>(string key, TValue value)

Parameters

key string

The key of the value.

value TValue

The value to store; it cannot be null. The default of a value type (0, false) is stored.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

ArgumentNullException

value is null.

DataCacheException

The cache or the serialization failed; the original exception is the inner exception.

Remove(string)

Removes the value stored for the key.

public bool Remove(string key)

Parameters

key string

The key of the value.

Returns

bool

true when the operation succeeded; false when the underlying cache raised an error.

Exceptions

CacheNotInitializedException

The cache is not initialized.

RemoveAsync(string, CancellationToken)

Asynchronously removes the value stored for the key.

public Task<bool> RemoveAsync(string key, CancellationToken cancellation = default)

Parameters

key string

The key of the value.

cancellation CancellationToken

A token to cancel the operation.

Returns

Task<bool>

true when the operation succeeded; false when the underlying cache raised an error.

Exceptions

CacheNotInitializedException

The cache is not initialized.

ToString()

Returns the name of the type T.

public override string ToString()

Returns

string

The name of T.

TryGetValueAsync<TValue>(string, CancellationToken)

Asynchronously tries to get the value stored for the key. Errors raised while reading or deserializing are swallowed.

public Task<TValue?> TryGetValueAsync<TValue>(string key, CancellationToken cancellation = default)

Parameters

key string

The key of the value.

cancellation CancellationToken

A token to cancel the operation.

Returns

Task<TValue>

The value, or the default of TValue when it is not found or an error occurred.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

TryGetValue<TValue>(string, out TValue?)

Tries to get the value stored for the key. Errors raised while reading or deserializing are swallowed.

public bool TryGetValue<TValue>(string key, out TValue? value)

Parameters

key string

The key of the value.

value TValue

The value, or the default of TValue when it is not found or an error occurred.

Returns

bool

true when the key exists and a non-null value was read; otherwise false.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.