Davasorus.Utility.DotNet.Cache 2026.2.2.14

Davasorus.Utility.DotNet.Cache

A unified, high-performance caching library for .NET 8+ that provides a common interface for multiple cache backends: in-memory, SQLite, and SQL Server.

Features

• Unified Interface: Common ICacheOperations interface across all backends
• Multiple Backends: Choose between in-memory (fast), SQLite (persistent, file-based), or SQL Server (distributed)
• Batch Operations: Get/set multiple items efficiently with GetManyAsync and SetManyAsync
• Smart Caching: Built-in GetOrSetAsync prevents cache stampede
• Statistics & Monitoring: Track cache performance with ICacheStatistics
• Key Pattern Operations: Search and remove by pattern with ICacheKeyOperations
• Service/Client Pattern: Scoped services with transient clients for dependency injection
• Expiration Support: Sliding and absolute expiration for all backends
• Type-Safe: Fully generic with strong typing
• Production Ready: Comprehensive test coverage (200+ tests)
• Async/Await: First-class async support with cancellation tokens

Installation

dotnet add package Davasorus.Utility.DotNet.Cache

When to use this package vs. .NET 9 HybridCache

.NET 9 introduced Microsoft.Extensions.Caching.Hybrid (HybridCache), Microsoft's first-party tiered (L1 in-memory + L2 distributed) cache abstraction. Our package partially overlaps with HybridCache but is designed for different use cases. Pick whichever fits your scenario.

Comparison

Concern	This package	Microsoft HybridCache (.NET 9+)
L1+L2 tiering	No (single backend per service)	Yes (built-in)
Memory-only use case	Yes (lightweight)	Overkill
SQLite persistence	Yes	No (not a built-in L2 option)
SqlServer persistence	Yes	Yes (via IDistributedCache)
Tag-based invalidation	Memory + SQLite only (SqlServer N/A)	Yes (built-in)
Stale-while-revalidate	Yes	No
Custom serializer	Yes	Yes
Custom compression	Yes	No
Stampede prevention	Yes	Yes (built-in)
Cache-key fidelity (null-vs-missing distinction)	Yes (TryGetAsync)	Limited
OTel instrumentation	First-class (operations/duration/errors/entries/evictions metrics + activity tags)	Limited
BenchmarkDotNet baseline	Yes (per-backend baseline included)	No

Pick HybridCache when

• You want L1+L2 tiering (in-memory + distributed) with minimal config.
• You're building on .NET 9+ and want the framework-blessed cache abstraction.
• Your use case is well-served by Microsoft's defaults; you don't need custom compression, SWR, or detailed metrics.

Pick this package when

• You want SQLite persistence for desktop apps, single-server scenarios, or tier-2 caching above an L1 in-memory cache (you can build the L1+SQLite combination yourself if needed).
• You want stale-while-revalidate semantics on cache reads (return stale while refreshing in background).
• You want custom compression (Brotli, Gzip) for large payloads, especially on SQLite/SqlServer.
• You want detailed OpenTelemetry instrumentation out of the box — cache.operations, cache.operation.duration, cache.errors, cache.entries, cache.evictions metrics plus rich activity tags.
• You want tag-based invalidation with a simple, predictable API.
• You're on .NET 8 (HybridCache requires .NET 9+).
• You want a deterministic, opinionated single-backend cache rather than a tiered abstraction.

Can I use both?

Yes — they're not mutually exclusive. A common pattern:

// Use HybridCache for the request-path L1+L2 caching (Microsoft's strength):
services.AddHybridCache();

// Use this package for a separate persistent SQLite cache for offline data:
services.AddSqliteCacheServices();

The two services live side-by-side in DI; consumers inject whichever is appropriate for the scenario.

Future direction

We currently don't bridge to HybridCache (don't implement its API; don't provide adapters to use our backends as HybridCache's L2). If you have a specific integration use case, please open an issue describing it — that demand signal would justify a future spec.

Quick Start

Memory Cache (In-Memory)

Perfect for high-performance, non-persistent caching.

Note: Memory cache stores references, not copies. Values you retrieve from MemoryCacheService are the same instances stored. Do not mutate retrieved objects — that mutation is visible to all subsequent readers of the same key. If you need copy semantics, clone the object after retrieval. (This matches the behavior of IMemoryCache, ConcurrentDictionary, and other in-process .NET caches.)

using Davasorus.Utility.DotNet.Cache.Configuration;

// Recommended: Use extension methods
services.AddMemoryCacheServices();

// Or with fluent configuration for batch operations
services.AddMemoryCacheServices(cache => cache
    .WithParallelBatching()
    .WithMaxDegreeOfParallelism(4)
    .WithBatchSize(100));

// Usage
public class MyService
{
	private readonly IMemoryCacheService _cache;

	public MyService(IMemoryCacheService cache)
	{
		_cache = cache;
	}

