LowCodeHub.AdvancedHybridCache 0.0.3

LowCodeHub.AdvancedHybridCache

A typed, region-aware wrapper over Microsoft.Extensions.Caching.Hybrid for .NET 10.

It keeps the native HybridCache behavior, including stampede protection, local cache, distributed cache support, tag invalidation, and serializer extensibility, while adding a small LowCodeHub-friendly API:

• CacheKey for collision-safe region/key composition.
• IAdvancedHybridCache for get, set, remove, and tag invalidation operations.
• CacheGetResult<T> for explicit cache hit/miss results.
• AddAdvancedHybridCache(...) for DI registration that still returns IHybridCacheBuilder.

Why This Library?

Installation

dotnet add package LowCodeHub.AdvancedHybridCache

Targets net10.0.

Quick Start

using LowCodeHub.AdvancedHybridCache.Abstractions;
using LowCodeHub.AdvancedHybridCache.Extensions;
using LowCodeHub.AdvancedHybridCache.Models;
using Microsoft.Extensions.Caching.Hybrid;

builder.Services
    .AddAdvancedHybridCache(options =>
    {
        options.DefaultEntryOptions = new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromMinutes(10),
            LocalCacheExpiration = TimeSpan.FromMinutes(2)
        };
    });

Use it from application services:

public sealed class ProductService(IAdvancedHybridCache cache)
{
    public ValueTask<Product> GetProductAsync(Guid productId, CancellationToken cancellationToken = default)
    {
        var cacheKey = new CacheKey(
            region: "products",
            key: productId.ToString(),
            tags: ["products"]);

        return cache.GetOrCreateAsync(
            cacheKey,
            token => LoadProductAsync(productId, token),
            cancellationToken);
    }

    private static ValueTask<Product> LoadProductAsync(Guid productId, CancellationToken cancellationToken)
    {
        // Load from your database, API, or other source of truth.
        throw new NotImplementedException();
    }
}

Try-Get Without Ambiguous Defaults

HybridCache primarily exposes GetOrCreateAsync. This package adds a try-get shape that does not confuse a cache miss with a cached default value:

var result = await cache.TryGetAsync<int>(
    new CacheKey("product-inventory", productId.ToString(), ["inventory"]),
    cancellationToken);

if (!result.Found)
{
    return Results.NotFound();
}

return Results.Ok(result.Value);

This matters for valid cached values such as:

• 0
• false
• null
• default(T)

Use result.Found to decide whether the entry exists. Use result.Value only after that check.

Cache Keys

CacheKey has three parts:

var cacheKey = new CacheKey(
    region: "tenant-settings",
    key: tenantId.ToString(),
    tags: [$"tenant:{tenantId}", "tenant-settings"]);

The generated cache key is length-prefixed, so regions and keys that contain : do not collide.

Set and Remove

Set a value directly:

await cache.SetAsync(
    new CacheKey("feature-flags", tenantId.ToString(), [$"tenant:{tenantId}", "feature-flags"]),
    flags,
    cancellationToken);

Set with per-entry expiration:

await cache.SetAsync(
    new CacheKey("reports", reportId.ToString(), ["reports"]),
    report,
    new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromHours(1),
        LocalCacheExpiration = TimeSpan.FromMinutes(5)
    },
    cancellationToken);

Remove one entry:

await cache.RemoveAsync(new CacheKey("products", productId.ToString()), cancellationToken);

Remove entries by tag:

await cache.RemoveByTagAsync("products", cancellationToken);

Distributed Cache Backend

AddAdvancedHybridCache registers Microsoft HybridCache. If your application also registers an IDistributedCache implementation, HybridCache can use it as the distributed tier.

Redis example:

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
});

builder.Services.AddAdvancedHybridCache();

Without a distributed cache registration, HybridCache still provides local in-process caching.

Serializers

The registration method returns IHybridCacheBuilder, so you can configure serializers exactly as you would with native HybridCache:

builder.Services
    .AddAdvancedHybridCache()
    .AddSerializerFactory<MyHybridCacheSerializerFactory>();

Use a serializer factory when your cached payload types need custom serialization behavior. The wrapper stores cached values in CacheGetResult<T> so it can preserve hit/miss semantics for cached default values. Prefer serializer factories that can handle generic wrapper types, or rely on the default System.Text.Json-based serializer for regular POCO payloads.

Configuration

Example appsettings shape:

{
  "HybridCache": {
    "DefaultExpiration": "00:10:00",
    "DefaultLocalExpiration": "00:02:00"
  }
}

Example binding:

builder.Services.AddAdvancedHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = builder.Configuration.GetValue<TimeSpan>("HybridCache:DefaultExpiration"),
        LocalCacheExpiration = builder.Configuration.GetValue<TimeSpan>("HybridCache:DefaultLocalExpiration")
    };
});

Behavior Notes

• GetOrCreateAsync uses HybridCache stampede protection for concurrent misses.
• TryGetAsync never calls a source callback; it returns Found = false on a miss.
• Tags are not part of the cache identity; they are passed to HybridCache for invalidation.
• CacheKey.Region and CacheKey.Key must be non-empty and non-whitespace.
• If underlying data retrieval is disabled through HybridCache entry options and the entry is missing, GetOrCreateAsync throws InvalidOperationException.