FloxDc.CacheFlow 1.10.0-beta3

.NET 5.0 .NET Core 3.1
This is a prerelease version of FloxDc.CacheFlow.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package FloxDc.CacheFlow --version 1.10.0-beta3
NuGet\Install-Package FloxDc.CacheFlow -Version 1.10.0-beta3
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.10.0-beta3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add FloxDc.CacheFlow --version 1.10.0-beta3
#r "nuget: FloxDc.CacheFlow, 1.10.0-beta3"
#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.10.0-beta3&prerelease

// Install FloxDc.CacheFlow as a Cake Tool
#tool nuget:?package=FloxDc.CacheFlow&version=1.10.0-beta3&prerelease

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

Quick Start

Install a package via NuGet

PM> Install-Package FloxDc.CacheFlow -Version 1.9.1

And add following lines to your Startup.cs file:

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

Caching strategies

The library builds on top of standard caching interfaces of .NetCore, so most of its methods have same names as regual caching services and use same option types.

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 local. There is a DoubleFlow approach for that case. Note some methods of DoubleFlow may return a ValueTask where 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 in key naming
CacheKeyPrefix Sets a prefix to cache keys
DataLoggingLevel Normal Sets a logging level of cache values and execution points
SuppressCacheExceptions true Enables suppression of throwing exceptions, caused by caching service itself
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)
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 binary serializer which isn't suitable well for real world task, so I recommend to replace it with another one. There are two existing options, and also you could use your own implementation.

Json

A Newtonsoft.Json serializer.

Install a package via NuGet

PM> Install-Package FloxDc.CacheFlow.Json -Version 1.7.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.7.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

|Warning!| |--------| OpenTelemerty is currently in alpha, a version of the package and it's usage may change dramatically over time.

CacheFlow emits DiagnosticSource events and execution state logs. There is an integration with OpenTelemerty already in the place.

Install a package via NuGet

PM> Install-Package FloxDc.CacheFlow.OpenTelemerty -Version 1.7.1

services.AddOpenTelemetrySdk(builder =>
    {
        builder
            .AddCacheFlowInstrumentation()
            .UseJaegerActivityExporter(options =>
            {
                options.ServiceName = serviceName;
                options.AgentHost = agentHost;
                options.AgentPort = agentPort;
            })
            .SetResource(Resources.CreateServiceResource(serviceName))
            .SetSampler(new AlwaysOnActivitySampler());
    });
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 was computed.  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 21,820 11/22/2022
1.11.0 11,285 9/30/2022
1.10.0 22,458 12/24/2021
1.10.0-beta3 715 11/21/2021
1.9.1 7,644 2/20/2021
1.8.0 2,705 11/12/2020
1.7.0 4,404 5/30/2020
1.6.4 1,485 3/18/2020
1.6.3 931 2/23/2020
1.6.2 742 1/15/2020
1.6.1 684 1/12/2020
1.6.0 806 11/1/2019
1.5.2 1,175 6/11/2019
1.5.2-beta1 480 6/7/2019
1.5.1 1,350 3/20/2019
1.5.0 567 3/20/2019
1.4.0 643 12/23/2018
1.3.1 841 9/20/2018
1.3.0 757 9/20/2018
1.3.0-beta2 609 9/18/2018
1.3.0-beta1 763 7/10/2018
1.3.0-alpha 688 9/18/2018
1.2.0 984 7/6/2018

- Nullable annotations
- netcoreapp2.1 support ended
- net6.0 support added
- code base clean-up and readability improvements
- modern telemetry support