Ofn.ServiceFabric.Cache

This repository is just a personal playground for creating a distributed cache using service fabric. I have started from the great work already done by others at SoCreate https://github.com/SoCreate/service-fabric-distributed-cache

What is it?

A caching service on service fabric with an IDistributedCache netstandard implementation using said service.

Where to get it

An initial alpha version has been published to NuGet

• Server Library: https://www.nuget.org/packages/Ofn.ServiceFabric.Cache/
• Client Library: https://www.nuget.org/packages/Ofn.ServiceFabric.Cache.Client/

How to use it?

Two things is required to start using the cache, a cache store/server which hosts the cached values, and a client that consumes and adds data to the cache.

Setting up a cache store

1. Create a new .NET Core Stateful Service
2. Add a reference to the Ofn.ServiceFabric.Cache package
3. Either change the auto-generated class or add a new one that inherits from BaseCacheStoreService like so

    internal sealed class CacheHost : BaseCacheStoreService
    {
        public CacheHost(StatefulServiceContext context, ILogger<ICacheStoreService> logger)
            : base(context, logger: logger)
        { }
    }

Refer to the CachingService project for a more complete example.

Using the cache store

1. Create any type of .NET Core service fabric application (SF remoting is used for communication with the store)
2. Add a reference to the Ofn.ServiceFabric.Cache.Client package
3. Configure the .net core container in startup (or a similar location):

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDistributedServiceFabricCache();
        }

4. Let something consume an IDistributedCache and use it as you would any instance of it, like the following ValuesController

    public class ValuesController : ControllerBase
    {
        private readonly IDistributedCache cache;

        public ValuesController(IDistributedCache cache) {
            this.cache = cache;
        }

        [HttpGet]
        public async Task<ActionResult<IEnumerable<string>>> Get() {
            var values = ( await this.cache.GetAsync("Values") ).FromByteArray<List<string>>();
            return values ?? new List<string>();
        }
    }

Refer to the CacheConsumer project for a more complete example.

Using HybridCache (.NET 10+)

HybridCache (two-level L1/L2 cache introduced in .NET 9) can use IDistributedCache as its distributed backing store. Since this library provides a full IDistributedCache implementation targeting .NET 10, no additional glue code is required.

See docs/hybrid-cache.md for a full setup guide and usage examples.

Telemetry

Both the cache store and client libraries expose System.Diagnostics.Metrics counters and histograms compatible with OpenTelemetry and dotnet-counters.

See docs/telemetry.md for the full metrics reference.

Why not just contribute to SoCreate Distributed Cache?

Well there is only really one reason, I stumbled upon the SoCreate distributed cache while doing stuff at work, and found it lacked a few minor things I would like to have, but my initial PR was met with "not atm" (understandably, I'm not pointing fingers here).

I have struggled with caching before, and figured I could have this as my personal pet hobby project, while also getting stuff done at work.

Maybe something will come of it, maybe not - but there it is, no good reason what so ever - but who said you needed a good reason :-)

Contributing

If you want to contribute, feel free to do so, here are some suggestions on how to do that

• Add/Create issues
• Submit Pull Requests that relates to specific issues
• Pull Requests which expands the test coverage
• Pull Requests for a benchmark (redis, sqlserver, service fabric)
• Documentation! (Obviously)

Development

Run unit tests and build:

dotnet test
dotnet build

⚠️ Always verify against a local SF cluster before pushing

Unit tests use a mock state manager that does not enforce Service Fabric's replica lifecycle constraints (e.g. the state manager not being readable during OnChangeRoleAsync). This means tests can pass for code that will crash the service at startup.

After any change to the SF lifecycle methods (OnOpenAsync, OnChangeRoleAsync, RunAsync, OnCloseAsync) or the Reliable Dictionary initialization, deploy and run CachingService against a local SF dev cluster to confirm the replica starts cleanly. Check the SF Event Log / Service Fabric Explorer for ReplicaOpenStatus warnings or FabricNotReadableException errors before pushing.