	public async Task<User> GetUserAsync(int userId)
	{
		var key = $"user:{userId}";

		// Get or create with factory pattern
		// Factory receives the cache key and a CancellationToken
		return await _cache.GetOrSetAsync(key, async (_, ct) =>
		{
			// This only runs if cache miss
			return await _database.GetUserAsync(userId, ct);
		}, new CacheOptions
		{
			SlidingExpiration = TimeSpan.FromMinutes(15)
		});
	}
}

SQLite Cache (File-Based Persistence)

Ideal for persistent caching in desktop apps or services without database infrastructure.

using Davasorus.Utility.DotNet.Cache.Configuration;

// Recommended: Use extension methods
services.AddSqliteCacheServices();

// Or with fluent configuration
services.AddSqliteCacheServices(cache => cache
    .DisableParallelBatching()
    .WithBatchSize(50));

// Initialize at startup
var cache = serviceProvider.GetRequiredService<ISqliteCacheService>();
await cache.InitializeAsync("./cache/app-cache.db");

// Usage
public class ProductService
{
	private readonly ISqliteCacheService _cache;

	public ProductService(ISqliteCacheService cache)
	{
		_cache = cache;
	}

	public async Task<List<Product>> GetProductsAsync(string category)
	{
		var key = $"products:{category}";
		var cached = await _cache.GetAsync<List<Product>>(key);

		if (cached != null)
			return cached;

		var products = await _database.GetProductsByCategoryAsync(category);

		await _cache.SetAsync(key, products, new CacheOptions
		{
			AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1)
		});

		return products;
	}

	// Database maintenance
	public async Task PerformMaintenanceAsync()
	{
		// Remove expired entries
		var removed = await _cache.PruneExpiredEntriesAsync();
		Console.WriteLine($"Removed {removed} expired entries");

		// Compact database
		await _cache.CompactDatabaseAsync();

		// Get statistics
		var stats = await _cache.GetStatisticsAsync();
		Console.WriteLine($"Cache size: {stats.SizeInBytes / 1024}KB");
	}
}

SQL Server Cache (Distributed)

Best for distributed applications requiring shared cache across multiple servers.

using Davasorus.Utility.DotNet.Cache.Configuration;

// Recommended: Use extension methods
services.AddSqlServerCacheServices();

// Or with fluent configuration
services.AddSqlServerCacheServices(cache => cache
    .WithSqlBatchSize(500)
    .WithBatchSize(100));

// Initialize at startup
var cache = serviceProvider.GetRequiredService<ISqlServerCacheService>();
await cache.InitializeAsync(
	connectionString: "Server=localhost;Database=AppCache;...",
	schemaName: "cache",
	tableName: "Cache"
);

// Note: You must create the cache table first using dotnet-sql-cache tool:
// dotnet tool install --global dotnet-sql-cache
// dotnet sql-cache create "Server=..." --schema cache --table Cache

// Usage
public class SessionService
{
	private readonly ISqlServerCacheService _cache;

	public SessionService(ISqlServerCacheService cache)
	{
		_cache = cache;
	}

	public async Task<Session> GetSessionAsync(string sessionId)
	{
		var key = $"session:{sessionId}";
		return await _cache.GetAsync<Session>(key);
	}

	public async Task SaveSessionAsync(string sessionId, Session session)
	{
		var key = $"session:{sessionId}";

		await _cache.SetAsync(key, session, new CacheOptions
		{
			// Session expires after 20 minutes of inactivity
			SlidingExpiration = TimeSpan.FromMinutes(20)
		});
	}
}

API Reference

Common Interface (ICacheOperations)

All cache services implement this unified interface:

public interface ICacheOperations : IAsyncDisposable
{
	// Get single value from cache
	Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default);

	// Get with explicit hit/miss disambiguation (distinguishes key-missing from stored-null)
	Task<(bool found, T? value)> TryGetAsync<T>(
		string key,
		CancellationToken cancellationToken = default
	);

	// Get multiple values in one operation
	Task<Dictionary<string, T?>> GetManyAsync<T>(
		IEnumerable<string> keys,
		CancellationToken cancellationToken = default
	);

	// Get from cache or create using factory (prevents cache stampede)
	// Factory receives the cache key and a CancellationToken
	Task<T?> GetOrSetAsync<T>(
		string key,
		Func<string, CancellationToken, Task<T>> factory,
		CacheOptions? options = null,
		CancellationToken cancellationToken = default
	);

	// Set single value in cache
	Task SetAsync<T>(
		string key,
		T value,
		CacheOptions? options = null,
		CancellationToken cancellationToken = default
	);

	// Set multiple values in one operation
	Task SetManyAsync<T>(
		Dictionary<string, T> items,
		CacheOptions? options = null,
		CancellationToken cancellationToken = default
	);

	// Remove value from cache
	Task<bool> RemoveAsync(string key, CancellationToken cancellationToken = default);

	// Check if key exists
	Task<bool> ExistsAsync(string key, CancellationToken cancellationToken = default);
}

