Zhomfr.Cache.Abstractions 0.7.0

Abstractions for Unified Work with Cache.

⚠️ Warning: Active Development (< 1.0.0)

Prior to the release of stable version 1.0.0, this library follows SemVer for initial development. This means breaking changes may occur even in minor releases (0.x).

We strongly recommend pinning the package version in your .csproj to avoid unexpected build errors.

A lightweight and flexible .NET library providing a unified contract for cache functions. It completely decouples your business logic from specific caching driver or third-party implementations.

💡 Core Concept

Your code interacts exclusively with a standardized interface. The underlying drivers is determined at the dependency injection composition root. If you ever need to change the provider tomorrow, you won't need to rewrite your business logic.

Available Drivers:

• InMemory see GitHub NuGet

• Redis see GitHub NuGet

• Database see GitHub NuGet

Development Custom Driver

📦 Installation

Install package:

dotnet add package Zhomfr.Cache.Abstractions

For example, you can use code of available drivers in GitHub.

Configuration Convention

All settings are located in appsettings.json under the Zhomfr:Cache section:

• The default service uses the Zhomfr:Cache:Default subsection.
• Keyed services use subsections where the name matches the service key, resulting in Zhomfr:Cache:KeyName.

For instance, given the following registrations:

builder.Services.AddDefaultCache<MyAwesomeCache, MyAwesomeCacheConfig>();
builder.Services.AddKeyedCache<MyAwesomeCache, MyAwesomeCacheConfig>("AwesomeKey");

Your appsettings.json file should follow this structure:

{
  "Zhomfr": {
    "Cache": {
      "Default": {
        "Prefix": "somePrefixForDefault",
        "Ttl": 10
        // ... other configuration properties
      },
      "AwesomeKey": {
        "Prefix": "somePrefixForAwesomeKey",
        "Ttl": 60
        // ... other configuration properties
      }
    }
  }
}

Abstractions

• AbstractConfig

• ICache

AbstractConfig

Namespace: Zhomfr.Cache.Abstractions

Abstract configuration object.

public abstract class AbstractConfig

Inheritance Object → AbstractConfig<br> Attributes NullableContextAttribute, NullableAttribute

Properties

Prefix

Cache prefix, needed then you use more than one app for one provider.

public abstract string Prefix { get; init; }

Property Value

String<br>

Ttl

Default time to life for saved data (in minutes).

public abstract int Ttl { get; init; }

Property Value

Int32<br>

Constructors

AbstractConfig ()

protected AbstractConfig()

ICache

Namespace: Zhomfr.Cache.Abstractions

Defines a unified interface for cache operations, inspired by the Laravel Cache facade. Provides both simple key-value storage and advanced "remember" patterns.

public interface ICache

Attributes NullableContextAttribute

Fields

KEY_SEPARATOR

The cache key separator used to format the full key with a driver prefix.

public static string KEY_SEPARATOR;

Methods

Get<T> (String)

Retrieve an item from the cache by its unique key.

T Get<T>(string key)

Type Parameters

T<br> The type of the item to retrieve.

Parameters

key String<br> The unique cache key.

Returns

T<br> The cached item or null if it does not exist.

GetAsync<T> (String, CancellationToken)

Asynchronously retrieve an item from the cache by its unique key.

Task<T> GetAsync<T>(string key, CancellationToken ct = null)

Type Parameters

T<br> The type of the item to retrieve.

Parameters

key String<br> The unique cache key.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<T><br> A task representing the asynchronous operation, containing the cached item or null.

Get<T> (String, T)

Retrieve an item from the cache, or return a default value if the item is missing.

T Get<T>(string key, T defaultValue)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

defaultValue T<br> The value to return if the key is not found.

Returns

T<br> The cached item or the provided default value.

GetAsync<T> (String, T, CancellationToken)

Asynchronously retrieve an item from the cache, or return a default value if the item is missing.

