How to use HybridCache in ASP.NET Core

Caching is a proven strategy for improving application scalability and performance. We’ve seen support for caching included in legacy ASP.NET and subsequently in ASP.NET Core frameworks. In ASP.NET Core, caching is primarily of two types: in-memory caching and distributed caching.

With .NET 9, currently available in preview, we now have three caching options in ASP.NET Core. HybridCache is a new library that addresses the shortcomings of in-memory caching and distributed caching. This article discusses HybridCache, its importance, and how we can work with it in ASP.NET Core applications.

Introducing HybridCache

The built-in caching mechanisms of ASP.NET Core can cause race conditions that could eventually result in a cache stampede. A cache stampede occurs when concurrent requests are made to the same piece of data residing in the cache, thereby overloading the application and rendering caching useless.

HybridCache is a new library built on top of the existing Microsoft.Extensions.Caching.Distributed.IDistributedCache library. HybridCache improves upon the existing caching mechanisms of ASP.NET Core and provides several additional features and useful capabilities:

• Stampede protection
• Support for multi-tier caching
• Support for configurable serialization
• Support for tag-based eviction

HybridCache takes advantage of two levels of cache storage, i.e., L1 cache (in-process) and L2 cache (out-of-process). While L1 is an in-memory cache that is fast and stores data in the primary memory of your computer, L2 is comparatively slower but can store larger volumes of data that is often spread across multiple servers.

HybridCache addresses the limitations of IDistributedCache and IMemoryCache by combining their best features and capabilities. Stampede protection is a feature that saves resources by not allowing more than one request to get the same information concurrently, thereby reducing the load on the application. HybridCache also supports many serialization options, allowing you to configure how you want your data to be saved or retrieved thereby adding flexibility.

The key benefits of HybridCache are greater simplicity, improved performance, and enhanced efficiency.

HybridCache is an abstract class pertaining to the Microsoft.Extensions.Caching.Hybrid namespace. To store data to the cache and retrieve data from the cache, you use the GetOrCreateAsync method of the HybridCache class. This method takes advantage of the cache key to retrieve an object from the primary cache.

Now, if the object requested by the application is not available in the cache, i.e., in the case of a cache miss, the method checks the secondary cache if it is configured. If the data is not available there, the method stores the object in both the primary and secondary caches.

Create an ASP.NET Core Web API project in Visual Studio 2022

To create an ASP.NET Core Web API project in Visual Studio 2022, follow the steps outlined below.

1. Launch the Visual Studio 2022 IDE.
2. Click on “Create new project.”
3. In the “Create new project” window, select “ASP.NET Core Web API” from the list of templates displayed.
4. Click Next.
5. In the “Configure your new project” window, specify the name and location for the new project. Optionally check the “Place solution and project in the same directory” check box, depending on your preferences.
6. Click Next.
7. In the “Additional Information” window shown next, select “.NET 8.0 (Long Term Support)” as the framework version and check the check box that says “Use controllers,” as we’ll be using controllers instead of minimal APIs in this project.
8. Elsewhere in the “Additional Information” window, leave the “Authentication Type” set to “None” (the default) and make sure the check boxes “Enable OpenAPI Support,” “Configure for HTTPS,” and “Enable Docker” remain unchecked. We won’t be using any of those features here.
9. Click Create.

We’ll use this ASP.NET Core Web API minimal API project to work with the HybridCache code examples given in the sections below.

Install the HybridCache NuGet package

To work with HybridCache library, we’ll need to install the HybridCache NuGet package in the project. To do this, select the project in the Solution Explorer window, then right-click and select “Manage NuGet Packages.”

In the NuGet Package Manager window, search for the Microsoft.Extensions.Caching.Hybrid package and install it. Remember to check the “Include prerelease” check box.

Alternatively, you can install the package via the NuGet Package Manager console by running the command below.

dotnet add package Microsoft.Extensions.Caching.Hybrid –prerelease

Registering and configuring HybridCache in ASP.NET Core

Once you have installed HybridCache into your project, you should register it as a service with the dependency injection container by including the following code in the Program.cs file.

using HybridCacheDemo;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container
builder.Services.AddAuthorization();
builder.Services.AddHybridCache();

You can configure the AddHybridCache method as shown in the code snippet given below.

builder.Services.AddHybridCache(options =>
    {
        options.MaximumPayloadBytes = 1024 * 1024;
        options.MaximumKeyLength = 1024;
        options.DefaultEntryOptions = new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromMinutes(3),
            LocalCacheExpiration = TimeSpan.FromMinutes(3)
        };
    });

Next, we’ll create a custom service class that leverages HybridCache.

Create the CustomHybridCache service in ASP.NET Core

Create an interface named ICustomHybridCacheService in a file having the same name with a .cs extension. Now replace the generated code with the following code snippet.

public interface ICustomHybridCacheService
{
    public Task<string> GetCachedDataAsync(string key, CancellationToken token = default);
}

Create a new class called CustomHybridCacheService that implements the ICustomHybridCacheService interface as shown in the code listing below.

public class CustomHybridCacheService: ICustomHybridCacheService
{
    private HybridCache _cache;
    public CustomHybridCacheService(HybridCache cache)
    {
        _cache = cache;
    }
    public async Task<string> GetCachedDataAsync(string key, CancellationToken token = default)
    {
        return await _cache.GetOrCreateAsync(
            $"{key}",
            async cancel => await GetDataAsync(key, cancel),
            token: token
        );
    }
    private async Task<string> GetDataAsync(string key, CancellationToken token)
    {
        return $"Data for cache entry with key: {key}";
    }
}

The GetCachedDataAsync method is responsible for retrieving data from the cache based on a key. While this method returns data if it is available in the cache, it takes advantage of a fallback strategy if the data is not available in the cache and returns the data from a secondary source.

Complete Program.cs file

The following is the complete source code of the Program.cs file for your reference.

using HybridCacheDemo;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container
builder.Services.AddHybridCache();
builder.Services.AddSingleton<ICustomHybridCacheService, CustomHybridCacheService>();
builder.Services.AddControllers();
var app = builder.Build();
// Configure the HTTP request pipeline.
app.UseAuthorization();
app.MapControllers();
app.Run();

Execute the application

Finally, when you execute the application, the data (as a simplex text message) together with the cache key will be displayed in the web browser as shown in Figure 2.

As with in-memory and distributed caching, you can remove cache entries from the primary and secondary caches when using the HybridCache library. It should be noted that HybridCache leverages System.Runtime.Caching.MemoryCache as its primary cache storage by default. For secondary storage of the cached data, it uses SQL Server or any out-of-process storage such as Redis. With HybridCache, you can use earlier versions of the .NET runtimes, such as .NET Framework 4.7.2 and .NET Standard 2.0. You can learn more about HybridCache from the GitHub repository here.