Note: Initialization is implementation-specific. Each cache type provides its own initialization method with appropriate parameters (e.g., database path for SQLite, connection string for SQL Server). Memory cache requires no initialization.

Cache Options

public class CacheOptions
{
	// Sliding expiration - resets on access
	public TimeSpan? SlidingExpiration { get; set; }

	// Absolute expiration relative to now
	public TimeSpan? AbsoluteExpirationRelativeToNow { get; set; }

	// Absolute expiration at specific time
	public DateTimeOffset? AbsoluteExpiration { get; set; }

	// Priority (Memory cache only)
	public CacheItemPriority Priority { get; set; } // Low, Normal, High, NeverRemove
}

Statistics Interface (ICacheStatistics)

Memory and SQLite caches support detailed statistics. All backends return the canonical CacheStats record with three fields:

public interface ICacheStatistics
{
	Task<CacheStats> GetStatisticsAsync(CancellationToken cancellationToken = default);
}

public record CacheStats
{
	public long ItemCount { get; init; }              // Total items in cache
	public long? SizeInBytes { get; init; }           // Cache size in bytes (SQLite only; null otherwise)
	public long? ExpiredEntryCount { get; init; }     // Entries past expiration but not yet pruned (SQLite only)
}

Hit/miss/operation-count metrics are no longer fields on CacheStats. Consume them from the OTel cache.operations Counter on the backend's Meter instead (see "OpenTelemetry instrumentation" below).

Key Pattern Operations (ICacheKeyOperations)

Memory and SQLite caches support key pattern matching:

public interface ICacheKeyOperations
{
	// Get keys matching pattern (* and ? wildcards)
	Task<IEnumerable<string>> GetKeysAsync(
		string? pattern = null,
		CancellationToken cancellationToken = default
	);

	// Streaming key traversal — yields keys lazily without buffering the whole result set
	IAsyncEnumerable<string> EnumerateKeysAsync(
		string? pattern = null,
		CancellationToken cancellationToken = default
	);

	// Remove all keys matching pattern
	Task<int> RemoveByPatternAsync(
		string pattern,
		CancellationToken cancellationToken = default
	);
}

// Example usage:
var userKeys = await cache.GetKeysAsync("user:*");
var removedCount = await cache.RemoveByPatternAsync("session:expired:*");

// Streaming variant — useful for large key sets
await foreach (var key in cache.EnumerateKeysAsync("user:*"))
{
	// process each key without materializing the full list
}

Memory Cache Specific

// Implements: ICacheOperations, IClearableCache, ICacheStatistics, ICacheKeyOperations

// Synchronous key access
IEnumerable<string> GetAllKeys();

// Cache statistics — async only; returns the canonical CacheStats
Task<CacheStats> GetStatisticsAsync(CancellationToken cancellationToken = default);

SQLite Cache Specific

// Implements: ICacheOperations, IClearableCache, ICacheStatistics, ICacheKeyOperations

// Initialize database (must be called before use)
Task InitializeAsync(string databasePath, CancellationToken cancellationToken = default);

// Cache statistics — returns the canonical CacheStats record
// (ItemCount, SizeInBytes, ExpiredEntryCount)
Task<CacheStats> GetStatisticsAsync(CancellationToken cancellationToken = default);

// Remove expired entries
Task<int> PruneExpiredEntriesAsync(CancellationToken cancellationToken = default);

// Compact database file
Task CompactDatabaseAsync(CancellationToken cancellationToken = default);

SQL Server Cache Specific

// Implements: ICacheOperations only (no statistics or pattern operations)

// Initialize with connection string (must be called before use)
Task InitializeAsync(
	string connectionString,
	string schemaName = "cache",
	string tableName = "CacheData",
	CancellationToken cancellationToken = default
);

Pluggable Serializer

The cache package supports pluggable serialization via ICacheSerializer. The default implementation, JsonCacheSerializer, wraps System.Text.Json.

Customizing JsonSerializerOptions (incl. source-gen)

Register a JsonSerializerOptions with your JsonSerializerContext before calling the cache extension:

services.AddSingleton(new JsonSerializerOptions
{
    TypeInfoResolver = MyAppJsonContext.Default,
});
services.AddSqliteCacheServices(...);

JsonCacheSerializer will pick up the registered options. Source-gen context eliminates reflection overhead at serialization time.

Replacing the serializer entirely

Implement ICacheSerializer and register it as a singleton:

public sealed class MessagePackCacheSerializer : ICacheSerializer
{
    public byte[] Serialize<T>(T? value) =>
        MessagePack.MessagePackSerializer.Serialize(value);
    public T? Deserialize<T>(ReadOnlySpan<byte> payload) =>
        MessagePack.MessagePackSerializer.Deserialize<T>(payload);
}

