NCache.Dapper 5.3.800

NCache Dapper Integration

NCache integration for Dapper. This package adds cache-aside query caching to Dapper's IDbConnection extension methods, using NCache as the distributed cache backing store.

Installation

Install-Package NCache.Dapper

or, using the .NET CLI:

dotnet add package NCache.Dapper

Prerequisites

• .NET Framework 4.6.2 or .NET 8.0 compatible application.
• An NCache 5.3.800 (or later) server should be up and running, with the target cache already created/registered on it.

Getting Started

Setting up NCache

Declare the cache server(s) within your configuration file:

appsettings.json

{
  "NCache": {
    "CacheName": "defaultCache",
    "ServerList": [
      { "Ip": "10.0.0.1", "Port": 9800 },
      { "Ip": "10.0.0.2" }
    ]
  }
}

app.config / web.config

<configuration>
  <configSections>
    <section name="ncache" type="Alachisoft.NCache.Client.NCacheSection, Alachisoft.NCache.Client" />
  </configSections>
  <ncache>
    <caches>
      <add name="defaultCache" server="10.0.0.1" port="9800" />
    </caches>
  </ncache>
</configuration>

Change defaultCache → YourCacheName, and 10.0.0.1 → the IP/hostname of a node hosting YourCacheName.

Setting up Package

QueryCached and QueryCachedAsync do not take a connection configuration instance directly as a parameter. Instead, they resolves their cache provider from a single, static registry (DapperNCache.CacheProvider). Build and connect an NCache ICache yourself using the NCache SDK, then register it once at application startup:

DapperNCache.CacheProvider = new NCacheCacheProvider(cache);

// Optional: applied to every cached item that doesn't specify its own CacheOptions.Expiration
DapperNCache.DefaultExpiration = TimeSpan.FromMinutes(30);
DapperNCache.DefaultIsSliding = false;

// Optional: observe cache failures that are swallowed (ErrorEnabled = false)
DapperNCache.OnCacheError = (ex, context) => logger.LogWarning(ex, context);

Because NCacheCacheProvider takes an already-configured ICache, you're free to build that instance however you need — CacheManager.GetCache with ConnectionOptions, TLS settings, custom retry/timeout policies, etc.

With the provider registered, call QueryCached or QueryCachedAsync directly on any IDbConnection, the same way you'd call Dapper's own Query:

using var connection = new SqlConnection(connectionString);

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

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

A per-query CacheOptions.Expiration always overrides DapperNCache.DefaultExpiration; if neither is set, cached items never expire.

A custom provider can also be supplied per call instead of the globally registered one:

var usersSync = connection.QueryCached<User>(sql, param, options, cacheProvider: myCustomProvider);

var usersAsync = await connection.QueryCachedAsync<User>(sql, param, options, cacheProvider: myCustomProvider);

Configuration

Configure the connection to NCache by building your own ICache instance via the NCache SDK (e.g. CacheManager.GetCache) and passing it into NCacheCacheProvider. The cache must already exist on the server.

Configure per-query caching behavior through a CacheOptions instance.

The integration provides:

• QueryCached<T> — IDbConnection extension methods that wrap a Dapper query with cache-aside behavior backed by NCache.
• QueryCachedAsync<T> — IDbConnection extension methods that wrap a Dapper query with cache-aside behavior backed by NCache asynchronously.
• INCacheCacheProvider — The provider abstraction (Get/Set/Remove) used by the extension methods; implement this to plug in a custom cache backend.
• NCacheCacheProvider — The default INCacheCacheProvider implementation, constructed from an already-configured NCache ICache instance.
• DapperNCache — Static registry holding the globally configured CacheProvider, DefaultExpiration, DefaultIsSliding, and the OnCacheError hook.

When a cached entry is missing or expired, the query is executed against the database and the result is written back to the cache under a key derived from the database name, SQL text, parameters, and result type, so identical queries share a cache entry and differently-shaped results never collide.

Resources

• NCache Integration Docs
• Dapper
• Programmer's Guide

Technical Support

Alachisoft provides various technical support resources.

Visit the Alachisoft Support Center to select a support resource appropriate for your issue.

To request additional features or report a documentation discrepancy, contact support@alachisoft.com.

License

Copyright © 2026 Alachisoft. All rights reserved.