How to Use HybridCache in ASP.NET Core

HybridCache is a new API in.NET 9 that improves and simplifies caching in ASP.NET Core. Here’s how to make use of it.

Caching is an effective strategy for increasing application scalability and performance. Caching support has been added to legacy ASP.NET and, more recently, ASP.NET Core frameworks. In ASP.NET Core, caching is divided into two types: in-memory caching and distributed caching.

With.NET 9, which is currently in preview, ASP.NET Core now has three caching options. HybridCache is a new library designed to address the shortcomings of both in-memory and distributed caching. This article discusses HybridCache, its importance, and how to use it in ASP.NET Core applications.

Introducing HybridCache

ASP.NET Core’s built-in caching mechanisms can cause race conditions, potentially leading to a cache stampede. A cache stampede occurs when multiple requests are made to the same piece of data stored in the cache, overloading the application and rendering caching ineffective.

HybridCache is a new library that builds on top of the existing Microsoft.Extensions.Caching.The Distributed.IDistributedCache library. HybridCache enhances the existing caching mechanisms of ASP.NET Core and adds several new features and useful capabilities:

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

HybridCache utilizes two types of cache storage: L1 cache (in-process) and L2 cache (out-of-process). While L1 is a fast in-memory cache that stores data in your computer’s primary memory, L2 is slower but can store larger amounts of data that are frequently distributed across multiple servers.

HybridCache overcomes the limitations of IDistributedCache and IMemoryCache by combining their most useful features and capabilities. Stampede protection is a feature that saves resources by preventing multiple requests from accessing the same information at the same time, reducing the application’s load. HybridCache also supports numerous serialization options, allowing you to specify how your data should be saved or retrieved, increasing flexibility.

The primary advantages of HybridCache are greater simplicity, improved performance, and increased efficiency.

HybridCache is an abstract class that belongs to Microsoft.Extensions.Caching.Hybrid namespace. To store data in the cache and retrieve data from it, use the HybridCache class’s GetOrCreateAsync method. This method uses the cache key to retrieve an object from the primary cache.

If the object requested by the application is not found in the cache, resulting in a cache miss, the method checks the secondary cache, if one is configured. If the data is not available there, the method saves the object to 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 provided in the following sections.

Install the HybridCache NuGet package

To work with the HybridCache library, we must first install its NuGet package in the project. To do this, select the project in the Solution Explorer window, then right-click and choose “Manage NuGet Packages.”

In the NuGet Package Manager window, look for Microsoft.Extensions.Download the Caching.Hybrid package and install it. Remember to select the “Include prerelease” checkbox.

Alternatively, you can install the package using the NuGet Package Manager console by running the following command.

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

Registering and configuring HybridCache in ASP.NET Core

After you’ve installed HybridCache in your project, you should register it as a service with the dependency injection container by adding the following code to 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 using the code snippet provided 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 takes advantage of HybridCache.

Create the CustomHybridCache service in ASP.NET Core

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

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

Create a new class, CustomHybridCacheService, that implements the ICustomHybridCacheService interface, as shown in the code 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 using a key. While this method returns data if it is available in the cache, if it is not, it uses a fallback strategy to retrieve the data from a secondary source.

Complete Program.cs file

For your convenience, the Program.cs file’s complete source code is provided below.

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 run the application, the data (as a simplex text message) and the cache key will be displayed in the web browser, as illustrated in Figure below.

When using the HybridCache library, you can remove cache entries from both the primary and secondary caches, just like in-memory and distributed caching. It should be noted that HybridCache uses the System.Runtime.Caching.MemoryCache is the primary cache storage by default. SQL Server or another out-of-process storage system, such as Redis, is used for secondary cached data storage. HybridCache supports earlier versions of the.NET runtimes, such as.NET Framework 4.7.2 and.NET Standard 2.0. The GitHub repository contains additional information about HybridCache.