DevelopmentHelpers.AzureDistributedCache 11.0.0

DevelopmentHelpers.AzureDistributedCache

A .NET library that simplifies Azure Redis Cache integration with support for both IDistributedCache and HybridCache APIs.

✨ Features

📦 Installation

dotnet add package DevelopmentHelpers.AzureDistributedCache

🚀 Quick Start

1. Add Configuration

Add to your appsettings.json:

{
  "DevelopmentHelpers": {
	"AzureDistributedCacheConfiguration": {
	  "DnsName": "your-cache.redis.cache.windows.net",
	  "ConnectionString": "your-cache.redis.cache.windows.net:6380,password=xxx,ssl=True,abortConnect=False"
	},
	"HybridCacheConfiguration": {
	  "DefaultExpiration": "00:05:00",
	  "DefaultLocalCacheExpiration": "00:02:00",
	  "MaximumPayloadBytes": 1048576,
	  "MaximumKeyLength": 1024
	}
  }
}

2. Register Services

Option A: HybridCache (Recommended)

// Program.cs
builder.Services.AddAzureHybridCache(builder.Configuration);

Option B: IDistributedCache Only

// Program.cs
builder.Services.AddAzureRedisCache(builder.Configuration);

3. Use in Your Code

HybridCache (Recommended Pattern)

public class ProductService
{
	private readonly HybridCache _cache;
	private readonly ILogger<ProductService> _logger;

	public ProductService(HybridCache cache, ILogger<ProductService> logger)
	{
		_cache = cache;
		_logger = logger;
	}

	public async Task<Product?> GetProductAsync(int productId, CancellationToken ct = default)
	{
		// HybridCache handles everything:
		// ✓ Checks L1 (memory) then L2 (Redis)
		// ✓ Calls factory only on cache miss
		// ✓ Prevents stampede (parallel requests wait)
		// ✓ Serializes/deserializes automatically

		return await _cache.GetOrCreateAsync(
			$"product:{productId}",
			async token => await FetchProductFromDatabaseAsync(productId, token),
			new HybridCacheEntryOptions
			{
				Expiration = TimeSpan.FromMinutes(10),
				LocalCacheExpiration = TimeSpan.FromMinutes(2)
			},
			cancellationToken: ct);
	}

	public async Task InvalidateProductAsync(int productId)
	{
		await _cache.RemoveAsync($"product:{productId}");
		_logger.LogInformation("Invalidated cache for product {ProductId}", productId);
	}
}

IDistributedCache (Traditional Pattern)

public class ProductService
{
	private readonly IDistributedCache _cache;
	private readonly ILogger<ProductService> _logger;

	public ProductService(IDistributedCache cache, ILogger<ProductService> logger)
	{
		_cache = cache;
		_logger = logger;
	}

	public async Task<Product?> GetProductAsync(int productId, CancellationToken ct = default)
	{
		var cacheKey = $"product:{productId}";

		// Check cache
		var cached = await _cache.GetStringAsync(cacheKey, ct);
		if (cached != null)
		{
			_logger.LogDebug("Cache hit for {CacheKey}", cacheKey);
			return JsonSerializer.Deserialize<Product>(cached);
		}

		// Cache miss - fetch from database
		_logger.LogDebug("Cache miss for {CacheKey}", cacheKey);
		var product = await FetchProductFromDatabaseAsync(productId, ct);

		if (product != null)
		{
			var options = new DistributedCacheEntryOptions
			{
				AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(10),
				SlidingExpiration = TimeSpan.FromMinutes(2)
			};

			await _cache.SetStringAsync(
				cacheKey,
				JsonSerializer.Serialize(product),
				options,
				ct);
		}

		return product;
	}
}

⚙️ Configuration Options

AzureDistributedCacheConfiguration

HybridCacheConfiguration

📝 Registration Overloads

// From IConfiguration
services.AddAzureHybridCache(configuration);
services.AddAzureRedisCache(configuration);

// With explicit settings
services.AddAzureHybridCache(cacheSettings, hybridSettings);
services.AddAzureRedisCache(cacheSettings);

// With connection string
services.AddAzureHybridCache(connectionString, dnsName, hybridSettings);
services.AddAzureRedisCache(connectionString, dnsName);

📊 Logging

The library uses structured logging with ILogger<AzureRedisCache>. All cache operations are logged:

Configure logging in appsettings.json:

{
  "Logging": {
	"LogLevel": {
	  "Default": "Information",
	  "DevelopmentHelpers.AzureDistributedCache": "Debug"
	}
  }
}

💡 Best Practices

Cache Key Design

// ✅ Good: Hierarchical, descriptive keys
var key = $"user:{userId}:profile";
var key = $"products:category:{categoryId}:page:{page}";

// ❌ Avoid: Generic, non-descriptive keys
var key = "data1";
var key = userId.ToString();

Expiration Strategy

// High-traffic, rarely changing data
new HybridCacheEntryOptions
{
	Expiration = TimeSpan.FromHours(1),
	LocalCacheExpiration = TimeSpan.FromMinutes(10)
}

// Frequently updated data
new HybridCacheEntryOptions
{
	Expiration = TimeSpan.FromMinutes(5),
	LocalCacheExpiration = TimeSpan.FromMinutes(1)
}

Error Handling

public async Task<Product?> GetProductSafeAsync(int id)
{
	try
	{
		return await _cache.GetOrCreateAsync(
			$"product:{id}",
			async ct => await _repository.GetAsync(id, ct));
	}
	catch (RedisConnectionException ex)
	{
		_logger.LogError(ex, "Redis unavailable, falling back to database");
		return await _repository.GetAsync(id);
	}
}

🎯 Sample Application

The included AzureRedisCache sample project demonstrates:

• Side-by-side comparison of IDistributedCache and HybridCache
• Modern Bootstrap 5 UI with cache hit/miss visualization
• Code examples and feature comparison table
• Clear cache functionality for testing

Run the sample:

cd AzureRedisCache
dotnet run

📚 API Reference

HybridCache Methods

Task<T> GetOrCreateAsync<T>(
	string key, 
	Func<CancellationToken, Task<T>> factory, 
	HybridCacheEntryOptions? options = null, 
	CancellationToken token = default);

Task RemoveAsync(string key, CancellationToken token = default);

Task RemoveByTagAsync(string tag, CancellationToken token = default);

IDistributedCache Methods

Task<byte[]?> GetAsync(string key, CancellationToken token = default);
Task<string?> GetStringAsync(string key, CancellationToken token = default);
Task SetAsync(string key, byte[] value, DistributedCacheEntryOptions options, CancellationToken token = default);
Task SetStringAsync(string key, string value, DistributedCacheEntryOptions options, CancellationToken token = default);
Task RemoveAsync(string key, CancellationToken token = default);
Task RefreshAsync(string key, CancellationToken token = default);

🧪 Running Tests

dotnet test

Tests use real Redis integration (no mocks) for accurate behavior verification.

🔧 Troubleshooting

📄 License

MIT License - see LICENSE.md

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

See CONTRIBUTING.md for coding standards.