FloxDc.CacheFlow 1.12.0

dotnet add package FloxDc.CacheFlow --version 1.12.0                
NuGet\Install-Package FloxDc.CacheFlow -Version 1.12.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FloxDc.CacheFlow" Version="1.12.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add FloxDc.CacheFlow --version 1.12.0                
#r "nuget: FloxDc.CacheFlow, 1.12.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install FloxDc.CacheFlow as a Cake Addin
#addin nuget:?package=FloxDc.CacheFlow&version=1.12.0

// Install FloxDc.CacheFlow as a Cake Tool
#tool nuget:?package=FloxDc.CacheFlow&version=1.12.0                

CacheFlow

CacheFlow is a cache management system for .Net Core. It ables you not only use cache but handles various complex use cases i.e. value serialization, default values, the Get or Set pattern.

Table of Content

The library removes boilerplate code and builds on top of standard caching interfaces of .Net, so most of its methods have same names as regular caching services and use same option types. In addition to standard features it adds a little bit of comfort. For instance one may use the GetOrSet method instead of Get and Set separately. Just use this:

public T CacheFlowWay<T>(string key, TimeSpan expirationTime)
    => GetOrSet(key, CalculateResult, timeout)

instead of this:

public T UsualWay<T>(string key, TimeSpan expirationTime)
{
    if (Cache.TryGetValue(key, out T result))
        return result;

    result = CalculateResult();

    Cache.Set(key, result, expirationTime);
    return result;
}

And that's the simpliest example. In addition the library contains safity checks, serialization, logging, and other handy features.

Quick Start

Install a package via NuGet

PM> Install-Package FloxDc.CacheFlow -Version 1.10.0

And add following lines to your Startup.cs file:

services.AddMemoryCache()
    .AddStackExchangeRedisCache(options => 
    { 
        options.Configuration = Configuration["Redis:Endpoint"]; 
    })
    .AddDoubleFlow();

Caching strategies

In-Memory

MemoryFlow
Method Description
GetOrSet Tries to get a value from a cache, and sets it if no entries were found
GetOrSetAsync Tries to get a value from a cache, and sets it if no entries were found
Remove Removes a specified cache entry
Set Sets a cache entry with a provided value
TryGetValue Tries to get a value from a cache

Distributed

DistributedFlow
Method Description
GetAsync Gets a value from a cache
GetOrSet Tries to get a value from a cache, and sets it if no entries were found
GetOrSetAsync Tries to get a value from a cache, and sets it if no entries were found
Refresh Refreshes a specified cache entry
RefreshAsync Refreshes a specified cache entry
Remove Removes a specified cache entry
RemoveAsync Removes a specified cache entry
Set Sets a cache entry with a provided value
SetAsync Sets a cache entry with a provided value
TryGetValue Tries to get a value from a cache

Both In-Memory And Disitibuted

When you work with immutable data you may want to cache it both distributed and in-memory. There is a DoubleFlow approach for that case. Note some methods of the DoubleFlow may return a ValueTask where the DistributedFlow returns a Task.

DoubleFlow
Method Description
GetAsync Gets a value from a cache
GetOrSet Tries to get a value from a cache, and sets it if no entries were found
GetOrSetAsync Tries to get a value from a cache, and sets it if no entries were found
Refresh Refreshes a specified cache entry
RefreshAsync Refreshes a specified cache entry
Remove Removes a specified cache entry
RemoveAsync Removes a specified cache entry
Set Sets a cache entry with a provided value
SetAsync Sets a cache entry with a provided value
TryGetValue Tries to get a value from a cache

Options

There is a set of options you can use to configure CacheFlow:

Parameter Default Meaning
CacheKeyDelimiter :: Sets a delimiter which uses for key construction
CacheKeyPrefix Sets a prefix to all cache keys within an app
DataLoggingLevel Normal Sets a logging level of cache values and execution points, like hit, miss, data calculation etc.
SuppressCacheExceptions true Enables exception throwing suppression, for error caused by caching service itself. Suitable when your app tolerate for invalid cache requests.
Data Logging Levels

