Dapper with NCache

Dapper is a .NET object mapper that provides extension methods for executing database operations through IDbConnection. NCache integrates with Dapper through the NCache.OSS.Dapper package to provide distributed cache-aside query caching. The integration provides the QueryCached<T> extension method, which checks NCache before executing a database query. If the requested result is available in the cache, it is returned directly. Otherwise, the query is executed against the database, and the result is stored in NCache for subsequent requests.

The integration uses NCacheCacheProvider as the NCache-backed implementation of INCacheCacheProvider. Applications create an NCache ICache instance through the NCache SDK and provide it to NCacheCacheProvider.

Note

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

Key Features

The key features of the NCache integration with Dapper are:

  • Cache-Aside Query Caching: QueryCached<T> checks NCache for the requested query result before executing the database query. On a cache miss, the result is retrieved from the database and stored in NCache.
  • Distributed Query Cache: Query results are stored in the configured NCache cache and can be shared across application instances.
  • Automatic Cache Key Generation: Unless customCacheKey is provided, QueryCached<T> automatically generates the cache key internally using the database name, SQL query, query parameters, and result type.
  • Custom Cache Keys: Applications can provide customCacheKey when they need to explicitly control the cache key.
  • Absolute and Sliding Expiration: Cached query results can use absolute or sliding expiration.
  • Global and Per-Query Expiration: Applications can configure global expiration defaults or override them for individual queries.
  • Forced Cache Refresh: ForceUpdate allows an application to bypass an existing cached result, execute the query again, and refresh the cache.
  • Per-Key Concurrency Protection: Concurrent requests for the same cache key use double-checked locking to reduce duplicate database queries within the same application process.
  • Application-Managed Cache Freshness: Database writes do not automatically invalidate cached query results. Applications must use expiration, explicit cache removal, or ForceUpdate to refresh affected entries.

How Dapper Works with NCache

The NCache Dapper integration uses a single cache-aside layer between the application and the database. When the application calls QueryCached<T>, the method first uses the configured cache provider to check NCache for the query result. If the result is available in NCache, it is returned directly to the application without executing the database query.

If the result is not available in NCache, QueryCached<T> executes the query against the database, stores the returned result in NCache, and then returns it to the application. Subsequent calls for the same cache key can therefore retrieve the cached result from NCache instead of querying the database again.

For each call, QueryCached<T> resolves a single INCacheCacheProvider. The provider can be:

  • The cacheProvider supplied directly to QueryCached<T>, or
  • The provider registered in DapperNCache.CacheProvider.

If no provider is available, QueryCached<T> throws InvalidOperationException.

Important

NCache.OSS.Dapper does not automatically invalidate cached query results when the underlying database data is modified. Database writes performed through Dapper or by other applications do not automatically update or remove related cached results. Applications are responsible for maintaining cache freshness through expiration, explicit cache removal, or ForceUpdate.

A single database change can affect multiple cached query results because different queries, parameters, result types, or custom cache keys can produce separate cache entries.

Query Execution

When the application calls QueryCached<T>, the integration first resolves the cache provider and determines the cache key. If a customCacheKey is provided, that key is used; otherwise, QueryCached<T> automatically generates one by calling CacheKeyGenerator.GenerateCacheKey(cnn.Database, sql, param, typeof(T)). NCache is then checked for an existing result associated with that key. If the result is found, it is returned directly from NCache. If the result is not available in the cache, the query is executed against the database, the returned result is stored in NCache, and the result is then returned to the application.

Concurrent Query Handling

When multiple requests for the same cache key arrive concurrently, QueryCached<T> uses a per-key SemaphoreSlim. After the first cache miss:

  • A per-key lock is acquired.
  • NCache is checked again.
  • If another request populated the cache while the current request was waiting, the cached value is returned.
  • Otherwise, the database query is executed and its result is stored in NCache.

This reduces duplicate database queries caused by concurrent requests for the same cache key.

Note

The per-key lock is local to the application process. It does not provide distributed locking between separate application instances.

Force Cache Refresh

Use CacheOptions.ForceUpdate when a query should execute against the database even if a cached result already exists. When ForceUpdate is true:

  • The existing cache entry is removed.
  • The normal cache lookup is bypassed.
  • The query is executed against the database.
  • The new result is stored in NCache.

Cache Failure Handling

By default, QueryCached<T> fails open when an NCache cache operation fails. When CacheOptions.ErrorEnabled is false, which is the default:

  • If a cache Get operation fails, the failure is treated as a cache miss and the query is executed against the database.
  • If a cache Set operation fails, the database result is still returned, but the result is not cached.
  • If a cache Remove operation fails during ForceUpdate, the database query is still executed.

Set CacheOptions.ErrorEnabled to true to propagate cache-operation exceptions to the application.

Note

ErrorEnabled applies to cache-operation failures and does not control exceptions raised while executing the database query.

In This Section

NCache as Dapper Cache Provider
Learn how to create an NCache ICache, configure NCacheCacheProvider, and register it for cached Dapper queries.

Dapper API Usage with NCache
Learn how to use QueryCached<T> with NCache, including expiration, forced refresh, custom cache keys, and per-query cache providers.