NCache as Dapper Cache Provider

The NCache Dapper integration uses NCacheCacheProvider to store cached query results in NCache.NCacheCacheProvider does not configure the NCache connection itself. The application creates and connects an Alachisoft.NCache.Client.ICache instance through the NCache SDK and passes that instance to NCacheCacheProvider. This allows NCache connection settings such as cache name, server list, ports, TLS, retries, timeouts, and other client configuration to remain part of the NCache SDK configuration.

Note

For general Dapper concepts and APIs, refer to the Dapper documentation.

Prerequisites

Before using Dapper with NCache, ensure that the following prerequisites are fulfilled:

  • Install the following NuGet package in your application:
    • OpenSource: NCache.OSS.Dapper
  • Include the following namespaces:
    • NCache.OSS.Dapper
    • Alachisoft.NCache.Client
  • The NCache cache must already exist and must be running.
  • Configure the NCache connection through the NCache SDK before creating NCacheCacheProvider.
  • Make sure query result objects being stored in NCache are serializable.

Configure NCache with Dapper

Create an NCache ICache through the NCache SDK and pass it to NCacheCacheProvider. Add the following code to your Program.cs file:

var cache = CacheManager.GetCache(
    "demoCache",
    new CacheConnectionOptions
    {
        ServerList = new List<ServerInfo>
        {
            new ServerInfo("127.0.0.1", 9800)
        }
    });

DapperNCache.CacheProvider =
    new NCacheCacheProvider(cache);

In this configuration:

  • CacheManager.GetCache(...) connects the application to NCache.
  • CacheConnectionOptions specifies NCache client connection settings.
  • ServerList specifies the NCache server endpoint.
  • NCacheCacheProvider wraps the connected NCache ICache.
  • DapperNCache.CacheProvider registers it as the default provider used by QueryCached<T>.

Configure Default Expiration

Use DapperNCache.DefaultExpiration to define a default expiration for cached query results:

DapperNCache.DefaultExpiration =
    TimeSpan.FromMinutes(30);

Specify whether the default expiration is sliding:

DapperNCache.DefaultIsSliding = false;

When DefaultIsSliding is:

  • false: absolute expiration is used.
  • true: sliding expiration is used.

A per-query CacheOptions.Expiration overrides the global default.

Note

If neither CacheOptions.Expiration nor DapperNCache.DefaultExpiration is specified, the cached result is stored without expiration.

Complete Configuration Example

The following example connects to NCache, registers the cache provider, configures default expiration, and executes a cached query:

var cache = CacheManager.GetCache(
    "demoCache",
    new CacheConnectionOptions
    {
        ServerList = new List<ServerInfo>
        {
            new ServerInfo("127.0.0.1", 9800)
        }
    });

DapperNCache.CacheProvider =
    new NCacheCacheProvider(cache);

DapperNCache.DefaultExpiration =
    TimeSpan.FromMinutes(30);

DapperNCache.DefaultIsSliding = false;

using var connection =
    new SqlConnection(connectionString);

var users = connection.QueryCached<User>(
    "SELECT * FROM Users WHERE IsActive = @IsActive",
    new { IsActive = true },
    new CacheOptions
    {
        Expiration = TimeSpan.FromMinutes(5)
    });

NCacheCacheProvider Constructor

NCacheCacheProvider accepts an already-initialized NCache ICache: 

NCacheCacheProvider(ICache cache)
Parameter Description
cache* Specifies an initialized and connected NCache ICache, typically obtained through CacheManager.GetCache(...).

CacheOptions Properties

CacheOptions controls NCache caching behavior for an individual QueryCached<T> call.

Property Description
Expiration Specifies the expiration duration for the cached query result. It overrides DapperNCache.DefaultExpiration when set.
IsSliding Specifies whether the configured expiration is sliding. The default is false.
ForceUpdate Removes the existing cached result, executes the query against the database, and refreshes NCache. The default is false.
ErrorEnabled Specifies whether cache operation failures are propagated to the application. The default is false, which causes cache operation failures to be swallowed.

When ErrorEnabled is false, a failed cache read is treated as a cache miss, a failed cache write does not prevent the database result from being returned, and a failed cache removal does not prevent ForceUpdate from executing the database query. Set ErrorEnabled to true to rethrow cache-operation exceptions.

Maintain Cache Freshness

NCacheCacheProvider stores and retrieves cached query results but does not monitor changes made to the underlying database. Operations such as INSERT, UPDATE, and DELETE, whether performed through Dapper or by another application, do not automatically invalidate related entries in NCache.

Applications are responsible for keeping cached query results synchronized with database changes. Depending on the application requirements, cached results can be refreshed through:

  • Cache expiration.
  • Explicit removal of affected cache entries.
  • CacheOptions.ForceUpdate when executing the query again.
Important

A database change can affect more than one cached query result. For example, updating one record may make cached results for a full-table query, a filtered query, and other queries containing that record stale. Each affected cache entry must be considered when applying explicit invalidation.

See Also

Dapper with NCache
Dapper API Usage with NCache