Skip to main content

Use Zaris as a distributed cache in ASP.NET Core

In this tutorial, you build an ASP.NET Core web API that stores and reads values through the standard IDistributedCache interface, backed by a Zaris store. You register the cache once at startup and then depend on IDistributedCache in a controller, exactly as you would with any other distributed cache provider. You need the .NET SDK.

The Clustron.Zaris.DistributedCache package supplies an IDistributedCache implementation that reads and writes through a named Zaris store. You register a store with AddClustronZaris, then register the cache against that same store name.

1. Create a web API project​

Create a controller-based web API project.

dotnet new webapi --use-controllers -o ZarisCacheDemo
cd ZarisCacheDemo

2. Add the cache package​

Add the distributed cache package. It depends on the Zaris client and the in-process store, so those come in transitively.

dotnet add package Clustron.Zaris.DistributedCache

3. Register the store and the cache​

Open Program.cs. Register a Zaris store named cache in in-process mode, then register the distributed cache against that same store name. The cache resolves the store's client from dependency injection, so the store name you pass to AddClustronDistributedCache must match the one you registered with AddClustronZaris.

using Clustron.Zaris.Client.DependencyInjection;
using Clustron.Extensions.Caching.Distributed;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddClustronZaris("cache", "zaris://inproc/cache");

builder.Services.AddClustronDistributedCache("cache", options =>
{
    options.KeyPrefix = "app:";
});

var app = builder.Build();

app.MapControllers();

app.Run();

The KeyPrefix option is prepended to every key the cache stores, which keeps cache entries from colliding with other keys in the same store. Registering a single cache also makes it the default IDistributedCache, so anything that depends on IDistributedCache — including framework features such as session state — uses Zaris.

4. Add a controller that uses the cache​

Add a file named Controllers/CacheController.cs. The controller depends on IDistributedCache through its constructor and does not reference Zaris at all: it works against the standard interface. IDistributedCache stores byte arrays, so the controller encodes and decodes strings itself.

using System.Text;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Caching.Distributed;

[ApiController]
[Route("[controller]")]
public class CacheController : ControllerBase
{
    private readonly IDistributedCache _cache;

    public CacheController(IDistributedCache cache) => _cache = cache;

    [HttpGet("{key}")]
    public async Task<IActionResult> Get(string key)
    {
        var bytes = await _cache.GetAsync(key);
        if (bytes is null)
        {
            return NotFound();
        }

        return Ok(Encoding.UTF8.GetString(bytes));
    }

    [HttpPost("{key}")]
    public async Task<IActionResult> Set(string key, [FromBody] string value)
    {
        await _cache.SetAsync(
            key,
            Encoding.UTF8.GetBytes(value),
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5)
            });

        return Ok();
    }
}

Setting AbsoluteExpirationRelativeToNow gives the entry a time-to-live: the cache writes the value with that expiration, and the store drops it automatically when the window elapses. Omit it and the value stays until it is overwritten or removed.

5. Run and test​

Start the app.

dotnet run

Note the HTTP address it prints, then store and read a value. The example below uses port 5000; use whatever address your app reports.

curl -X POST http://localhost:5000/cache/greeting \
  -H "Content-Type: application/json" \
  -d "\"hello world\""

curl http://localhost:5000/cache/greeting

The second call returns hello world. The value was written to the Zaris store under the key app:greeting and read back through the same cache.

What you built​

You wired Zaris in as the IDistributedCache for an ASP.NET Core app. Your controller code depends only on the standard caching interface, so it stays portable while Zaris does the storage. You saw how the registered store name links AddClustronDistributedCache to the AddClustronZaris store, how KeyPrefix namespaces cache entries, and how DistributedCacheEntryOptions maps an expiration onto the store's time-to-live. Because the store runs in-process here, the whole thing works with no server; switch the store to remote mode to share the cache across instances.

Next steps​