Caching
The Hazelcast.Net.Caching NuGet package provides an IDistributedCache
implementation based upon the Hazelcast .NET Client. In its most basic usage, the IDistributedCache
implementation can be instantiated explicitly with classical Hazelcast options, plus some HazelcastCacheOptions
which specify the cache unique identifier.
The cache is implemented as a Hazelcast map, and the unique identifier corresponds to the name of the map.
The cache can be simply instantiated as:
var hazelcastOptions = new HazelcastOptionsBuilder()....Build();
var cacheOptions = new HazelcastCacheOptions
{
CacheUniqueIdentifier = "some-cache"
};
IDistributedCache cache = new HazelcastCache(hazelcastOptions, cacheOptions);
Note that the cache implementation also supports running on top of a failover client:
var hazelcastOptions = new HazelcastFailoverOptionsBuilder()....Build();
var cacheOptions = new HazelcastCacheOptions
{
CacheUniqueIdentifier = "some-cache"
};
IDistributedCache cache = new HazelcastCache(hazelcastOptions, cacheOptions);
Warning
Note that the failover client is only supported by Enterprise clusters.
Dependency Injection Support
In addition, the NuGet package provides utilities for using the cache in a dependency-injection environment. Provided that Hazelcast options and cache options have been registered in a service container, then the IDistributedCache
implementation can be registered with one single line of code:
services.AddHazelcastOptions(...);
services.Configure<HazelcastCacheOptions>(options => options.CacheUniqueIdentifier = "some-cache");
services.AddHazelcastCache(withFailover: false); // register cache
Or the failover counterpart:
services.AddHazelcastFailoverOptions(...);
services.Configure<HazelcastCacheOptions>(options => options.CacheUniqueIdentifier = "some-cache");
services.AddHazelcastCache(withFailover: true); // register cache
With these declarations, the Hazelcast cache implementation would be injected into any service requiring an IDistributedCache
.
Cache Functionality
Hazelcast's implementation of IDistributedCache
supports all functionality of the interface. Note however that, due to the inherently asynchronous nature of the Hazelcast client, all synchronous cache operations have to be implemented over asynchronous operations using the task.GetAwaiter().GetResult()
pattern. This pattern can cause potential threading problems, and should be avoided as much as possible. Always use the asynchronous API wherever possible.
ASP.NET Core Session State Provider
IDistributedCache
implementation can be used to store session state in Hazelcast. After registering
Hazelcast IDistributedCache
implementation to DI (as described above) you can enabled session state management
in your ASP.NET Core project.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHazelcastCache();
var app = builder.Build();
app.UseSession(); // Session state will be stored in distributed cache provided by AddHazelcastCache()
Warning
When the ISession object is supported by the Hazelcast client, its synchronous operations should be avoided, as the Hazelcast client is fully asynchronous and therefore calls to task.GetAwaiter().GetResult() may be involved and, potentially, cause threading issues. Prefer the asynchronous operations, such as those provided in the SessionExtensions class.