FloxDc.CacheFlow 1.13.0

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Core 3.1 This package targets .NET Core 3.1. The package is compatible with this framework or higher. 
dotnet add package FloxDc.CacheFlow --version 1.13.0                

                    
                

            
NuGet\Install-Package FloxDc.CacheFlow -Version 1.13.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.13.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add FloxDc.CacheFlow --version 1.13.0                

                    
                

            
#r "nuget: FloxDc.CacheFlow, 1.13.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.13.0

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

CacheFlow

CacheFlow is a cache management system for .Net Core. It helps you use cache and handle complex cases like value serialization, default values, and the Get or Set pattern.

Table of Content

The library reduces boilerplate code and builds on standard .Net caching interfaces. Most methods have the same names and option types as regular caching services. It also adds convenience features like the GetOrSet method.

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;
}

This is the simplest example. The library also includes safety checks, serialization, logging, and other useful features.

Quick Start

Install the package via NuGet

PM> Install-Package FloxDc.CacheFlow -Version 1.13.0

Add the 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 the cache, and sets it if not found
GetOrSetAsync Tries to get a value from the cache, and sets it if not found
Remove Removes a specified cache entry
Set Sets a cache entry with a provided value
TryGetValue Tries to get a value from the cache

Distributed

DistributedFlow
Method Description
GetAsync Gets a value from the cache
GetOrSet Tries to get a value from the cache, and sets it if not found
GetOrSetAsync Tries to get a value from the cache, and sets it if not 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 the cache

Both In-Memory And Disitibuted

For immutable data, you may want to cache it both distributed and in-memory. Use the DoubleFlow approach.

Warning! Note that some methods of DoubleFlow may return a ValueTask where DistributedFlow returns a Task.

DoubleFlow
Method Description
GetAsync Gets a value from the cache
GetOrSet Tries to get a value from the cache, and sets it if not found
GetOrSetAsync Tries to get a value from the cache, and sets it if not 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 the cache

Options

You can configure CacheFlow with the following options:

Parameter Default Meaning
CacheKeyDelimiter :: Delimiter used for key construction
CacheKeyPrefix Prefix for all cache keys within an app
DataLoggingLevel Normal Logging level for cache values and execution points (hit, miss, data calculation, etc.)
SuppressCacheExceptions true Suppresses exceptions caused by the caching service itself. Useful if your app can tolerate invalid cache requests.
Data Logging Levels

CacheFlow can produce different types of monitoring events:

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 suppression is on and it may slow down your application.
Turn off this option if you are confident in your caching system.

Named instances

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

public MyClass(IMemoryFlow<MyClass> cache)

This is useful if you want to find a key in a database.

Time Spans

To avoid overlaps in caching, you can use the 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 methods during the configuration step to use it. There are two more pre-built options, and you can also implement your own serializer.

Json

A Newtonsoft.Json serializer.

Install the package via NuGet

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

Add the following lines to your configuration:

services.AddMemoryFlow()
    .AddCacheFlowJsonSerialization();
MessagePack

A neuecc's MessagePack serializer.

Install the package via NuGet

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

Add the following lines to Startup.cs:

var messagePackOptions = MessagePackSerializerOptions.Standard;

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

Note: MessagePack requires a structured map of serialized data

Telemetry

The package supports .Net activity-based telemetry. Register a source from the FloxDc.CacheFlow.Telemetry.ActivitySourceHelper namespace 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();

Benchmarks

The library has been tested with the following benchmarks:

** 1.12.0**

BenchmarkDotNet v0.14.0, Windows 11 (10.0.22631.4317/23H2/2023Update/SunValley3)
12th Gen Intel Core i7-12700H, 1 CPU, 20 logical and 14 physical cores
.NET SDK 8.0.403
  [Host]     : .NET 8.0.10 (8.0.1024.46610), X64 RyuJIT AVX2
  DefaultJob : .NET 8.0.10 (8.0.1024.46610), X64 RyuJIT AVX2
Method Mean Error StdDev Gen0 Allocated
GetOrSet 266.46 ns 5.309 ns 4.966 ns 0.0949 1192 B
GetOrSetAsync 1,280.23 ns 16.234 ns 14.391 ns 0.1335 1687 B
Remove 85.99 ns 1.384 ns 1.295 ns 0.0362 456 B
Set 144.00 ns 2.874 ns 3.422 ns 0.0579 728 B
TryGetValue 92.13 ns 1.640 ns 1.534 ns 0.0370 464 B

1.13.0

BenchmarkDotNet v0.14.0, Windows 11 (10.0.22631.4317/23H2/2023Update/SunValley3)
12th Gen Intel Core i7-12700H, 1 CPU, 20 logical and 14 physical cores
.NET SDK 8.0.403
  [Host]     : .NET 8.0.10 (8.0.1024.46610), X64 RyuJIT AVX2
  DefaultJob : .NET 8.0.10 (8.0.1024.46610), X64 RyuJIT AVX2
Method Mean Error StdDev Gen0 Allocated
GetOrSet 268.21 ns 4.083 ns 3.619 ns 0.0949 1192 B
GetOrSetAsync 1,282.62 ns 15.648 ns 14.637 ns 0.1335 1686 B
Remove 89.43 ns 1.404 ns 1.245 ns 0.0362 456 B
Set 148.76 ns 2.934 ns 2.744 ns 0.0579 728 B
TryGetValue 96.02 ns 1.026 ns 0.960 ns 0.0370 464 B
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 is compatible.  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.13.0 413 10/25/2024
1.12.0 28,048 11/22/2022
1.11.0 11,345 9/30/2022
1.10.0 22,538 12/24/2021
1.10.0-beta3 764 11/21/2021
1.9.1 7,703 2/20/2021
1.8.0 2,746 11/12/2020
1.7.0 4,468 5/30/2020
1.6.4 1,528 3/18/2020
1.6.3 998 2/23/2020
1.6.2 787 1/15/2020
1.6.1 726 1/12/2020
1.6.0 843 11/1/2019
1.5.2 1,216 6/11/2019
1.5.2-beta1 507 6/7/2019
1.5.1 1,403 3/20/2019
1.5.0 599 3/20/2019
1.4.0 663 12/23/2018
1.3.1 884 9/20/2018
1.3.0 795 9/20/2018
1.3.0-beta2 645 9/18/2018
1.3.0-beta1 792 7/10/2018
1.3.0-alpha 727 9/18/2018
1.2.0 1,036 7/6/2018

Warning: logger messages are slightly changed. Please update your logger configuration if needed.
     
     * CVE-2024-48924 fixed
     * .Net 8 support
     * Code improvments