Interface ICache

Namespace

Arc4u.Caching

Assembly

Arc4u.Caching.dll

The interface defines the contract implemented by a cache.

public interface ICache : IDisposable

Inherited Members

IDisposable.Dispose()

Methods

GetAsync<TValue>(string, CancellationToken)

Asynchronously gets the value stored for the key.

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

Parameters

key string

The key used to identify the value in the cache.

cancellation CancellationToken

A CancellationToken to cancel the operation.

Returns

Task<TValue>

The value, or the default of TValue when no value exists for the key.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

DataCacheException

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

Get<TValue>(string)

Gets the value stored for the key.

TValue? Get<TValue>(string key)

Parameters

key string

The key used to identify the value in the cache.

Returns

TValue

The value, or the default of TValue when no value exists for the key.

Type Parameters

TValue

The type of the value.

Exceptions

CacheNotInitializedException

The cache is not initialized.

DataCacheException

The cache engine 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.

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<T>(string, TimeSpan, T, bool, CancellationToken)

Asynchronously adds or replaces a value in the cache with an expiration.

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

Parameters

key string

The key used to identify the value in the cache.

timeout TimeSpan

The period of validity of the value. When it expires, the value is removed from the cache.

value T

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

isSlided bool

true to restart the period each time the value is read (sliding expiration); false for an absolute expiration. Not every cache supports a sliding expiration (the Dapr cache throws NotSupportedException).

cancellation CancellationToken

A CancellationToken to cancel the operation.

Returns

Task

A task that completes when the value is saved.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

value is null.

CacheNotInitializedException

The cache is not initialized.

NotSupportedException

isSlided is true and the cache does not support it.

PutAsync<T>(string, T, CancellationToken)

Asynchronously adds or replaces a value in the cache, without a specific expiration.

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

Parameters

key string

The key used to identify the value in the cache.

value T

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

cancellation CancellationToken

A CancellationToken to cancel the operation.

Returns

Task

A task that completes when the value is saved.

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

value is null.

CacheNotInitializedException

The cache is not initialized.

DataCacheException

The cache engine or the serialization failed (the original exception is the inner exception), or the memory cache is full.

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

Adds or replaces a value in the cache with an expiration.

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

Parameters

key string

The key used to identify the value in the cache.

timeout TimeSpan

The period of validity of the value. When it expires, the value is removed from the cache.

value T

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

isSlided bool

true to restart the period each time the value is read (sliding expiration); false for an absolute expiration. Not every cache supports a sliding expiration (the Dapr cache throws NotSupportedException).

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

value is null.

CacheNotInitializedException

The cache is not initialized.

NotSupportedException

isSlided is true and the cache does not support it.

Put<T>(string, T)

Adds or replaces a value in the cache, without a specific expiration.

void Put<T>(string key, T value)

Parameters

key string

The key used to identify the value in the cache.

value T

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

Type Parameters

T

The type of the value.

Exceptions

ArgumentNullException

value is null.

CacheNotInitializedException

The cache is not initialized.

DataCacheException

The cache engine or the serialization failed (the original exception is the inner exception), or the memory cache is full.

Remove(string)

Removes the value stored for the key.

bool Remove(string key)

Parameters

key string

The key used to identify the value in the cache.

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.

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

Parameters

key string

The key used to identify the value in the cache.

cancellation CancellationToken

A CancellationToken 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.

TryGetValueAsync<TValue>(string, CancellationToken)

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

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

Parameters

key string

The key used to identify the value in the cache.

cancellation CancellationToken

A CancellationToken to cancel the operation.

Returns

Task<TValue>

The value, or the default of TValue when it is not found or could not be read.

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 not thrown.

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

Parameters

key string

The key used to identify the value in the cache.

value TValue

The value, or the default of TValue when it is not found or could not be read.

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.