services.AddSingleton<ICacheSerializer, MessagePackCacheSerializer>();
services.AddSqliteCacheServices(...);

The Memory backend does not use the serializer (it stores references directly).

Compression

The cache package supports pluggable compression via ICacheCompressor. Three implementations are shipped:

• NullCacheCompressor — no-op, prefixes the uncompressed marker (default).
• GzipCacheCompressor — gzip via System.IO.Compression.GZipStream.
• BrotliCacheCompressor — brotli via System.IO.Compression.BrotliStream.

Each compressor compresses payloads at or above its MinCompressionSizeBytes threshold (default 1024) and passes payloads below threshold through with the uncompressed marker. Compressors interop on read: each can read payloads written by itself OR the no-op compressor; cross-algorithm reads throw a helpful InvalidDataException.

services.AddSingleton<ICacheCompressor>(new BrotliCacheCompressor
{
    MinCompressionSizeBytes = 512,
});
services.AddSqliteCacheServices(...);

Tag-Based Invalidation

Memory and SQLite backends support tag-based invalidation: attach symbolic tags to cache entries when storing them, then invalidate groups of related entries by tag in O(tags-touched) time instead of O(all-keys).

// Tag entries on write:
await cache.SetAsync(
    $"user:{userId}:profile",
    profile,
    new CacheOptions { Tags = new[] { $"tenant-{tenantId}", "user-profiles" } });

// Invalidate everything for a tenant:
if (cache is ICacheTagInvalidation tagInvalidator)
{
    var removed = await tagInvalidator.InvalidateByTagAsync($"tenant-{tenantId}");
    logger.LogInformation("Removed {Count} entries for tenant {TenantId}", removed, tenantId);
}

// Invalidate the union of multiple tags (logical OR):
await tagInvalidator.InvalidateByTagsAsync(new[] { "tenant-42", "stale-reports" });

Backend support matrix

Backend	Tag invalidation
Memory	Yes
SQLite	Yes
SqlServer	Not supported (IDistributedCache has no per-entry metadata API)

Consumers writing backend-agnostic code can detect support via the runtime type-check shown above; backends that don't implement ICacheTagInvalidation simply omit the interface, and the cast returns false.

Atomicity

InvalidateByTagAsync removes everything tagged at the time the query starts. Entries added concurrently during the invalidation (with the same tag) survive. Consumers needing strict atomicity should coordinate externally (e.g., a write-side lock, or invalidate-then-recheck).

Activity instrumentation

Tag-based operations emit:

