Second-level caching is a query cache. The results of Entity Framework (EF) commands are stored in the cache so that the same EF commands will retrieve their data from the cache rather than executing them against the database again.
How to Use
Using the second-level cache involves three mandatory steps: installing a provider, registering it, and adding the interceptor to your DbContext.
EasyCaching.Core: A provider for the EasyCaching.Core library.
dotnet add package EFCoreSecondLevelCacheInterceptor.EasyCaching.Core
CacheManager.Core: A provider for the CacheManager.Core library.
dotnet add package EFCoreSecondLevelCacheInterceptor.CacheManager.Core
Custom: You can also implement your own provider.
2. Register the Cache Provider and Interceptor
In your Startup.cs or Program.cs, you need to register the EF Core second-level cache services and configure your chosen provider.
Example: Using the Built-in In-Memory Provider
public void ConfigureServices(IServiceCollection services)
{
// 1. Add EF Core Second Level Cache services
services.AddEFSecondLevelCache(options =>
options.UseMemoryCacheProvider().ConfigureLogging(true).UseCacheKeyPrefix("EF_")
// Fallback on db if the caching provider fails.
.UseDbCallsIfCachingProviderIsDown(TimeSpan.FromMinutes(1))
);
// 2. Add your DbContext
var connectionString = Configuration["ConnectionStrings:ApplicationDbContextConnection"];
services.AddConfiguredMsSqlDbContext(connectionString);
services.AddControllersWithViews();
}
(For detailed configuration examples of other providers, see the Available Cache Providers section below.)
3. Add the Interceptor to Your DbContext
Modify your DbContext registration to add the SecondLevelCacheInterceptor. This service is automatically registered and available via dependency injection.
public static class MsSqlServiceCollectionExtensions
{
public static IServiceCollection AddConfiguredMsSqlDbContext(this IServiceCollection services, string connectionString)
{
services.AddDbContextPool<ApplicationDbContext>((serviceProvider, optionsBuilder) =>
optionsBuilder
.UseSqlServer(
connectionString,
sqlServerOptionsBuilder =>
{
sqlServerOptionsBuilder
.CommandTimeout((int)TimeSpan.FromMinutes(3).TotalSeconds)
.EnableRetryOnFailure()
.MigrationsAssembly(typeof(MsSqlServiceCollectionExtensions).Assembly.FullName);
})
// Add the interceptor
.AddInterceptors(serviceProvider.GetRequiredService<SecondLevelCacheInterceptor>()));
return services;
}
}
4. Make Queries Cacheable
To cache a query, use the .Cacheable() extension method. It can be placed anywhere in the LINQ query chain.
var post = context.Posts
.Where(x => x.Id > 0)
.OrderBy(x => x.Id)
.Cacheable() // Mark this query to be cached
.FirstOrDefault(); // Async methods are also supported.
The Cacheable() method uses global settings by default, but you can override them for a specific query:
var post = context.Posts
.Where(x => x.Id > 0)
.OrderBy(x => x.Id)
// Override global settings for this query
.Cacheable(CacheExpirationMode.Sliding, TimeSpan.FromMinutes(5))
.FirstOrDefault();
How to Verify It's Working
To confirm that the interceptor is working, you should enable logging.
1. Enable Logging in the Configuration
Set ConfigureLogging(true) during service registration.
When you run a cacheable query for the first time, the data is fetched from the database and cached. On subsequent executions, you should see log messages indicating a cache hit:
Suppressed result with a TableRows[ee20d2d7-ffc7-4ff9-9484-e8d4eecde53e] from the cache[KeyHash: EB153BD4, CacheDependencies: Page.].
Using the TableRows[ee20d2d7-ffc7-4ff9-9484-e8d4eecde53e] from the cache.
Notes:
The Suppressed the result with the TableRows message confirms the caching interceptor is working.
You will still see an Executed DbCommand log message from EF Core, but this is expected behavior.
You can also use a database profiler to verify that the query is only executed against the database on the first run.
For more direct access to library events, you can pass an action to the ConfigureLogging method. See the Logging Events section for more details.
Caching Strategies
You can control caching globally or on a per-query basis.
Global Caching
Instead of marking individual queries with .Cacheable(), you can define a global caching policy.
Caching All Queries
To cache every query in the application, use CacheAllQueries().
You can also exclude specific types or table names from caching using CacheAllQueriesExceptContainingTypes or CacheAllQueriesExceptContainingTableNames.
Cache Invalidation
This library automatically invalidates cache entries when it detects CRUD operations (via its interceptor).
Automatic Invalidation
When you use SaveChanges() or SaveChangesAsync(), the interceptor identifies which tables have been modified and invalidates all cached queries that depend on those tables. No additional configuration is needed.
Limitation: ExecuteUpdate and ExecuteDelete
EF Core does not trigger interceptors for bulk operations like ExecuteUpdate and ExecuteDelete for performance reasons. These methods execute raw SQL directly, bypassing EF Core's change tracking and related events. Therefore, cache invalidation will not happen automatically for these operations. You must invalidate the cache manually.
Manual Invalidation
You can manually invalidate the cache by injecting the IEFCacheServiceProvider.
Invalidate the entire cache:
_cacheServiceProvider.ClearAllCachedEntries();
Invalidate cache entries related to specific tables:
This is useful if you are using an external tool like SqlTableDependency to monitor database changes.
// The prefix "EF_" should match your configured UseCacheKeyPrefix.
var tableNames = new HashSet<string> { "EF_TableName1", "EF_TableName2" };
_cacheServiceProvider.InvalidateCacheDependencies(new EFCacheKey(tableNames));
Invalidation Notifications
To receive notifications when cache entries are invalidated, use the NotifyCacheInvalidation method.
Skip by Result:services.AddEFSecondLevelCache(options =>
{
// Don't cache null values or empty result sets.
options.SkipCachingResults(result =>
result.Value == null || (result.Value is EFTableRows rows && rows.RowsCount == 0));
});
Skipping Invalidation
In some cases, you may want to prevent a command from invalidating the cache, such as when updating a view counter.
services.AddEFSecondLevelCache(options =>
{
options.SkipCacheInvalidationCommands(commandText =>
// Assumes a command that only updates a post's view count contains this text.
commandText.Contains("UPDATE [Posts] SET [Views]", StringComparison.InvariantCultureIgnoreCase));
});
Overriding Cache Policy
Use OverrideCachePolicy() to dynamically change the caching policy for a query at runtime.
services.AddEFSecondLevelCache(options =>
{
options.OverrideCachePolicy(context =>
{
// Don't cache any CRUD commands
if (context.IsCrudCommand)
{
return null;
}
// Use a "never remove" policy for queries on the 'posts' table
if (context.CommandTableNames.Contains("posts"))
{
return new EFCachePolicy().ExpirationMode(CacheExpirationMode.NeverRemove);
}
// Use the default calculated policy for all other queries
return null;
});
});
Logging Events
You can subscribe to caching events directly instead of parsing log files.
.ConfigureLogging(enable: environment.IsDevelopment(), cacheableEvent: args =>
{
switch (args.EventId)
{
case CacheableLogEventId.CacheHit:
break;
case CacheableLogEventId.QueryResultCached:
break;
case CacheableLogEventId.QueryResultInvalidated:
// Example of logging a specific event
args.ServiceProvider.GetRequiredService<ILoggerFactory>()
.CreateLogger(nameof(EFCoreSecondLevelCacheInterceptor))
.LogWarning("{EventId} -> {Message} -> {CommandText}",
args.EventId, args.Message, args.CommandText);
break;
// ... handle other events
}
})
Other Configurations
Custom Hash Provider: Replace the default xxHash algorithm by implementing IEFHashProvider and registering it with options.UseCustomHashProvider<T>().
Custom JsonSerializerOptions: Control serialization behavior by passing JsonSerializerOptions to options.UseJsonSerializerOptions(options).
Disable Interceptor: Temporarily disable the interceptor via options.EnableCachingInterceptor(false).
Skip DbContexts: Exclude certain DbContext types from caching with options.SkipCachingDbContexts().
Available Cache Providers
Below are setup examples for the various supported cache providers.
Dynamic Provider with EasyCaching.Core for Multi-tenancy:
You can dynamically select a cache provider based on the current context, such as a tenant ID from an HTTP request header.
services.AddEFSecondLevelCache(options =>
options.UseEasyCachingCoreProvider(
(serviceProvider, cacheKey) => "redis-db-" + serviceProvider.GetRequiredService<IHttpContextAccessor>().HttpContext.Request.Headers["tenant-id"],
isHybridCache: false)
);
5. Using CacheManager.Core
This allows you to use CacheManager.Core as a cache manager. Note: This library is not actively maintained.
In-Memory with CacheManager.Core:
First, install: CacheManager.Core, CacheManager.Microsoft.Extensions.Caching.Memory, and CacheManager.Serialization.Json.
services.AddEFSecondLevelCache(options => options.UseCacheManagerCoreProvider());
// Add CacheManager.Core services
services.AddSingleton(typeof(ICacheManager<>), typeof(BaseCacheManager<>));
services.AddSingleton(typeof(ICacheManagerConfiguration),
new CacheManager.Core.CacheConfigurationBuilder()
.WithJsonSerializer()
.WithMicrosoftMemoryCacheHandle("MemoryCache1")
.Build());
If the provided cache providers don't meet your needs, you can implement the IEFCacheServiceProvider interface and then register it using the options.UseCustomCacheProvider<T>() method.
Guidance and Best Practices
When to Use
Good candidates for query caching are global site settings and public data, such as infrequently changing articles or comments. It can also be beneficial to cache data specific to a user, so long as the cache expires frequently enough relative to the size of the user base that memory consumption remains acceptable. Small, per-user data that changes frequently is better held in other stores like user claims, which are stored in cookies, than in this cache.
Scope
This cache is scoped to the application, not the current user. It does not use session variables. Accordingly, when retrieving cached per-user data, be sure your queries include a filter for the user ID, such as .Where(x => x.UserId == id).
Invalidation
The cache is updated when an entity is changed (inserted, updated, or deleted) via a DbContext that uses this interceptor. If the database is modified through other means, such as a stored procedure, a trigger, or another application, the cache will become stale.
Transactions
To avoid complications, all queries inside an explicit transaction (context.Database.BeginTransaction()) will not be cached by default. However, cache invalidation for CRUD operations within the transaction will still occur. You can override this behavior and allow caching within explicit transactions by using the .AllowCachingWithExplicitTransactions(true) setting.
Database Provider Compatibility
Some database providers do not natively support special data types such as DateTimeOffset or TimeSpan. For these scenarios, you will need to configure the appropriate value converters in your DbContext.
How to Upgrade to Version 5
To support more advanced caching providers, this library was split into multiple assemblies and NuGet packages in version 5.
Remove the old dependency: EFCoreSecondLevelCacheInterceptor.
Add the new main package:
dotnet add package EFCoreSecondLevelCacheInterceptor
Add a provider package: The main package no longer includes a built-in provider. You must install one of the new provider packages.
For the previous built-in In-Memory cache, install:
dotnet add package EFCoreSecondLevelCacheInterceptor.MemoryCache
For the previous EasyCaching.Core provider, install:
dotnet add package EFCoreSecondLevelCacheInterceptor.EasyCaching.Core
For the previous CacheManager.Core provider, install:
dotnet add package EFCoreSecondLevelCacheInterceptor.CacheManager.Core
If you were using a custom cache provider via options.UseCustomCacheProvider<T>(), you do not need to install a new provider package.
