CacheManager Documentation

When using multiple cache handles (layers), CacheManager ensures data consistency:

• Put and Add operations: These are automatically executed on all registered cache handles in the manager.
• Get operations: Behavior is controlled by CacheUpdateMode:
  • None: No update occurs across handles on a hit.
  • Up: Updates the handles "above" the current one in the hierarchy.
  • All: Updates/Adds the item to all handles in the manager.
• Synchronization: For distributed environments, CacheManager can use Redis pub/sub to synchronize cache clients.

CacheManager provides a unified abstraction layer for .NET caching. Key concepts include:

• ICache<T>: The primary strongly-typed interface used to interact with the cache.
• Layered Caching: You can implement multiple layers (e.g., an in-process memory cache in front of a distributed Redis cache). CacheManager manages synchronization between these layers.
• Serialization: Required for distributed caches. If no specific serialization package is configured, it defaults to Binary serialization (if the full CLR is available).
• Cache Regions: A mechanism to group cache elements, allowing for bulk operations like removing all elements in a specific region.

CacheManager is distributed via NuGet packages. To use the core functionality, install CacheManager.Core. Depending on your requirements, you will also need provider-specific packages (like Redis or MemoryCache) and serialization packages for distributed caching.

Supported frameworks include .NET Standard 2.0, .NET 8.0, and .NET Framework 4.7.2.

To define your cache settings in a JSON file, use the cachemanager.json schema. This allows you to leverage IntelliSense and validation in your IDE. The configuration root should contain a cacheManagers array, where each entry defines a cache manager's name and the providers it handles (using knownType).

{
  "$schema": "http://cachemanager.michaco.net/schemas/cachemanager.json",
  "cacheManagers": [
    {
        "name": "MyCache",
        "handles": [ { "knownType": "SystemRuntime" } ]
    }
  ]
}

You can use the CacheFactory.Build overload that accepts a name and an Action<ConfigurationBuilderCachePart> to configure and instantiate a new CacheManager. This allows for a fluent configuration of cache settings, such as update modes, dictionary handling, performance counters, and expiration policies, within a single lambda expression.

var cache = cachefactory.build("mycachename", settings =>
{
   settings
       .withupdatemode(cacheupdatemode.up)
       .withdictionaryhandle()
           .enableperformancecounters()
           .withexpiration(expirationmode.sliding, timespan.fromseconds(10));
});

cache.add("key", "value");

By default, CacheManager uses a Binary serializer. You can switch to JSON serialization by calling .WithJsonSerializer() on the Core.ConfigurationBuilder.

This allows you to use JSON for (de)serialization of cached items. You can optionally provide specific Newtonsoft.Json.JsonSerializerSettings for both serialization and deserialization to customize how objects are handled.

var builder = new Core.ConfigurationBuilder();

// Basic usage: replaces default Binary serializer with JSON
builder.WithJsonSerializer();

// Advanced usage: specify custom Newtonsoft.Json settings for serialization and deserialization
builder.WithJsonSerializer(new JsonSerializerSettings(), new JsonSerializerSettings());

You can integrate CacheManager configuration with the standard .NET Microsoft.Extensions.Configuration ecosystem. To use configuration providers like JSON or XML, ensure you have installed the corresponding Microsoft.Extensions.Configuration.* NuGet packages.

Use the GetCacheConfiguration() extension method on an IConfiguration object to retrieve the CacheManager-specific configuration settings.

// setting up the configuration providers
var builder = new Microsoft.Extensions.Configuration.ConfigurationBuilder()
    .AddJsonFile("cache.json");

// build the configuration
this.Configuration = builder.Build();

// retrieve the CacheManager configuration
var jsonConfiguration = 
    this.Configuration.GetCacheConfiguration();

For distributed caching, you can opt-in to various serialization formats by installing the corresponding package. Supported options include:

• Binary: Built-in (requires full CLR).
• Json: Uses Newtonsoft.Json.
• Json with Gzip: JSON serialization with compression.
• Bond: Based on Microsoft.Bond.
• DataContract: Based on System.Runtime.Serialization (supports Binary, Json, and Json with Gzip).
• Protocol Buffer: Uses Google's protobuf via the protobuf-net implementation.