• operation="invalidateByTag" or "invalidateByTags" on the cache.operations Counter (and corresponding activity span).
• cache.invalidated_count activity tag — the number of entries removed.
• cache.tags activity tag — the tag(s) being invalidated. Opt-in via CacheOperationsOptions.RecordCacheTags = true (or the builder's WithCacheTagRecording(true)). Off by default to avoid high-cardinality tag explosion on busy systems.

Stale-While-Revalidate

Memory and SQLite backends support stale-while-revalidate (SWR): set CacheOptions.Refresh when caching a value, and after that duration passes, reads via GetOrSetAsync return the cached (stale) value immediately AND trigger a background refresh.

var profile = await cache.GetOrSetAsync(
    $"user:{userId}:profile",
    (key, ct) => fetchUserProfileAsync(userId, ct),
    new CacheOptions
    {
        AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(60),  // hard expiry
        Refresh = TimeSpan.FromMinutes(5),                            // stale after 5 min
    });

After 5 minutes, the next read returns the cached profile immediately and kicks off a background fetch. Concurrent stale reads see the same stale value — only one of them triggers the background refresh; the others are no-ops on the refresh path.

After 60 minutes (absolute expiry), the entry is gone; the next read is a normal cache miss with synchronous factory invocation.

Backend support matrix

Backend	SWR support
Memory	Yes
SQLite	Yes
SqlServer	Not supported (IDistributedCache has no per-entry CreatedAt metadata API). CacheOptions.Refresh is silently ignored.

Consumers writing backend-agnostic code don't need explicit detection — SWR is automatically a no-op on backends that don't support it.

Background refresh behavior

• Only one refresh per key runs at a time. Concurrent stale reads see the same stale value but don't all trigger separate refreshes (the per-key lock from cache stampede prevention coordinates).
• Background refresh uses CancellationToken.None — the caller's cancellation does NOT cancel work other concurrent callers benefit from. If you need bounded refresh time, your factory should set its own cancellation token internally.
• If the background factory throws, the error is logged at Warning level. The cache keeps the stale value; the next stale read triggers another refresh attempt (thundering retry, idiomatic for SWR).
• Background refresh writes to the cache via the same pipeline as foreground writes (serializer, compressor, tag preservation if applicable).

Activity instrumentation

SWR adds three new activity tags:

• cache.is_stale (bool) on getOrSet activities — true when the read returned a stale value.
• cache.refresh_started (bool) — true if THIS caller's read triggered the background refresh (vs. another caller already running it).
• cache.refresh_complete (bool) on the synthetic backgroundRefresh activity — true on success, false on factory exception.

The cache.operations Counter's result tag gains a new value:

• result="hit" — fresh cached value (not stale).
• result="stale" — cached value past refresh window; background refresh kicked off.
• result="miss" — factory ran synchronously (cache empty).

Recent Breaking Changes

This section documents breaking changes shipped in the most recent release. For older breaking changes, consult the package's git history and GitHub release notes.

Spec B: API consolidation

1. GetStatistics / GetStatisticsAsync returns CacheStats

The backend-specific stats types (CacheStatistics, SqliteCacheStatistics) have been deleted. All backends now return the canonical CacheStats record with three fields: ItemCount (long), SizeInBytes (long?), and ExpiredEntryCount (long?).

// BEFORE
var stats = await sqliteService.GetStatisticsAsync();
var entries = stats.EntryCount;
var dbSize  = stats.DatabaseSize;

// AFTER
var stats = await sqliteService.GetStatisticsAsync();
var entries = stats.ItemCount;       // long
var bytes   = stats.SizeInBytes;     // long?
var expired = stats.ExpiredEntryCount; // long?

Memory's GetStatistics() (sync) is replaced by GetStatisticsAsync():

// BEFORE
var stats = memoryService.GetStatistics();

// AFTER
var stats = await memoryService.GetStatisticsAsync();

Hit-rate and operation-count metrics are no longer stats fields — consume them from the OTel cache.operations Counter on the backend's Meter instead.

2. GetOrSetAsync factory takes (string key, CancellationToken ct)

The factory delegate signature has changed from Func<Task<T>> to Func<string, CancellationToken, Task<T>>.

// BEFORE
await cache.GetOrSetAsync("user:42", () => fetchUserAsync(42));

// AFTER (using the key from the factory)
await cache.GetOrSetAsync("user:42", (key, ct) =>
    fetchUserAsync(int.Parse(key.Split(':')[1]), ct));

// AFTER (ignoring the new parameters with discards)
await cache.GetOrSetAsync("user:42", (_, _) => fetchUserAsync(42));

Additionally, GetOrSetAsync now distinguishes "key missing" from "key present with stored null." Previously, a stored null re-invoked the factory; with the new internal use of TryGetAsync, a stored null is treated as a cache hit and the factory is not invoked. Consumers relying on the old behavior should call RemoveAsync(key) before GetOrSetAsync.

3. Activity-tag operation values shifted

GetAsync is now a thin wrapper over TryGetAsync. As a result, calls to GetAsync emit metrics under operation="tryGet" (not operation="get"). Existing dashboards filtering on operation="get" should be updated to filter on operation="tryGet" (or use operation IN ("get", "tryGet") to capture both pre- and post-Spec-B data).

New additive features

• Task<(bool found, T? value)> TryGetAsync<T>(string key, CancellationToken) on ICacheOperations — distinguishes key-missing from stored-null.
• IAsyncEnumerable<string> EnumerateKeysAsync(string? pattern, CancellationToken) on ICacheKeyOperations — streaming key traversal (Memory + SQLite).

Spec E: Pluggable serializer + compression

Schema change for SQLite caches

The SQLite Cache table's Value column changed from TEXT to BLOB. Existing SQLite cache files written by earlier versions of this package are incompatible with the new format and will fail to read.

Migration: delete the old cache file before upgrading.

if (File.Exists(databasePath))
    File.Delete(databasePath);

await sqliteCacheService.InitializeAsync(databasePath);

The cache will repopulate organically.

Schema change for SqlServer caches

The [cache].[CacheData] table schema is unchanged, but the byte format of the Value column has changed (now includes a 1-byte compression marker prefix). Existing rows are unreadable.

Migration:

TRUNCATE TABLE [cache].[CacheData];

The cache will repopulate organically.

No migration for Memory caches

The Memory backend stores references in-process. Process restart clears everything; no migration action needed.

Constructor change for direct (non-DI) instantiation

SqliteCacheClient and SqlServerCacheClient constructors now require ICacheSerializer and ICacheCompressor parameters. DI consumers are unaffected — the cache extensions register JsonCacheSerializer and NullCacheCompressor as defaults.

If you instantiate clients directly (not via DI):

// BEFORE
var client = new SqliteCacheClient();

// AFTER
var client = new SqliteCacheClient(
    new JsonCacheSerializer(),
    new NullCacheCompressor());

Performance Characteristics

Backend	Speed	Persistence	Distributed	Statistics	Pattern Ops	Use Case
Memory	Fastest	No	No	Yes	Yes	High-frequency, session data
SQLite	Fast	Yes	No	Yes	Yes	Single-server, desktop apps
SQL Server	Moderate	Yes	Yes	No	No	Multi-server, distributed applications

OpenTelemetry instrumentation

The cache services emit OpenTelemetry traces and metrics through the Davasorus.Utility.DotNet.Telemetry package. All instrumentation is zero-cost when no listener is attached — safe to leave on in production.

ActivitySources

Backend	ActivitySource
Memory	Davasorus.Utility.Cache.memory
SQLite	Davasorus.Utility.Cache.sqlite
SqlServer	Davasorus.Utility.Cache.mssql

Meters

Backend	Meter
Memory	Davasorus.Utility.Cache.memory
SQLite	Davasorus.Utility.Cache.sqlite
SqlServer	Davasorus.Utility.Cache.mssql

Activity tags

Standard tags emitted on every operation:

Tag	Description
cache.backend	memory | sqlite | mssql
cache.result	hit | miss | ok | removed | cancelled | error
db.operation.name	get | set | remove | getOrSet | getMany | setMany | clear | exists | ...
db.system.name	sqlite | mssql (Memory backend omits this tag)
db.collection.name	<schema>.<table> (SqlServer only, after InitializeAsync)
cache.lock_waited	bool — True if the GetOrSet caller waited on a contended per-key lock (i.e., observed stampede protection); false if no contention or fast-path hit. Emitted on getOrSet operations only.

cache.key is opt-in — set RecordCacheKeys = true (default false) to stamp the literal key on activity tags. Leave disabled for caches with high-cardinality keyspaces (user IDs, session tokens) to avoid blowing up trace storage.

Metrics

Instrument	Type	Backends	Tags
cache.operations	Counter	all	operation, backend, result
cache.operation.duration	Histogram (ms)	all	operation, backend
cache.errors	Counter	all	operation, backend, exception.type
cache.entries	ObservableGauge	Memory, SQLite	backend
cache.evictions	Counter	Memory, SQLite	backend, reason

SqlServer does not expose cache.entries or cache.evictions — the underlying IDistributedCache abstraction has no cheap entry-count or eviction signals.

Configuring cache-key recording

services.AddMemoryCacheServices(cache => cache
    .WithCacheKeyRecording(true));   // opts in to stamping cache.key on traces

WithCacheKeyRecording(false) is equivalent to the default and explicitly disables recording.

Service lifetime requirement

Cache services (IMemoryCacheService, ISqliteCacheService, ISqlServerCacheService) must be registered as singletons. The AddMemoryCacheServices / AddSqliteCacheServices / AddSqlServerCacheServices extensions do this for you. Manual scoped or transient registration causes the eviction-counter wiring (which takes a strong reference to the cache client) to retain across DI scopes, leaking memory and producing inconsistent metrics over the process lifetime.

The cache.entries ObservableGauge is registered exactly once per backend Meter via a static guard, so it does not leak even under non-singleton registration — but the eviction wiring still does. Always use the provided extension methods.

Health Checks

The package ships IHealthCheck implementations for the SQLite and SqlServer cache backends. Register them in your existing IHealthChecksBuilder pipeline:

services
    .AddHealthChecks()
    .AddSqliteCacheHealthCheck()
    .AddSqlServerCacheHealthCheck();

The checks probe the cache by writing a reserved key (__healthcheck__) with a one-minute TTL and reading it back. They return:

• Healthy — write and read both succeeded and the value roundtripped.
• Degraded — write succeeded but the probe key was missing on read or came back with the wrong value.
• Unhealthy — operation threw (cache backend unreachable, schema is missing, permissions are wrong, etc.).

The Memory backend doesn't have a health check — Memory is in-process, so liveness equals process-up.

Customization

Pass a custom name, failure status, tags, or timeout (standard health-check library options):

.AddSqliteCacheHealthCheck(
    name: "primary-cache",
    failureStatus: HealthStatus.Degraded,
    tags: new[] { "ready", "cache" },
    timeout: TimeSpan.FromSeconds(5))

Best Practices

1. Use GetOrSetAsync to Prevent Cache Stampede

// BAD: Multiple requests may hit database simultaneously
var cached = await cache.GetAsync<Data>(key);
if (cached == null)
{
	cached = await ExpensiveOperation(); // Multiple threads may execute this
	await cache.SetAsync(key, cached);
}

// GOOD: Only one request hits database
// Factory receives (cache key, CancellationToken)
var result = await cache.GetOrSetAsync(key, async (_, ct) =>
	await ExpensiveOperation(ct) // Only executed once
);

2. Choose Appropriate Expiration

// Sliding: Resets on access (good for user sessions)
SlidingExpiration = TimeSpan.FromMinutes(20)

// Absolute: Expires at specific time (good for time-sensitive data)
AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1)
AbsoluteExpiration = DateTimeOffset.UtcNow.AddHours(1)

