Davasorus.Utility.DotNet.Cache 2026.2.2.3

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

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
);

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).

Performance Characteristics

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

Meters

Activity tags

Standard tags emitted on every operation:

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

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.

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

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

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.