Task<T> GetAsync<T>(string key, T defaultValue, CancellationToken ct = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

defaultValue T<br> The value to return if the key is not found.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<T><br> A task containing the cached item or the provided default value.

Put<T> (String, T, TimeSpan?)

Store an item in the cache for a specific duration.

void Put<T>(string key, T value, TimeSpan? ttl = null)

Type Parameters

T<br> The type of the item to store.

Parameters

key String<br> The unique cache key.

value T<br> The object to be cached.

ttl TimeSpan?<br> Time-to-live. If null, a default system duration is used.

PutAsync<T> (String, T, TimeSpan?, CancellationToken)

Asynchronously store an item in the cache for a specific duration.

Task PutAsync<T>(string key, T value, TimeSpan? ttl = null, CancellationToken ct = null)

Type Parameters

T<br> The type of the item to store.

Parameters

key String<br> The unique cache key.

value T<br> The object to be cached.

ttl TimeSpan?<br> Time-to-live. If null, a default system duration is used.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<br> A task representing the asynchronous operation.

Add<T> (String, T, TimeSpan?)

Store an item in the cache only if it does not already exist.

bool Add<T>(string key, T value, TimeSpan? ttl = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

value T<br> The object to be cached.

ttl TimeSpan?<br> Time-to-live. If null, a default system duration is used.

Returns

Boolean<br> True if the item was added; false if it already existed.

AddAsync<T> (String, T, TimeSpan?, CancellationToken)

Asynchronously store an item in the cache only if it does not already exist.

Task<bool> AddAsync<T>(string key, T value, TimeSpan? ttl = null, CancellationToken ct = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

value T<br> The object to be cached.

ttl TimeSpan?<br> Time-to-live. If null, a default system duration is used.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<Boolean><br> A task containing true if the item was added; false if it already existed.

Forever<T> (String, T)

Store an item in the cache indefinitely.

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

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

value T<br> The object to be cached.

ForeverAsync<T> (String, T, CancellationToken)

Asynchronously store an item in the cache indefinitely.

Task ForeverAsync<T>(string key, T value, CancellationToken ct = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

value T<br> The object to be cached.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<br> A task representing the asynchronous operation.

Has (String)

Determine if an item exists in the cache.

bool Has(string key)

Parameters

key String<br> The cache key to check.

Returns

Boolean<br> True if the key exists; otherwise, false.

HasAsync (String, CancellationToken)

Asynchronously determine if an item exists in the cache.

Task<bool> HasAsync(string key, CancellationToken ct = null)

Parameters

key String<br> The cache key to check.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<Boolean><br> A task containing true if the key exists; otherwise, false.

Forget (String)

Remove an item from the cache by its key.

bool Forget(string key)

Parameters

key String<br> The key to remove.

Returns

Boolean<br> True if the item was successfully removed.

ForgetAsync (String, CancellationToken)

Asynchronously remove an item from the cache by its key.

Task<bool> ForgetAsync(string key, CancellationToken ct = null)

Parameters

key String<br> The key to remove.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<Boolean><br> A task containing true if the item was successfully removed.

Flush ()

Remove all items from the cache.

void Flush()

FlushAsync (CancellationToken)

Asynchronously remove all items from the cache.

Task FlushAsync(CancellationToken ct = null)

Parameters

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<br> A task representing the asynchronous operation.

Remember<T> (String, TimeSpan?, Func<IServiceProvider, T>)

Get an item from the cache, or execute the callback and store the result if the item is missing. Provides access to IServiceProvider within the callback for dependency resolution.

T Remember<T>(string key, TimeSpan? ttl, Func<IServiceProvider, T> callback)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The cache key.

ttl TimeSpan?<br> Time-to-live for the new cache entry.

callback Func<IServiceProvider, T><br> A delegate that receives a service provider and returns the data to cache.

Returns

T<br> The cached or freshly generated item.

**RememberAsync<T> (String, TimeSpan?, Func<IServiceProvider, CancellationToken, Task<T>>,

CancellationToken)**

Asynchronously get an item from the cache, or execute the callback and store the result if the item is missing.

Task<T> RememberAsync<T>(string key, TimeSpan? ttl, Func<IServiceProvider, CancellationToken, Task<T>> callback, CancellationToken ct = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The cache key.

ttl TimeSpan?<br> Time-to-live for the new cache entry.

callback Func<IServiceProvider, CancellationToken, Task<T>><br> An asynchronous delegate that receives a service provider, a cancellation token, and returns the data to cache.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<T><br> A task containing the cached or freshly generated item.

RememberForever<T> (String, Func<IServiceProvider, T>)

Get an item from the cache, or store the callback result indefinitely if the item is missing.

T RememberForever<T>(string key, Func<IServiceProvider, T> callback)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The cache key.

callback Func<IServiceProvider, T><br> A delegate that receives a service provider and returns the data to cache.

Returns

T<br> The cached or freshly generated item.

**RememberForeverAsync<T> (String, Func<IServiceProvider, CancellationToken, Task<T>>,

CancellationToken)**

Asynchronously get an item from the cache, or store the callback result indefinitely if the item is missing.

Task<T> RememberForeverAsync<T>(string key, Func<IServiceProvider, CancellationToken, Task<T>> callback, CancellationToken ct = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The cache key.

callback Func<IServiceProvider, CancellationToken, Task<T>><br> An asynchronous delegate that receives a service provider, a cancellation token, and returns the data to cache.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<T><br> A task containing the cached or freshly generated item.

Pull<T> (String)

Retrieve an item from the cache and then delete it.

T Pull<T>(string key)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

Returns

T<br> The cached item before its removal, or null.

PullAsync<T> (String, CancellationToken)

Asynchronously retrieve an item from the cache and then delete it.

Task<T> PullAsync<T>(string key, CancellationToken ct = null)

Type Parameters

T<br> The type of the item.

Parameters

key String<br> The unique cache key.

ct CancellationToken<br> A token to cancel the asynchronous operation.

Returns

Task<T><br> A task containing the cached item before its removal, or null.