3. Use Meaningful Cache Keys

// BAD: Unclear
var key = "u123";

// GOOD: Clear namespace and purpose
var key = $"user:profile:{userId}";
var key = $"products:category:{categoryId}:page:{pageNum}";

4. Handle Nulls Appropriately

var user = await cache.GetAsync<User>(key);

// GetAsync returns null for cache miss AND when null was cached.
// If you need to distinguish, prefer TryGetAsync (single round-trip):
var (found, cachedUser) = await cache.TryGetAsync<User>(key);
if (!found)
{
	// Definitely a cache miss
}
else
{
	// Hit (cachedUser may legitimately be null if a null was stored)
}

5. SQLite Maintenance

// Run maintenance periodically (e.g., daily background job)
await cache.PruneExpiredEntriesAsync(); // Remove expired entries
await cache.CompactDatabaseAsync(); // Reclaim space

6. SQL Server Table Setup

// Must create table before using SQL Server cache
// Use dotnet-sql-cache tool:
// dotnet tool install --global dotnet-sql-cache
// dotnet sql-cache create "YourConnectionString" --schema cache --table Cache

Cache stampede prevention via GetOrSetAsync

GetOrSetAsync provides built-in stampede prevention: when multiple callers concurrently request the same key with a missing value, only one caller's factory delegate is invoked. The other callers wait for the factory to complete and receive the same cached result.