The library can produce monitoring events of different types:

Level Behavior
Disabled Emits only tracing events
Normal Traces events, logs operations, their result states, and cache keys
Sensitive Traces events, logs operations, their result states, cache keys, and cached values
Exception Suppression

Warning!

By default exception supression is on and it may slow down your application. Turn off the option if you confident in your caching system.

Named instances

You could use typed service insances to autoprefix cache keys with the class name:

public MyClass(IMemoryFlow<MyClass> cache)

Useful if one want to find a key in a database.

Time Spans

If you want to avoid overlaps in caching, you may use following TimeSpan extensions:

Method Name Time Frame
BeforeMinuteEnds up to 1 minute
BeforeTwoMinutesEnd up to 2 minutes
BeforeFiveMinutesEnd up to 5 minutes
BeforeTenMinutesEnd up to 10 minutes
BeforeQuarterHourEnds up to 15 minutes
BeforeHalfHourEnds up to 30 minutes
BeforeHourEnds up to 60 minutes
BeforeDayEnds up to 24 hours

Extensions

Serialization

By default CacheFlow uses the System.Text.Json serializer. Add no extension metoods on a configuration step to use that method. There are two more pre-built options, and also you could implement your own serializer as well.

Json

A Newtonsoft.Json serializer.

Install a package via NuGet

PM> Install-Package FloxDc.CacheFlow.Json -Version 1.10.0

And add following lines to your configuration:

services.AddMemoryFlow()
    .AddCacheFlowJsonSerialization();
MessagePack

A neuecc's MessagePack serializer.

Install a package via NuGet

PM> Install-Package FloxDc.CacheFlow.MessagePack -Version 1.10.0

And add following lines to Startup.cs:

var messagePackOptions = MessagePackSerializerOptions.Standard;

services.AddMemoryFlow()
    .AddCacheFlowMessagePackSerialization(messagePackOptions, StandardResolver.Instance);

Keep in mind MessagePack requires to specify a structured map of serialized data.

Telemetry

The package supports standard .Net activity-based telemetry. Register a source from a namespace FloxDc.CacheFlow.Telemetry.ActivitySourceHelper to enable it. Here's an example of OpenTelemetry configuration with the source:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // other configs
    .AddSource(ActivitySourceHelper.CacheFlowActivitySourceName)
    // other configs
    .Build();    
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.1 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on FloxDc.CacheFlow:

Package Downloads
FloxDc.CacheFlow.Json

Newtonsoft Json serialization for FloxDc's Cache Flow

FloxDc.CacheFlow.MessagePack

Message Pack serialization for FloxDc's Cache Flow

FloxDc.CacheFlow.OpenTelemetry

An OpenTelemetry instrumentation for CacheFlow

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.12.0 24,755 11/22/2022
1.11.0 11,295 9/30/2022
1.10.0 22,490 12/24/2021
1.10.0-beta3 717 11/21/2021
1.9.1 7,653 2/20/2021
1.8.0 2,711 11/12/2020
1.7.0 4,412 5/30/2020
1.6.4 1,490 3/18/2020
1.6.3 938 2/23/2020
1.6.2 747 1/15/2020
1.6.1 690 1/12/2020
1.6.0 811 11/1/2019
1.5.2 1,182 6/11/2019
1.5.2-beta1 484 6/7/2019
1.5.1 1,360 3/20/2019
1.5.0 572 3/20/2019
1.4.0 654 12/23/2018
1.3.1 853 9/20/2018
1.3.0 767 9/20/2018
1.3.0-beta2 616 9/18/2018
1.3.0-beta1 765 7/10/2018
1.3.0-alpha 694 9/18/2018
1.2.0 994 7/6/2018

Warning: .Net 7 libraries officially support only .Net 6+ projects! Please, reach us on Github in case of any inconsistancies.

- .Net 7 support
- New way of serializer configuration
- Code improvments