Resrcify.SharedKernel.Caching 4.4.0

Resrcify.SharedKernel.Caching

Resrcify.SharedKernel.Caching provides an IDistributedCache-based caching service with typed serialization helpers and simple expiration APIs.

Table of Contents

• Resrcify.SharedKernel.Caching
  • Table of Contents
  • What you get
  • Prerequisites
  • Install
    • Option A: Project reference
    • Option B: NuGet package
  • Quick Start
  • Usage guide
    • Set cache values
    • Get cache values
    • Remove values and bulk get
    • Claim a key (do something once)
  • Common issues
  • Related modules

What you get

• ICachingService abstraction in Resrcify.SharedKernel.Abstractions.Caching.
• DistributedCachingService implementation in Primitives/, registered with services.AddDistributedCaching() (Extensions/).
• Typed JSON serialization via System.Text.Json.
• Support for:
  • Sliding expiration (TimeSpan)
  • Absolute expiration (DateTimeOffset)
  • Bulk retrieval by keys (GetBulkAsync<T>)
  • Claims (IClaimStore.TryClaimForAsync): set a key only if nobody holds it
• Values serialized with the caller's JsonSerializerOptions (indentation and escaping too).

Prerequisites

• .NET 10 SDK.
• A configured IDistributedCache provider (memory, Redis, SQL Server, etc.).

Install

Option A: Project reference

<ProjectReference Include="..\path\to\Resrcify.SharedKernel.Caching.csproj" />

Option B: NuGet package

<PackageReference Include="Resrcify.SharedKernel.Caching" Version="<latest>" />

CLI:

dotnet add package Resrcify.SharedKernel.Caching

Quick Start

using Resrcify.SharedKernel.Caching.Extensions;

services.AddDistributedCaching();
// or, tuning the in-memory cache:
services.AddDistributedCaching(cache => cache.SizeLimit = 1024 * 1024 * 1024);

AddDistributedCaching registers, in one call: the in-memory IDistributedCache (AddDistributedMemoryCache, which configure tunes) unless one is registered already (Redis, registered before it, is kept); DistributedCachingService as the ICachingService and the IClaimStore, one singleton (the mediator's idempotency behavior and the message bus' duplicate skipping claim keys through it); and the system TimeProvider unless one is registered (before or after). An ICachingService or IClaimStore registered before is kept. It replaces:

services.AddDistributedMemoryCache();
services.AddSingleton<ICachingService, DistributedCachingService>();

Usage guide

Set cache values

Every entry expires, and how long it lives is in the method's name:

// A one-time code: gone after 5 minutes, however often it is read.
await cachingService.SetForAsync($"otc:{email}", code, TimeSpan.FromMinutes(5), cancellationToken);

// A user profile: kept while it is in use.
await cachingService.SetSlidingAsync("users:42", userDto, TimeSpan.FromMinutes(10), cancellationToken);

An implementation provides one method, SetAsync(key, value, absoluteExpiration, slidingExpiration, serializerOptions, cancellationToken); the others call it. It refuses an entry with neither expiration: one that never expires stays until the cache runs out of memory. Data kept until the next update replaces it gets a lifetime longer than the update interval, and its readers handle it being gone.

Get cache values

UserDto? cachedUser = await cachingService.GetAsync<UserDto>(
    key: "users:42",
    cancellationToken: cancellationToken);

Remove values and bulk get

await cachingService.RemoveAsync(
    key: "users:42",
    cancellationToken: cancellationToken);

IEnumerable<UserDto?> cachedUsers = await cachingService.GetBulkAsync<UserDto>(
    keys: ["users:1", "users:2", "users:3"],
    cancellationToken: cancellationToken);

Claim a key (do something once)

// IClaimStore claims (DistributedCachingService is one)
if (await claims.TryClaimForAsync("payouts:sent:42", TimeSpan.FromHours(3), cancellationToken))
{
    // this caller holds the claim; release it with ReleaseAsync if the work must be retried
}

A claim is a marker, not a value: claims are a separate interface (IClaimStore) from the cache, and a claim key is never read with GetAsync or written with SetAsync. DistributedCachingService claims atomically within one process only (IDistributedCache can't set a key only if it is absent): two instances sharing a cache can both claim a key. An ICachingService over Redis can claim across processes with SET key value PX <ms> NX.

Common issues

• If cache entries never expire, verify the provider supports requested expiration settings.
• If deserialization fails, ensure cached payload schema matches the expected type.
• If performance degrades on bulk operations, review provider latency and key count per request.

Related modules

• Resrcify.SharedKernel.Mediator includes CachingPipelineBehavior<TRequest, TResponse> for cache-aside query handling.