Lock granularity is per-key: callers requesting different keys run in parallel. The lock is held only for the duration of the factory plus the cache write, then released. Lock cleanup is automatic — the internal lock map self-drains when no waiters remain.

Cancellation: if a caller's CancellationToken fires while waiting for the lock or during the factory, the caller observes OperationCanceledException immediately. The cache state is not modified by a cancelled caller.

Factory exceptions: if the designated factory caller throws, the exception propagates to that caller. Other waiters retry: they acquire the lock next, check the cache (still empty), and become the new designated factory caller. This "thundering retry" pattern is idiomatic for cache stampedes; if you want exception-caching semantics (where a transient error is briefly cached to avoid hammering an unhealthy backend), see the future stale-while-revalidate work tracked under Spec G.

Testing

The package includes 200+ tests covering all functionality:

cd "DotNet/12 Davasorus.Utility.DotNet.Cache"
dotnet test --configuration Release

All tests pass, including:

• Core cache operations (Get, Set, Remove, Exists)
• Batch operations (GetMany, SetMany)
• GetOrSetAsync pattern
• Expiration (sliding and absolute)
• Statistics and key pattern operations
• Service layer validation and logging
• Configuration and DI extension methods
• SQL Server integration tests with Testcontainers

Running benchmarks

The package includes a BenchmarkDotNet suite for measuring per-backend performance. Benchmarks run on-demand (not in CI) — full BDN runs take minutes per class, well beyond CI budget.

cd Davasorus.Utility.DotNet.Cache.Benchmarks

# Run every benchmark on .NET 8:
dotnet run -c Release --framework net8.0

# Same on .NET 10:
dotnet run -c Release --framework net10.0

# Filter to a specific class:
dotnet run -c Release --framework net8.0 -- --filter '*Memory*'

# List all benchmarks without running:
dotnet run -c Release --framework net8.0 -- --list flat

The benchmark project multi-targets net8.0;net10.0, so dotnet run requires an explicit --framework <tfm> flag.

SqlServer benchmarks require Docker running locally (Testcontainers spins up a SQL Server 2022 container). Memory and SQLite benchmarks have no external dependencies.

Results land in Davasorus.Utility.DotNet.Cache.Benchmarks/BenchmarkDotNet.Artifacts/results/ (gitignored). Use them as a baseline when evaluating perf-sensitive changes (Spec D per-key locking, Spec E pluggable serializer + compression, etc.).

Advanced Usage

Custom Serialization

// By default, System.Text.Json is used
// Complex types are automatically serialized/deserialized

public class ComplexObject
{
	public int Id { get; set; }
	public List<string> Tags { get; set; }
	public Dictionary<string, object> Metadata { get; set; }
}

await cache.SetAsync("key", new ComplexObject { ... });
var obj = await cache.GetAsync<ComplexObject>("key");

Batch Operations

// Retrieve multiple cache entries at once
var keys = new[] { "user:1", "user:2", "user:3" };
var results = await cache.GetManyAsync<User>(keys);

foreach (var kvp in results)
{
	Console.WriteLine($"{kvp.Key}: {kvp.Value?.Name ?? "not found"}");
}

