NCache.Caching.Hybrid 5.3.800

NCache.Caching.Hybrid

NCache implementation of ASP.NET Core HybridCache. NCacheHybridCache implements Microsoft.Extensions.Caching.Hybrid.HybridCache on top of an NCache client cache: a local in-process cache (L1) that NCache keeps synchronized with a clustered cache (L2).

Features

• Drop-in HybridCache: register once, inject HybridCache anywhere.
• L1/L2 caching through an NCache client cache: reads are served from L1 when possible; synchronization with the cluster is handled by NCache.
• Tag-based removal: attach tags on write, remove by one tag or by any of several tags.
• Bulk removal: remove many keys in one call.
• Cache stampede protection: a per-key lock ensures concurrent misses run the factory once.
• Expiration: a default absolute expiration in configuration, overridable per entry.
• Logging: uses ILogger<NCacheHybridCache> from the standard .NET logging pipeline.

Prerequisites

1. A running NCache server or cluster with a clustered cache.
2. A client cache enabled for that cache, on every machine that runs your application. This is mandatory. If it is disabled, the constructor throws InvalidOperationException ("Client cache is not configured").
3. Connection settings for the cache in the ncache section of appsettings.json, keyed by the cache name.
4. .NET 8 or later.

See the NCache documentation for how to create and enable a client cache for your cluster.

Installation

dotnet add package NCache.Caching.Hybrid

Install-Package NCache.Caching.Hybrid

Quick Start

1. Configure appsettings.json

{
  "ncache": {
    "defaultCache": {
      "server": "192.168.1.100,192.168.1.101",
      "port": 9800
    }
  },
  "NCacheHybridCache": {
    "CacheName": "defaultCache",
    "Expiration": "00:05:00"
  }
}

• ncache: specific to NCache, it supplies the server address(es) and port (default 9800) for each cache name.
• NCacheHybridCache: read by this library (see Configuration options).

2. Register services in Program.cs

var builder = WebApplication.CreateBuilder(args);

// From a configuration section (recommended)
builder.Services.AddNCacheHybridCache(
    builder.Configuration.GetSection("NCacheHybridCache"));

// Or from the root configuration (uses the "NCacheHybridCache" section if present)
// builder.Services.AddNCacheHybridCache(builder.Configuration);

// Or from code
// builder.Services.AddNCacheHybridCache(options =>
// {
//     options.CacheName = "defaultCache";
//     options.Expiration = TimeSpan.FromMinutes(5);
// });

3. Inject and use HybridCache

public class ProductService
{
    private readonly HybridCache _cache;
    private readonly IProductRepository _database;

    public ProductService(HybridCache cache, IProductRepository database)
    {
        _cache = cache;
        _database = database;
    }

    public async Task<Product> GetProductAsync(int productId, int categoryId)
    {
        return await _cache.GetOrCreateAsync(
            key: $"product:{productId}",
            state: productId,
            factory: async (id, ct) => await _database.GetProductAsync(id, ct),
            tags: new[] { "products", $"category:{categoryId}" });
    }
}

Configuration options

NCacheHybridCache section (NCacheHybridCacheOptions)

Expiration uses the .NET TimeSpan string format, for example "00:04:00" for four minutes.

Per-call HybridCacheEntryOptions

HybridCacheEntryFlags

L1 and L2 share a single NCache handle, so the "local" and "distributed" flags cannot be applied separately:

Operations

Bulk removal

await _cache.RemoveAsync(products.Select(p => $"product:{p.Id}"));
await _cache.RemoveByTagAsync(new[] { "category:1", "category:2", "category:3" });

Behavior and limitations

• Stampede protection is per process. Multiple application instances can each run the factory once for the same key at the same time.
• Synchronization is NCache's responsibility. The HybridCache library does not provide L1 - L2 synchronization, that is done natively by NCache
• Operations run on the thread pool. The NCache calls are synchronous
• Disposal disposes the underlying NCache cache handle.

Troubleshooting

Diagnostic logging

The library logs through ILogger<NCacheHybridCache> (category NCache.Caching.Hybrid.NCacheHybridCache). Hits, misses, factory calls and removals are logged at Information; lock and insert details at Debug.

{
  "Logging": {
    "LogLevel": {
      "NCache.Caching.Hybrid": "Debug"
    }
  }
}

Use Warning or higher in production, since every call is logged at Information.

License

Copyright © 2005-2026 Alachisoft. All rights reserved.

Resources

• NCache Documentation
• Microsoft HybridCache Documentation
• Alachisoft Website