pvNugsCacheNc9Local 9.0.0

🗄️ pvNugs Cache Nc9 Local

📋 Overview

pvNugsCacheNc9Local is a high-performance, thread-safe in-memory caching solution for .NET 9 applications. Built on top of Microsoft.Extensions.Caching.Memory, it provides a simple yet powerful abstraction for storing and retrieving cached data with configurable time-to-live (TTL) settings and comprehensive logging support.

✨ Key Features

• ✅ In-Memory Caching - Fast, efficient local caching using IMemoryCache
• ⏱️ Configurable TTL - Set default or per-item time-to-live durations
• 🔒 Thread-Safe - Concurrent access support out of the box
• 📊 Integrated Logging - Built-in trace logging for cache hits and misses
• 🎯 Type-Safe - Generic methods for strongly-typed cache operations
• ⚡ Async/Await - Full async support with cancellation tokens
• 🔧 Easy Integration - Simple dependency injection setup
• 🌐 Configuration-Based - Configure via appsettings.json

📦 Installation

dotnet add package pvNugsCacheNc9Local

🚀 Quick Start

1️⃣ Configure in appsettings.json

{
  "PvNugsCacheConfig": {
    "DefaultTimeToLive": "00:10:00"
  }
}

2️⃣ Register Services

using pvNugsCacheNc9Local;

var builder = WebApplication.CreateBuilder(args);

// Register the cache service
builder.Services.TryAddPvNugsCacheNc9Local(builder.Configuration);

var app = builder.Build();

3️⃣ Use the Cache

using pvNugsCacheNc9Abstractions;

public class MyService
{
    private readonly IPvNugsCache _cache;

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

    public async Task<User> GetUserAsync(string userId)
    {
        var cacheKey = $"user:{userId}";
        
        // Try to get from cache
        var cachedUser = await _cache.GetAsync<User>(cacheKey);
        if (cachedUser != null)
            return cachedUser;
        
        // Load from database
        var user = await LoadUserFromDatabaseAsync(userId);
        
        // Store in cache with 5-minute TTL
        await _cache.SetAsync(cacheKey, user, TimeSpan.FromMinutes(5));
        
        return user;
    }

    public async Task UpdateUserAsync(User user)
    {
        await SaveUserToDatabaseAsync(user);
        
        // Invalidate cache
        await _cache.RemoveAsync($"user:{user.Id}");
    }
}

🎯 API Reference

IPvNugsCache Interface

SetAsync

Task SetAsync<TValue>(
    string key, 
    TValue value,
    TimeSpan? timeToLive = null,
    CancellationToken cancellationToken = default)

Stores a value in the cache with an optional time-to-live.

Parameters:

• key - Unique cache key (required)
• value - Value to cache
• timeToLive - Optional TTL (uses default if not specified)
• cancellationToken - Cancellation token

GetAsync

Task<TValue?> GetAsync<TValue>(
    string key,
    CancellationToken cancellationToken = default)

Retrieves a value from the cache.

Parameters:

• key - Cache key to retrieve
• cancellationToken - Cancellation token

Returns: The cached value or default(TValue) if not found

RemoveAsync

Task RemoveAsync(
    string key, 
    CancellationToken cancellationToken = default)

Removes a cached item.

Parameters:

• key - Cache key to remove
• cancellationToken - Cancellation token

⚙️ Configuration

PvNugsCacheConfig

Configuration Example

{
  "PvNugsCacheConfig": {
    "DefaultTimeToLive": "01:00:00"  // 1 hour default TTL
  }
}

🔍 Logging

The cache service integrates with the pvNugs logging framework to provide trace-level logging:

• Cache Hit - Logged when an item is found in cache
• Cache Miss - Logged when an item is not found
• Cache Set - Logged when an item is stored

Example log output:

[Trace] Cache hit for key: user:12345
[Trace] Cache miss for key: product:67890
[Trace] Cache set for key: order:54321 with TTL: 00:05:00

💡 Best Practices

✅ Do's

• Use meaningful cache keys - Include entity type and ID (e.g., user:123, order:456)
• Set appropriate TTLs - Consider data volatility and freshness requirements
• Invalidate on updates - Remove cached items when underlying data changes
• Handle null returns - Always check for null when retrieving cached values
• Use generic types - Leverage type safety with GetAsync<T>

❌ Don'ts

• Don't cache sensitive data - Avoid storing passwords or tokens
• Don't use overly long TTLs - Balance performance with data freshness
• Don't ignore cancellation tokens - Support cooperative cancellation
• Don't cache large objects - Be mindful of memory consumption

🔗 Dependencies

• Microsoft.Extensions.Caching.Memory (9.0.8) - Core caching functionality
• Microsoft.Extensions.Options.ConfigurationExtensions (9.0.8) - Configuration binding
• pvNugsCacheNc9Abstractions - Cache interface definitions
• pvNugsLoggerNc9Abstractions - Logging abstractions

📚 Related Packages

• pvNugsCacheNc9Abstractions - Cache interface definitions
• pvNugsLoggerNc9Console - Console logger implementation
• pvNugsLoggerNc9MsSql - SQL Server logger implementation

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

Pierre Van Wallendael - pvWay Ltd

📞 Support

For issues, questions, or suggestions:

• 🐛 GitHub Issues
• 📧 Contact: pvWay Ltd

⭐ If you find this package useful, please consider giving it a star on GitHub!