// Set multiple cache entries at once
var users = new Dictionary<string, User>
{
	["user:1"] = new User { Id = 1, Name = "Alice" },
	["user:2"] = new User { Id = 2, Name = "Bob" },
	["user:3"] = new User { Id = 3, Name = "Charlie" }
};

await cache.SetManyAsync(users, new CacheOptions
{
	SlidingExpiration = TimeSpan.FromMinutes(15)
});

Statistics and Monitoring

// Get cache statistics (Memory and SQLite only)
var stats = await cache.GetStatisticsAsync();

Console.WriteLine($"Items: {stats.ItemCount}");
Console.WriteLine($"Size: {stats.SizeInBytes / 1024}KB");        // SQLite only; null on memory backend
Console.WriteLine($"Expired: {stats.ExpiredEntryCount}");        // SQLite only; null on memory backend

// Hit rate, hit/miss counts, and oldest-entry timestamps are no longer fields on
// CacheStats. Consume those from the OTel `cache.operations` Counter on the
// backend's Meter (see "OpenTelemetry instrumentation" above).

Key Pattern Operations

// Get all keys matching a pattern (Memory and SQLite only)
var sessionKeys = await cache.GetKeysAsync("session:*");
var userKeys = await cache.GetKeysAsync("user:profile:*");

// Remove all keys matching a pattern
var removed = await cache.RemoveByPatternAsync("temp:*");
Console.WriteLine($"Removed {removed} temporary items");

// Clear specific user's cache
await cache.RemoveByPatternAsync($"user:{userId}:*");

Dependency Injection Setup

Recommended: Extension Methods

using Davasorus.Utility.DotNet.Cache.Configuration;

public void ConfigureServices(IServiceCollection services)
{
	// Memory cache (with defaults)
	services.AddMemoryCacheServices();

	// SQLite cache (with defaults)
	services.AddSqliteCacheServices();

	// SQL Server cache (with defaults)
	services.AddSqlServerCacheServices();

	// Or with fluent configuration
	services.AddMemoryCacheServices(cache => cache
		.WithParallelBatching()
		.WithMaxDegreeOfParallelism(4)
		.WithBatchSize(100));

	// Or from appsettings.json
	services.AddMemoryCacheServices(Configuration.GetSection("CacheOptions"));
}

Manual Registration

// Memory cache — service and client must both be singletons
services.AddMemoryCache();
services.AddSingleton<IMemoryCacheClient, MemoryCacheClient>();
services.AddSingleton<IMemoryCacheService, MemoryCacheService>();

// SQLite cache — service must be singleton
services.AddSingleton<ISqliteCacheClient, SqliteCacheClient>();
services.AddSingleton<ISqliteCacheService, SqliteCacheService>();

// SQL Server cache — service must be singleton; client stays transient
services.AddTransient<ISqlServerCacheClient, SqlServerCacheClient>();
services.AddSingleton<ISqlServerCacheService, SqlServerCacheService>();

Initialization

// SQLite and SQL Server caches require initialization at startup
var sqliteCache = serviceProvider.GetRequiredService<ISqliteCacheService>();
await sqliteCache.InitializeAsync("./data/cache.db");

var sqlServerCache = serviceProvider.GetRequiredService<ISqlServerCacheService>();
await sqlServerCache.InitializeAsync(Configuration.GetConnectionString("Cache"));

Troubleshooting

SQL Server: "Invalid object name 'cache.Cache'"

Solution: Create the cache table using dotnet-sql-cache tool before initializing.

dotnet tool install --global dotnet-sql-cache
dotnet sql-cache create "Server=...;Database=..." --schema cache --table Cache

SQLite: Database file locked

Solution: Ensure only one process accesses the database, or use Cache = SqliteCacheMode.Shared in connection string (already default).

Memory: High memory usage

Solution: Set cache priorities and size limits:

services.AddMemoryCache(options =>
{
	options.SizeLimit = 1024; // Limit total size
	options.CompactionPercentage = 0.25; // Compact by 25% when limit hit
});

// Use priorities
await cache.SetAsync(key, value, new CacheOptions
{
	Priority = CacheItemPriority.Low // Will be evicted first
});

Migration Guide

From IMemoryCache to This Package

// Before
_memoryCache.Set("key", value, TimeSpan.FromMinutes(5));
var cached = _memoryCache.Get<MyType>("key");

// After
await _cache.SetAsync("key", value, new CacheOptions
{
	AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5)
});
var cached = await _cache.GetAsync<MyType>("key");

From IDistributedCache to This Package

// Before
var bytes = await _distributedCache.GetAsync("key");
var value = JsonSerializer.Deserialize<MyType>(bytes);

// After
var value = await _cache.GetAsync<MyType>("key");

License

This package follows the repository license.

Contributing

Contributions are welcome! Please follow the repository's contribution guidelines in NEWCOMERS.md.

Support

For issues, questions, or feature requests, please refer to the repository's issue tracker.