NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet
NuGet, #1790 most downloaded on NuGet
FusionCache serializer based on Newtonsoft Json.NET
Latest stable
2.9.0
Last release 2 months ago
22 Sep 2026
Release timing varies
gaps range from 8 days to 5 months
Nearly every release is documented
notes for 46 of 47 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
66 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
- Update: package dependencies
Community member @sfhb24 noticed that during an Eager Refresh the L2 was not being checked.
Now, this is admittedly not a huge thing per se, because of 2 reasons:
In both these cases, the extra L2 check during an eager refresh would not be necessary.
Having said that, an L1+L2 setup without a backplane or a distributed locker may also be common, and in that case the new L2 check in the eager refresh window can in fact be helpful in reducing the amount of factory executions even more.
Long story short: I just implemented it!
See here for the issue.
If a factory fails when executed in the background during an eager refresh, FusionCache already takes care of everything and correctly releases the potentially acquired locks (memory and/or distributed), and this is good.
But community member @joaopbnogueira noticed a peculiar edge case: if the factory is not one marked with the async keyword AND it throws an exception, the memory lock is not being released properly.
Or, to better say, "was not". Because now this has been fixed.
Thanks João for spotting this.
See here for the issue.
Community member @joaopbnogueira also noticed another peculiar scenario, specifically when a MemoryCache write fails (yep, it can happen, true story).
Here's an example of it:
MemroyCache is being used as the L1SizeLimitSize specifiedSizeLimit it's mandatory for every entry to specify a Size)In this scenario a distributed lock may not have been released.
But fear no more: this does not hapen anymore!
See here for the issue.
Clear(false) + Fail-SafeCommunity member @joaopbnogueira (damn, he is on a roll!) noticed something else, that somehow went unnoticed until now.
In some cases, after a Clear(false) call, an expired entry saved with Fail-Safe enabled may still be returned by FusionCache.
This too has now been fixed.
See here for the issue.
Community member @GordeySt sent a PR with some really nice optimizations, particularly around reducing resource allocations and CPU consumption when working with metrics.
Now, even with metrics enabled, the hot path is allocation free.
That's great, thanks Gordey!
See here for the PR.
The test suite just crossed the 1600 mark:
<img width="577" height="54" alt="image" src="https://github.com/user-attachments/assets/a361f17a-2296-4438-9c3e-38c04cd167a1" />
Nice 🙂
Your coding agent can read these notes before it upgrades. Set up the MCP server →
- Update: package dependencies
Community member @joaopbnogueira spotted a problem with an edge case: when using SkipDistributedCacheWrite the distributed locker was not being properly disposed, which was unfortunate.
Now this has been fixed.
See here for the issue.
Community member @igor-henriques noticed an issues because of which when the tag marker (the special cache entry containing the RemoveByTag() timestamp) expired, it was being re-materialized with a newer timestamp: this could have led to the same results as a new RemoveByTag() call.
That was unfortunate, but it has now been fixed.
See here for the issue.
RemoveByTagBehavior.RemoveCommunity member @gpetrou asked for some help regarding a certain scenario, and during the explanation/investigation it emerged that FusionCache could have handled RemoveByTagBehavior.Remove in a slightly better way.
It was mostly an edge case, but still: now the way it is internally handled is even better than before.
See here for the issue.
Community member @dzmitry-tsarevich highlighted that user-initiated cancellations were being handled in a little-too-aggressive way from the oint of view of observability: too much background noise was being generated, which could lead to bloat. Now this has been made better, slimmer.
See here for the issue.
Community member @Stepami noticed the lack of a specific ext method on the builder to register the distributed locker based on Redis, basically WithRedisDistributedLocker().
After accepting his PR, I noticed a couple of extra ones were also missing, and so I added them.
See here for the issue.
Also, community member @petriceko asked for a new overload of the WithOptions() ext method with better DI support: promptly, community member @vrbyjimmy made a PR to add that, which I merged.
Talk about community collaboration 🙂
See here for the issue.
- Update: package dependencies
Community member @erikatsg noticed what seemed like a strange behavior, but after a preliminary check discovered that the problem was on their side, because they were adding the same FusionCache registration to the DI container more than once.
Something like this:
services.AddFusionCache()
.WithDefaultEntryOptions(options =>
{
options.Duration = TimeSpan.FromSeconds(111);
});
// LATER...
services.AddFusionCache()
.WithDefaultEntryOptions(options =>
{
options.Duration = TimeSpan.FromSeconds(222);
});
This is generally not suggested nor supported.
Luckily, FusionCache already had a series of checks for that and more strange situations, and those checks emit log records in those situations.
Unluckily though, those checks were previously performed only when asking to the DI container for an IFusionCacheProvider (to work with named caches).
Well, not anymore: now it works in any setup/scenarion, all automatically.
The current list of checks performed is:
IFusionCache registrations (e.g.: multiple services.AddFusionCache() calls)IFusionCache registrations (e.g.: multiple services.AddFusionCache(name) calls with the same name)IFusionCache registrations (e.g.: multiple services.AddFusionCache().AsKeyedService(key) calls with the same key, for either named caches or the default cache)See here for the issue.
A new check has been added in the Advisor that detecs a potentially incorrect configuration for a System.Text.Json based serializer related to value tuples.
This is not about a FusionCache bug, but about the System.Text.Json serializer's default configuration deviating from the commonly expected one (like, historically, Json.NET for example), see here for more.
Instead of forcing a specific json configuration for FusionCache, the Advisor now checks if the serializer in use is not supporting value tuples correctly and, if so, emits a warning (also configurable) in the logs to warn users about that.
This allows them to make the best decision for their specific use case.
Thanks to @sychare and @bassepeder for the hints.
Also, the check for a missing CacheKeyPrefix is now better, more limited in scope.
See here and here for the issues.
SerializationConfigIssuesLogLevel optionSee the previous item: with this new option is possible to change the desired log level, or suppress it.
DistributedLockerErrorsLogLevel optionIt's now possible to granularly configure the log level to use for distributed lockers errors, which is nice.
Sometimes the handling of OTEL parent traces was not the best, particularly around highly multithreaded scenarios where a native Activity is not being passed around correctly in the context.
This has now been fixed.
RemoveByTag(tag) operation now include the tag (duh)Normally, every operation in the cache has a cache key as the main argument.
In the case of a RemoveByTag(tag) operation though, that is not the case since the main argument is not the cache key, but the tag: strangely enough, FusionCache previously was not logging it front and center, but now it does.
This should help with tagging-related investigations and troubleshootings.
Thanks to community member @tvardero for spotting this.
See here for the issue.
Thanks to community member @DanielStout5 for spotting this: it's quite rare, but sometimes an entry in L2 may be older than the corresponding entry in L1, and before this fix that assumption did not hold sometimes. Now an extra check is performed, to make sure that this scenario doesnot produce unwanted results.
See here for the issue.
Every single operation in FusionCache has a uniquely identifying operation id (OperationId): this becomes very useful with observability, mainly with logs.
Previously, when no logger was present, the operation id was not generated, at all: this was an optimization to avoid useless work when not actually needed.
But in a case of traces being used without a logger, the traces did not include the operation id for the reason explain above.
With this fix, the optimization is still there, but it also takes into account trace listeners, so that when either a logger or a trace listener is present the operation id is generated, otherwise the optimization is still there.
Community member @vrbyjimmy discovered a nasty issue with user-initiated cancellations when used with the distributed locker, see the issue for more details.
Than, community member @qjustfeelitp sent a PR to fix exactly this: teamwork doing its thing, amirite?
Long story short: now that specific OperationCanceledException is being specifically handled to avoid creating issues.
Thanks both!
See here for the issue.
Thanks to community member @SirPustekuchen for noticing that the MessagePack package version being normally used was since marked as vulnerable: now the reference has been updated.
And thanks to communiy membe @aki-matleb for doing the same, but for the OpenTelemetry.Api package.
See here and here for the issues.
As always, I took some time to updated the docs with the latest stuff and make them overall better.
- Update: package dependencies
[!NOTE] You should update to
v2.7.2, see here: there's a small issue inv2.7.0, nothing critical really, but better to use the new version.
A new check has been added in the Advisor that detecs a potentially incorrect configuration for a System.Text.Json based serializer related to value tuples.
This is not about a FusionCache bug, but about the System.Text.Json serializer's default behavior deviating from the commonly expected one (like, historically, Json.NET for example), see here for more.
Instead of forcing different json options specifically for FusionCache, the Advisor now checks if the serializer in use is not supporting value tuples correctly and, if so, emits a warning (also configurable) in the logs to warn users about that.
This allows them to make the best decision for their specific use case.
Thanks to @sychare and @bassepeder for the hints.
Also, the check for a missing CacheKeyPrefix is now better, more limited in scope.
See here and here for the issues.
SerializationIssuesLogLevel optionSee the previous item: with this new option is possible to change the desired log level, or suppress it.
DistributedLockerErrorsLogLevel optionIt's now possible to granularly configure the log level to use for distributed lockers errors, which is nice.
Sometimes the handling of OTEL parent traces was not the best, particularly around highly multithreaded scenarios where a native Activity is not being passed around correctly in the context.
This has now been fixed.
RemoveByTag(tag) operation now include the tag (duh)Normally, every operation in the cache has a cache key as the main argument.
In the case of a RemoveByTag(tag) operation though, that is not the case since the main argument is not the cache key, but the tag: strangely enough, FusionCache previously was not logging it front and center, but now it does.
This should help with tagging-related investigations and troubleshootings.
Thanks to community member @tvardero for spotting this.
See here for the issue.
Thanks to community member @DanielStout5 for spotting this: it's quite rare, but sometimes an entry in L2 may be older than the corresponding entry in L1, and before this fix that assumption did not hold sometimes. Now an extra check is performed, to make sure that this scenario doesnot produce unwanted results.
See here for the issue.
Every single operation in FusionCache has a uniquely identifying operation id (OperationId): this becomes very useful with observability, mainly with logs.
Previously, when no logger was present, the operation id was not generated, at all: this was an optimization to avoid useless work when not actually needed.
But in a case of traces being used without a logger, the traces did not include the operation id for the reason explain above.
With this fix, the optimization is still there, but it also takes into account trace listeners, so that when either a logger or a trace listener is present the operation id is generated, otherwise the optimization is still there.
Community member @vrbyjimmy discovered a nasty issue with user-initiated cancellations when used with the distributed locker, see the issue for more details.
Than, community member @qjustfeelitp sent a PR to fix exactly this: teamwork doing its thing, amirite?
Long story short: now that specific OperationCanceledException is being specifically handled to avoid creating issues.
Thanks both!
See here for the issue.
Thanks to community member @SirPustekuchen for noticing that the MessagePack package version being normally used was since marked as vulnerable: now the reference has been updated.
And thanks to communiy membe @aki-matleb for doing the same, but for the OpenTelemetry.Api package.
See here and here for the issues.
As always, I took some time to updated the docs with the latest stuff and make them overall better.
- Update: package dependencies
RemoveByTag()Normally, when calling RemoveByTag("my-tag"), the entries with such a tag will be gradually expired on a subsequent access.
Community member @charlesvigneault asked for the ability to instead properly remove them.
So I added a new option to allow configuring this behavior:
services.AddFusionCache()
.WithOptions(options =>
{
options.RemoveByTagBehavior = RemoveByTagBehavior.Remove;
});
See here for the original issue.
RemoveByTag("*") in HybridCache adapterAfter the initial release of HybridCache in 2025, the team added support for a special case: using RemoveByTag("*") to clear the entire cache.
I didn't notice untile recently, and thanks to community user @vrbyjimmy I did that. Or, to better say it, he did that! He acted so quickly that a PR immediately landed with the implementation, so thanks Jakub for that!
What happens underneath is that a RemoveByTag("*") call on the adapter is detected and re-routed to a Clear() call on the underlying FusionCache instance: very simple and elegant, and I like that a lot.
See here for the original issue.
Community user @jgshowpad noticed that when using the new distributed stampede protection introduced in v2.5.0 with Eager Refresh some errors were being logged.
That was caused by the Redis-based distributed locker not handling correctly a timeout of zero (which btw is a pretty common approach to basically check for a lock already being acquired by someone else, without having to wait).
This has now been fixed.
See here for the original issue.
GenerateOperationId()Community user @Inok contributed with a nice set of low-level perf optimizations for the GenerateOperationId() internal method, which may be called quite a lot when doing observability (logging, OTEL, etc).
That's a very nice and welcome contribution, thanks Pavel!
See here for the original issue.
Community member @mumin-khan noticed that, after releasing distributed stampede support in v2.5.0, I missed the related ext method for the the DI registration.
So now I added it, and it's now possible to do this:
builder.Services.AddFusionCacheRedisDistributedLocker(options =>
{
options.Configuration = ... ;
});
This has now been added, thanks Mumin!
See here for the original issue.
ConfigureAwait(false)Community user @JerinMathewJose01 noticed that on the old .NET Framework 4.7.2 and 4.8, sometimes the factory may remain stuck without completing correctly.
That was caused by a couple of missing ConfigureAwait(false) when awaiting the factory execution.
This has now been fixed.
See here for the original issue.
As always, I took some time to updated the docs with the latest stuff and make them overall better.
- Update: package dependencies
Since the very beginning FusionCache offered a solid Cache Stampede protection, as explained in the docs where it is clearly illustrated:
Such protection worked not just in the normal flow (miss -> factory -> return) but also with other more advanced features like:
With time the stampede protection got even better, and even extensible: this allowed 3rd party implementations of the core mechanism, called memory locker (IFusionCacheMemoryLocker).
All of this without removing the normal "it just works" experience since, by default, a StandardMemoryLocker is used without needing any user setup or intervention.
Cool.
But here's the thing: this protection had always been a local thing, meaning it did not span multiple nodes, in a distributed way: this meant that, if we were "unlucky", multiple factories could have run at the same time for the same cache key on different nodes.
Meaning, this:
But that was true until now: enter Distributed Cache Stampede Protection 🎉
Thanks to the introduction of the new IFusionCacheDistributedLocker (see the next point) it's now possible to coordinate factory execution accross multiple nodes, so that only one factory would run at the same time for the same cache key even on different nodes.
Meaning, this:
By providing an IFusionCacheDistributedLocker implementation during setup, FusionCache will take care of everything, we don't have to do anything else.
The setup looks like this:
services.AddFusionCache()
// SERIALIZER
.WithSerializer(
new FusionCacheSystemTextJsonSerializer()
)
// DISTRIBUTED CACHE
.WithDistributedCache(
new RedisCache(new RedisCacheOptions
{
Configuration = "localhost:6379",
})
)
// BACKPLANE
.WithBackplane(
new RedisBackplane(new RedisBackplaneOptions
{
Configuration = "localhost:6379",
})
)
// DISTRIBUTED LOCKER <-- HERE IT IS!
.WithDistributedLocker(
new RedisDistributedLocker(new RedisDistributedLockerOptions
{
Configuration = "localhost:6379",
})
);
Or, even better, if we want to re-use the same connection multiplexer for better performanceand use of resources, we can do this:
var muxer = ConnectionMultiplexer.Connect("localhost:6379");
services.AddFusionCache()
// SERIALIZER
.WithSerializer(
new FusionCacheSystemTextJsonSerializer()
)
// DISTRIBUTED CACHE
.WithDistributedCache(
new RedisCache(new RedisCacheOptions
{
ConnectionMultiplexerFactory = async () => muxer,
})
)
// BACKPLANE
.WithBackplane(
new RedisBackplane(new RedisBackplaneOptions
{
ConnectionMultiplexerFactory = async () => muxer,
})
)
// DISTRIBUTED LOCKER <-- HERE IT IS!
.WithDistributedLocker(
new RedisDistributedLocker(new RedisDistributedLockerOptions
{
ConnectionMultiplexerFactory = async () => muxer,
})
);
As always, the idea is that "it just works".
See here for the original issue.
As mentioned above, this is the new distributed component responsible for coordinating multiple factory executions on different nodes, all automatically.
As of now I'm providing 2 main implementations:
Of course the Redis one is the only real deal for now, meant for production use.
Other implementations in the future will be possible, by simply implementing the new IFusionCacheDistributedLocker abstraction, just like it was possible before with the IFusionCacheMemoryLocker abstraction.
So to recap:
I would say it's all pretty nice 🙂
See here for the original issue.
MemoryCacheDuration entry optionThis is seemingly small, but really important.
In a multi-node scenario with an L1+L2 setup it's important to keep the cache, as a whole, coherent.
When using a Backplane there's no need to do anything: all is taken care of, and the cache as a whole is always coherent.
But wha if we cannot or don't want to use a backplane, for... reasons?
Well, every change in the cache will leave the other L1s out-of-sync for the remaining time before their expiration, and this is not good.
This problem is known as Cache Coherence, and the backplane is what is used to SOLVE it. But if we can't use a backplane, we should at least MITIGATE it: and we can do that by reducing the incoherency window.
And how?
Well, by simply specifying 2 different durations: one for the L1 and one for the L2.
Now, with FusionCache it has always been possible to specify a different Duration for the distributed cache, thanks to the DistributedCacheDuration option.
The problem was that, when in the scenario above (L1+L2 and no backplane), it would have been nice to be able to simply say "keep all the durations as alrady specified, and just refresh the data in the L1 from L2 every few seconds".
But with only the DistributedCacheDuration option available, the way to achieve this was counterintuitive: instead of somehow override the L1 duration, we needed to lower the normal Duration to a few seconds and specify the intended logical duration as the DistributedCacheDuration.
Not terrible, but not great.
But now, not anymore: enter MemoryCacheDuration.
We can of course go granular on a call-by-call basis, but there's something better: we can simply specify a value in the DefaultEntryOptions, and all the existing call sites will inherit this new value which will automatically override the duration only for the L1.
Done.
And, if we use Tagging we can simply do the same thing for the TagsDefaultEntryOptions, and we're done.
Something like this:
services.AddFusionCache()
.WithOptions(options =>
{
options.DefaultEntryOptions.MemoryCacheDuration = TimeSpan.FromSeconds(5);
options.TagsDefaultEntryOptions.MemoryCacheDuration = TimeSpan.FromSeconds(5);
});
Oh, and the new Best Practices Advisor (see next point) can already give this advice when it detects such a scenario.
Nice 🙂
[!IMPORTANT] It's important to say that, if you can, you should always use the backplane, as that is THE way to solve cache coherence for good without out-of-sync windows or other issues.
See here for the original issue.
Sometimes we may inadvertently fall into a scenario with:
With time FusionCache got more and more new components (like #575 ) and options (like #571 ) and this, along with the naturally dynamic nature of a flexible setup and configuration, may lead to inadvertently make the wrong decisions and fall into some gotchas.
FusionCache already had a couple of internal checks, like looking for a missing CacheKeyPrefix when using a shared L1 (which may lead to cache key collisions), and warns about them in the logs.
Now this practice has been unified & expanded, and it has a name: Best Practices Advisor.
Long story short, FusionCache now checks for common pitfalls and can give warnings and suggestions, all automatically and based on the current runtime state: no need to scrape the docs to see if the current config may lead to surprises thanks to a bad incantation of options.
I'd like to highlight that I've been careful about not trying to make it too smart for its own good: that is an easy to miss cliff that would lead to exaggerate in the implemented heuristics and checks, leading to bad results.
The checks initially implemented are:
More checks will be added in the future, but for now these are already quite useful.
Oh, one final thing: if you are thinking "great, a new piece of AI crap that will waste resources" then... nah, it's just a bunch of ifs done automatically in the background during startup. And if you want you can disable the Advisor by simply setting the new EnableBestPracticesAdvisor option to false (default is true).
See here for the original issue.
IgnoreTimeoutsWhenDebugging optionCommunity user @tvardero asked if it was possible to automatically ignore all timeouts when debugging.
That was in fact an interesting feature request, and after some investigations I decided to proceed.
Now, when setting the new IgnoreTimeoutsWhenDebugging option to true, all timeouts will be ignored, but ONLY when there is a debugger attached (via Debugger.IsAttached).
All in all this will help when debugging issues locally, without nasty timeouts hitting simply because we are inspecting a variable after a breapoint hit, which is... the whole point of debugging, right?
Thanks @tvardero for the input!
See here for the original issue.
See here for the feature design issue.
Thanks to community user @vit-svoboda I changed the logic that gets the timestamp for a new entry, generated from a factory. Before, the timestamp was about the moment the factory ended, now it's when it started. No big change really, but it should help in a couple of edge cases with high concurrency.
See here for the original issue.
Nothing big really, as the perf were already great: just a bunch of extra tuning in a couple of edge cases, nothing big really.
I did not have time to update the docs related to all this new stuff, but I'll do it in the next few days, pinky promise.
For now, this massive release note should be good enough.
As always, with new features come new tests to make sure that all work as intended, now and in the future (regressions, am I right?). Now we're up to 1534 total running tests, including params combinations & friends.
I can always do more, but still: not bad.
- Update: package dependencies
StaleTags to factory execution contextCommunity user @ted-mundy noticed a tricky behavior when using Tagging with stale entries (see next point).
To solve it, I added a new StaleTags property to the factory execution context, so that now it's possible to access both the tags that are being passed to the GetOrSet() call and the existing tags of the stale entry in the cache (if any), like this:
cache.GetOrSet<string>(
"foo",
(ctx, token) => {
// THE TAGS PASSED BELOW ("tag1", "tag2" and "tag3")
ctx.Tags;
// THE TAGS OF THE STALE ENTRY ALREADY IN THE CACHE, IF ANY
ctx.StaleTags;
return "Combo";
},
tags: ["tag1", "tag2", "tag3"]
);
This can be useful even in other scenarios, like applying some custom logic about what to do based on the tags already in the cache.
Nice.
As mentioned above, community user @ted-mundy noticed a tricky behavior when using Tagging with stale entries.
Thanks to the addition of the new StaleTags property, this is now solved for good.
Thanks @ted-mundy !
See here for the original issue.
Community user @TheSpookyElectric noticed that, when working with the HybridCache adapter, the LocalCacheExpiration was not being handled correctly in all cases.
The mapping logic has been updated to account for that, and it now works as expected.
Thanks @TheSpookyElectric !
See here for the original issue.
WithRegisteredSerializer()Community user @Inok noticed something... strange.
The builder, when calling WithRegisteredSerializer() on it, was doing something else: acting on the distributed cache.
That was, well... dumb, that's just what it was: my bad.
Now this has been solved.
Thanks @Inok !
See here for the original issue.
InvalidOperationException when using AlwaysOffSampler with OTELCommunity user @DFSko noticed an InvalidOperationException being thrown when working with OTEL and using the AlwaysOffSampler: this had to do with setting the current Activity after certain operations, in conjunction with activities with a state not compatible for being set as the current one.
This has now been solved.
Thanks @DFSko !
See here for the original issue.
Community user @marcominerva discovered a wrong description for the WithDistributedCache() method on the builder: fixed.
Thanks @marcominerva !
See here for the original issue.
FusionCache reached 1500 tests:
<img width="774" height="151" alt="image" src="https://github.com/user-attachments/assets/bc2d5e87-ca32-49ff-a399-2e4969e4b80d" />
That's it, that's the tweet 🙂
- Update: package dependencies
Community user @posledam and others asked for the ability to access the cache key in the factory context, to be able to work with it while going to the database or similar, without creating a closure with the lambda.
So that's what I added, but there's a catch here: FusionCache provides automatic cache key manipulation with things like CacheKeyPrefix usually in conjunction with things like Named Caches, so it would be nice to access both the original one and the processed one.
Therefore I added both of them in the factory context, and it can be used like this:
cache.GetOrSet<string>(
"foo",
(ctx, token) => {
ctx.Key; // THE (PROCESSED) CACHE KEY
ctx.OriginalKey; // THE (ORIGINAL) CACHE KEY
}
);
See here for the original issue, and here for the design issue.
InternalStrings optionsFusionCache automatically handles a lot of things for us, and to do that it may need to manipulate some strings used internally like the cache key or the backplane channel name.
For example to use the CacheName to automatically separate data in a shared cache when used in conjunction with other FusionCache instances, or the set of special cache keys used with Tagging or the way wire format versioning is handled to automatically avoid errors when evolving the internal data structures.
In these cases some special characters are used as separators.
This is all good and well, but recently community user @stebet started working on a NATS version of the backplane (and that's awesome!) and he noticed that some of these special characters create issues on NATS, which has some reserved characters that have special meaning or cannot be used anyway.
Because of this I'm adding a new set of options specifically for changing the set of internal strings used by FusionCache, so that it's possible to work with systems like NATS and avoid issues.
So now we have a new InternalStrings option inside of FusionCacheOptions where we can set strings like:
TagCacheKeyPrefixClearRemoveTagDistributedCacheWireFormatSeparatorBackplaneWireFormatSeparatorIt can be used like this:
var options = new FusionCacheOptions()
{
// ...
InternalStrings = {
TagCacheKeyPrefix = "tag__",
ClearRemoveTag = "clear_remove"
// ...
}
};
But there's an issue here that I can already foresee: in the future I may need to add new internal strings, and anyone who had carefully set them to something "safe" for them will start having issues after updating to the new version with the new internal strings.
Therefore I also added a new method on the internal strings class, a method that I will keep updating in case new strings will be needed of course, and that simply set them to values that uses a commonly accepted safe set of characters, meaning only alphanumeric characters + some common separators.
It can be used like this:
options.InternalStrings.SetToSafeStrings();
or, if we want to customize the couple of special chars, like this:
options.InternalStrings.SetToSafeStrings(
separator: '-',
specialChar: '_'
);
In this way it will be possible to keep every little detail under control and always be future proof.
See here for the original issue.
FusionCacheEntryOptionsProviderCommunity user @gleb-osokin was looking for a way to have DefaultEntryOptions specific for cache keys, to avoid having only one global entry options and have a way to automatically use the right one based on some custom logic instead of having to specify them at every call site.
The design took some time and some back and forth since the default entry options existed since the beginning, and to get things in the right shape has been a particularly delicate effort.
But now we have a new FusionCacheEntryOptionsProvider abstract class which anyone can implement with their own custom logic, and that we can set in the FusionCacheOptions object that we pass to create a FusionCache instance.
Nothing else needs to change, and the per-key provider, if any, is now automatically considered and used.
Particular care has been put into allowing users to have their custom logic without having a ton of new allocations.
Here's the thing:
/// <summary>
/// A provider to get <see cref="FusionCacheEntryOptions"/> based on a key.
/// <br/><br/>
/// ⚠️ <strong>IMPORTANT:</strong> in your GetEntryOptions() implementation carefully set the canMutate out param to indicate if the returned object can be mutated or not.
/// </summary>
public abstract class FusionCacheEntryOptionsProvider
{
/// <summary>
/// Provide entry options based on a key, by either returning a new instance or a reference to an existing one (for improved performance).
/// <br/><br/>
/// ⚠️ <strong>IMPORTANT:</strong> carefully set the <paramref name="canMutate"/> out param to indicate if the returned object can be mutated or not.
/// </summary>
/// <param name="ctx">The context, containing supporting features.</param>
/// <param name="key">The cache key.</param>
/// <param name="canMutate">An out parameter that indicate if the returned object can be mutated.</param>
/// <returns>The entry options.</returns>
public abstract FusionCacheEntryOptions? GetEntryOptions(FusionCacheEntryOptionsProviderContext ctx, string key, out bool canMutate);
}
As we can see extra care has been put into the xml comments, to warn implementers about the fact that they have to pay attention to the canMutate param, which is fundamental to signal that the returned entry options can bu mutated or not (and FusionCache then will take care of the rest, eventually duplicating it if needed).
A new method has been also added to IFusionCache: historically we had the CreateEntryOptions(...), and now we also have the CreateEntryOptions(key, ...) variant to include the key in the logic.
Here is the original PR, and here the design issue.
Community user @permagne noticed that read-only methods (eg: TryGet and GetOrDefault) were not considering the SkipDistributedCacheRead entry option: this, in case of a cache miss, means that every call would go to the L2, slowing things down.
This has now been solved.
See here for the original issue.
I finally took some time to update all the tests to xUnit v3, which has been out for some time now.
On top of this I also added some more tests to cover some missing scenarios, getting the size of the test suite to:
Almost 1500, not bad.
And finally the docs, which I care a lot about.
I have updated some, like:
Clear(true) and Clear(false)Expire() worksSome of these came from always welcome questions by community members like @GeddesJ , @bebo-dot-dev , @martinkoslof and @jundayin : thanks!
- Update: package dependencies
Some time ago I started enabling multi-targeting on FusionCache: I didn't do that because I needed to special case some parts of the code, but just because I wanted to reduce the amount of explicit dependencies for certain TFMs after a request from the community.
But recently community user @nick-randal noticed in #416 some potential issues: long story short, from now on FusionCache will have explicit targeting only for currently supported TFMs (which today means no more .NET 3.1, .NET 6 or .NET 7) and for them it will have the minimum set of explicit dependencies.
But wait: does this mean that those older versions of .NET wil not be able to use FusionCache anymore?
Absolutely not: since FusionCache targets .NET Standard 2.0, this means that ANY version of .NET compatible with .NET Standard 2.0 (meaning: all versions) will still be able to use FusionCache, just without an explicit "support statement", since those versions are anyway not supported anymore, not even by Microsoft itself.
See here and here for the original issues.
FusionCache has been AOT compatible for a long time, which is already good.
I just need to make that more "official" by declaring it in the csproj, enabling analyzers, create a test console app and, in general, do everything that's needed. And that's what I did.
Thanks to community user @digital88 for pointing that out.
See here and here for the original issues.
Currently, given a FusionCache instance, it's only possible to know if there is a distributed cache level (L2) via the bool HasDistributedCache { get; } property, not which one it is.
Community user @angularsen asked to expose it in #443 .
Historically I've been hesitant to expose internals, but at this point I think I can let this one go.
So now there's a new IDistributedCache? DistributedCache { get; } property that expose the IDistributedCache instance being used, if any.
See here and here for the original issues.
[!WARNING] This is technically a breaking change, but since nobody has custom
IFusionCacheimplementations and I updated both (FusionCacheandNullFusionCache), I think this is fine.
Same as above, but for the backplane.
So now there's a new a new IFusionCacheBackplane? Backplane { get; } property that expose the IFusionCacheBackplane instance being used, if any.
See here and here for the original issues.
[!WARNING] This is technically a breaking change, but since nobody has custom
IFusionCacheimplementations and I updated both (FusionCacheandNullFusionCache), I think this is fine.
NullFusionCacheCommunity user @eskild-th noted it was not possible to specify to use a NullFusionCache implementation via DI.
And now it is.
See here and here for the original issues.
Clear(true)Since I added Clear() support in v2, it has become one of the favourite features by the community (including, of course, Tagging).
Recently community user @ctyar noted something seemingly strange, which I then clarified, so all was good.
But this sparked an optimization idea so, even though the implementation for Clear() has been highly optimized since day 1, now it is even more in cases when Raw Clear is possible (eg: L1 only, no shared).
This, in reality, translates to better Clear checks,which means better perf for any method call in the mentioned scenario (eg: GetOrSet, TryGet, etc), not just when calling Clear() itself: yeah 🥳
See here for the issue that sparked the idea for the optimization.
Community user @pil0t suggested to look into some backplane code, and proposed some changes, which I merged and then added some others on top of them. The result is that now the backplane should work better, in a more async way, anytime possible: this allows for even less thread blocking than before.
See here for the original issue.
Community user @gmij pointed out that there was not much use of the INFO logging level, and that most log entries were at the DEBUG level: that is a good thing to point out, so now all the "entry/exit points" are marked at INFO level. This means there's more differentiation between the different levels used, which is better to get more visibility into FusionCache internals but without immediately getting too much visibility.
On a different note, but still about logging, distributed cache errors related to internal FusionCache operations now log with a WARNING level instead of an ERROR level: this should avoid triggering some alarms in observability scenarios where that is configured.
See here and here for the original issues.
Community user @MarkCiliaVincenti asked in #134 (yup, quite some time ago 😅) to switch FusionCache internal locking mechanism to his own library, AsyncKeyedLock.
Now, I don't want to have a direct dependency to something external for something so core, but since v0.26.0 there's a new IFusionCacheMemoryLocker abstraction which allows the creation of 3rd party implementations, so I decided to give it a try and added support for it.
How good is it? How does it compare to the standard one included in FusionCache? It depends on your own scenario, so the best thing is to try it out, measure everything, and see for yourself.
See here for the original issue.
Community user @HannaHromenko noted that sometimes, in highly concurrent scenarios, a null reference exception was being thrown, who knows why.
Well damn, I knew why, and that is now fixed.
See here for the original issue.
It has been noted by @fabianmenges that, when using both jittering and fail-safe, something unexpected could happen: now this has been fixed.
See here for the original issue.
Community user @nlconor noted that when using AutoClone the serialization was being done lazily, and this fact may create problems when putting something in the the cache, keeping a reference to it, then change it. Now this has been fixed.
See here for the original issue.
- Update: package dependencies
- Update: package dependencies
🙋♂️ Updating to v2 ? Please read here. |
|---|
Now that v2 isfinally here and with full Tagging support, it's time to integrate all the things 🥳
The first 2 can be found below:
The first one on my list is Output Cache, and the nice thing about the way it has been designed in ASP.NET is that the only thing that is needed to make a custom version is an implementation of IOutputCacheStore.
And so I did, and thanks to native Tagging in FusionCache the whole implementation is a thing of beauty with just 1 line per method: behold.
Btw while I was working on this, community user @Fabman08 asked for the same thing, talk about good timing!
Anyway, why is all of this useful?
Because now, when using OutputCache, we'll not be limited by a simple memory cache anymore, and can instead have the power of all the features of FusionCache like fail-safe, L1+L2, backplane support and more: imagine having the performance of a memory cache (L1) but with the availability and database savings of a distributed cache (L2) including instant synchronization of the backplane.
If you ask me, it's awesome.
Ok so, how can we set it up?
Easy:
// FUSION CACHE
services.AddFusionCache();
// FUSION OUTPUT CACHE
services.AddFusionOutputCache();
// OUTPUT CACHE (STANDARD SETUP)
services.AddOutputCache(options =>
{
options.AddPolicy("Expire2", builder =>
builder.Expire(TimeSpan.FromSeconds(2))
);
options.AddPolicy("Expire5", builder =>
builder.Expire(TimeSpan.FromSeconds(5))
);
});
When using the normal OutputCache (with a memory-only cache store) we need to:
With the FusionCache-based version we just need 2 extra steps, before the common one:
One thing to note is that, even though it's possible to use the default FusionCache instance like in the example above, it's usually better to have a separate named cache with a specific configuration for OutputCache: this can be useful both to avoid cache key collisions (even though it is already quite hard to have them because of the standard key structure in OutputCache itself) and to have different L1/L2/backplane configurations.
How? Easy:
// FUSION CACHE (WITH CUSTOM NAME, L2, BACKPLANE, DEFAULT ENTRY OPTIONS)
services.AddFusionCache("MyOutputCache")
.WithDefaultEntryOptions(options =>
{
options.IsFailSafeEnabled = true;
})
.WithSerializer(new FusionCacheProtoBufNetSerializer())
.WithDistributedCache(new RedisCache(new RedisCacheOptions
{
Configuration = "..."
}))
.WithBackplane(new RedisBackplane(new RedisBackplaneOptions
{
Configuration = "..."
}));
// FUSION OUTPUT CACHE
services.AddFusionOutputCache(options =>
{
// WHICH NAMED CACHE TO USE
options.CacheName = "MyOutputCache";
});
// OUTPUT CACHE (STANDARD SETUP)
services.AddOutputCache(options =>
{
options.AddPolicy("Expire2", builder =>
builder.Expire(TimeSpan.FromSeconds(2))
);
options.AddPolicy("Expire5", builder =>
builder.Expire(TimeSpan.FromSeconds(5))
);
});
Another important aspect is to be able to use a different serializers.
Wait, but why a different serializer?
Frequently it's common to use text-based serialziers (eg: JSON-based) for our entities and objects in the cache, and that is totally fine.
But OutputCache deals with byte[] (containing the entire http response with headers, body, etc) and by using a text-based serializer we are not getting the best performance for our bucks.
So, my suggestion is to pick a natively binary serializer like protobuf-net, MessagePack or MemoryPack (the available ones can be found here): in this way the payload in L2 will be as small as possible, and performance will be top notch.
Awesome.
The other one is an interesting project by @VahidN called EFCoreSecondLevelCacheInterceptor, which proposes itself as a transparent 2nd level cache for EFCore.
The nice thing for this is that I did... nothing at all 😅
One community user @kooshan asked for it in their repo some time ago, more recently another user @bbehrens let me know about it and, before I was able to do anything, the maintainer worked on it, released the new v5 version with pluggable multi-provider support and... tada 🎉
If interested, I suggest using at least v5.1 since it's the first that depends on the final FusionCache v2 bits.
The backplane has always been async at its core, meaning the messages sent and received.
A couple of smaller parts though were not as async-aware as ideally wanted, and now this is fixed: both the initial subscription and the ending unsubscription are now available in a fully async variant.
Comunity user @ilioan noticed (thanks!) a small regression in FusionCache v2 related to a particular edge case: highly parallel initializations. In that case there was a missing check in a classic double-checked-lock, such that in some cases it resulted in a missing model registration. Now this has been fixed.
See here for the original issue.
Community user @sebbarg noticed (thanks!) that when filtering log messages for the Debug level, the output was not totally consistent: the general method was being logged (eg: calling RemoveAsync), and the L1 operation was being logged too, but the L2 operation was nowhere to be found.
The issue? L2 operations were using the Trace log level 🤦.
Anyway now this has been fixed, and log messages are more consistent.
See here for the original issue.
Sometimes it's nice to be able to visualize the internal flow of a system, even more so for such a complex beast as an hybrid cache like FusionCache.
So, diagrams!
<div align="center">
</div>
As with any new release I made the tests better, this time adding a couple of additional scenarios covered.
I also reorganized all the tests in a better way, by splitting the sync and async ones in separated files thanks to partial classes, so that they are now nicer to work with and easier to keep aligned.
I've added some more docs for the latest stuff, and fixed some typos, no big deal.
| This version references only .NET 8 core packages, so it can be used in scenarios where only LTS packages can be referenced. |
| 📣 LTS-ONLY RELEASE |
|---|
| This version references only .NET 8 core packages, so it can be used in scenarios where only LTS packages can be referenced. |
This version is exactly the same as v2.2.0, except for 2 things:
v8 core packages (LTS)v9 core packagesThis has been done to support users that cannot reference STS core packages.
See here for the original issue and more details, like, a lot more details.
| This version references only .NET 8 core packages, so it can be used in scenarios where only LTS packages can be referenced. |
| 📣 LTS-ONLY RELEASE |
|---|
| This version references only .NET 8 core packages, so it can be used in scenarios where only LTS packages can be referenced. |
This version is exactly the same as v2.1.0, except for 2 things:
v8 core packages (LTS)v9 core packagesThis has been done to support users that cannot reference STS core packages.
See here for the original issue and more details, like, a lot more details.
…longer return stale data. This can be seen as a breaking change, but at the same time for the vast majority of use cases it was "wrong" to begin with,…
[!IMPORTANT] This is a world's first!
FusionCache is the first production-ready implementation of Microsoft HybridCache: not just the first 3rd party implementation, which it is, but the very first implementation at all, including Microsoft's own implementation which is not out yet.
Read below for more.
🙋♂️ Updating to v2 ? Please read here. |
|---|
For me (Jody), this feels like a monumental personal achievement. The amount of work poured into it, the sheer size of the release, all the new features like Tagging, Clear(), Microsoft HybridCache support and everything else: I honestly couldn't be prouder of it.
I hope you will all like using it, as much as I liked creating it.
Ok, end of the personal note: let's get the features rolling!
FusionCache now has full support for tagging!
This means we can now associate one or more tags to any cache entry and, later on, simply call RemoveByTag("my-tag") to evict all the entries that have the "my-tag" associated to them.
And yes, it works with all the other features of FusionCache like L1+L2, backplane, fail-safe, soft timeouts, eager refresh, adaptive caching and everything else.
Honestly, the end result is a thing of beauty.
Here's an example:
cache.Set("risotto_milanese", 123, tags: ["food", "yellow"]);
cache.Set("kimchi", 123, tags: ["food", "red"]);
cache.Set("trippa", 123, tags: ["food", "red"]);
cache.Set("sunflowers", 123, tags: ["painting", "yellow"]);
// REMOVE ENTRIES WITH TAG "red"
cache.RemoveByTag("red");
// NOW ONLY "risotto_milanese" and "sunflowers" ARE IN THE CACHE
// REMOVE ENTRIES WITH TAG "food"
cache.RemoveByTag("food");
// NOW ONLY "sunflowers" IS IN THE CACHE
It's really that simple.
Well, using it is simple: the behind the scenes on how to make it work, to make it work well, in a scalable and flexible way including support for all the resiliency features of FusionCache (eg: fail-safe, auto-recovery, etc), that is a completely different story. The design is a particular one, and I suggest anyone to take a look at the docs to understand how it all works.
There are also a lot performance optimizations, plus a lot of big and small tweaks.
See here for the official docs. See here for the original issue.
Thanks to the new Tagging support, it is now also possible for FusionCache to support a proper Clear() method, something that the community has been asking for a long time.
And this, too, works with everything else like cache key prefix, backplane notifications, auto-recovery and so on.
Here's an example:
cache.Set("foo", 1);
cache.Set("bar", 2);
cache.Set("baz", 3);
// CLEAR
cache.Clear();
// NOW THE CACHE IS EMPTY
Easy peasy.
In reality there's more: an additional bool allowFailSafe param (with a default value of true) allows us to choose between a full Clear (eg: "remove all") and a soft Clear (eg: "expire all"): in the second case all entries will be logically deleted, but still available as a fallback in case fail-safe is needed, and there's full support for both at the same time.
There are also a lot performance optimizations, so everything is incredibly fast, even with a massive amount of data.
See here for the official docs. See here for the original issue.
With .NET 9 Microsoft introduced their own hybrid cache, called HybridCache.
This of course sparked a lot of questions about what I thought about it, and the future of FusionCache.
Now, the nice thing is that Microsoft introduced not just a default implementation (which as of this writing, Jan 2025, has not been released yet) but also a shared abstraction that anyone can implement.
So, as I already announced when I shared my thoughts about it, I wanted to allow FusionCache to be ALSO usable as a 3rd party HybridCache implementation.
To be clear: this does NOT mean that FusionCache is now based on the HybridCache implementation from Microsoft, but that is ALSO usable AS an implementation of the abstraction, via an adapter class.
Currently the HybridCache abstraction has been released, but the Microsoft implementation is not out yet: today, FusionCache becomes the world's first production-ready implementation of it.
So, how can we use it?
Easy, when setting up FusionCache in our Startup.cs file, we simply add .AsHybridCache():
services.AddFusionCache()
.AsHybridCache(); // MAGIC
Now, every time we'll ask for HybridCache via DI (taken as-is from the official docs):
public class SomeService(HybridCache cache)
{
private HybridCache _cache = cache;
public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
{
return await _cache.GetOrCreateAsync(
$"{name}-{id}", // Unique key to the cache entry
async cancel => await GetDataFromTheSourceAsync(name, id, cancel),
cancellationToken: token
);
}
public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
{
string someInfo = $"someinfo-{name}-{id}";
return someInfo;
}
}
we'll be using in reality FusionCache underneath acting as HybridCache, all transparently.
And this also means we'll have the power of FusionCache itself, including the resiliency of fail-safe, the speed of soft/hard timeouts and eager-refresh, the automatic synchronization of the backplane, the self-healing power of auto-recovery, the full observability thanks to native OpenTelemetry support and more.
Oh, and we'll still be able to get IFusionCache too all at the same time, so another SomeService2 in the same app, similarly as the above example, can do this:
public class SomeService2(IFusionCache cache)
{
private IFusionCache _cache = cache;
// ...
and the same FusionCache instance will be used for both, directly as well as via the HybridCache adapter.
Oh (x2), and we'll be even able to read and write from BOTH at the SAME time, fully protected from Cache Stampede!
Yup, this means that when doing hybridCache.GetOrCreateAsync("foo", ...) at the same time as fusionCache.GetOrSetAsync("foo", ...), they both will do only ONE database call, at all, among the 2 of them.
Oh (x3 😅), and since FusionCache supports both the sync and async programming model, this also means that Cache Stampede protection (and every other feature, of course) will work perfectly well even when calling at the same time:
hybridCache.GetOrCreateAsync("foo", ...) (async call from the HybridCache adapter)fusionCache.GetOrSet("foo", ...) (sync call from FusionCache directly)Damn, that's good.
Of course, since the API surface area is more limited (eg: HybridCacheEntryOptions VS FusionCacheEntryOptions) we can enable and configure all of this goodness only at startup and not on a per-call basis: but still, it is a lot of power to have available for when you need/want to depend on the Microsoft abstraction.
Actually, to be more precise: the features available in both HybridCacheEntryOptions and FusionCacheEntryOptions (although with different names) have been automatically mapped and will work flawlessly: an example is using HybridCacheEntryFlags.DisableLocalCacheRead in the HybridCacheEntryOptions which becomes SkipMemoryCacheRead in FusionCacheEntryOptions, all automatically.
Want more? Ok, here's something crazy.
The Microsoft implementation (now in preview) currently have some limitations, like:
IDistributedCache is not registered in the DI container HybridCache will not have an L2, but if it's registered it will be used, forcibly. This means that if another component registers an IDistributedCache service, we'll be forced to use it in HybridCache too, even if we don't want itNow these limitations are for the (current) HybridCache implementation, not for the abstraction: so can FusionCache go above and beyond those limits?
Yup 🎉
First: since the registration is the one for FusionCache, this means we have total control over what components to use (see the builder here), so we are not forced to use an L2 just because there's an IDistributedCache registered in the DI container or vice versa.
Second: thanks to the Named Caches feature of FusionCache, we can register more than one, and each of them can be exposed via the adapter.
But how can we access them separately in our code?
Easy, via Keyed Services!
Instead of registering it like this:
services.AddFusionCache()
.AsHybridCache();
and then request it via serviceProvider.GetRequiredService<HybridCache>() or via a param injection like this:
public class SomeService(HybridCache cache) {
...
}
we can register it like this:
services.AddFusionCache()
.AsKeyedHybridCache("Foo");
and then request it via serviceProvider.GetRequiredKeyedService<HybridCache>("Foo") or via a param injection like this:
public class SomeService([FromKeyedServices("Foo")] HybridCache cache) {
...
}
And is it possible to do both at the same time?
Of course, simply register one FusionCache with .AsHybridCache() and others with .AsKeyedHybridCache(...), that's it.
Boom!
See here for the official docs. See here for the issue.
| ❤️ Microsoft (and Marc) and OSS |
|---|
| To me, this is a wonderful example of what it may look like when Microsoft and the OSS community have a constructive dialog. First and foremost many thanks to @mgravell himself for the openness, the back and forth and the time spent reading my mega-comments. Read here for more. |
Thanks to a big effort by community user @stebet , serializers are now natively better and allocate less, thanks to some array pools/buffers magic.
Because of this, support for the external RecyclableMemoryStreamManager has been removed, since it's not necessary anymore.
Less dependencies here, too!
See here for the original PR.
AllowStaleOnReadOnly entry optionHistorically fail-safe has been used even with read-only methods like TryGet and GetOrDefault, where a "fail" cannot actually happen.
This sometimes created some confusion, and lead to people enabling fail-safe globally and sometimes getting back stale values even with read-only operations.
To allow for better and more granular control over this aspect, a new AllowStaleOnReadOnly entry option has been added, which controls the return of stale values in read-only operations.
[!IMPORTANT] By updating introducing this new option the existing behaviour of your app may change when updating to v2 if you had fail-safe enabled globally for example, meaning that read-only operations will no longer return stale data. This can be seen as a breaking change, but at the same time for the vast majority of use cases it was "wrong" to begin with, so I decided to take the opportunity of the major version bump to v2 to make this change.
Of course if you want to keep the old behaviour (eg: read stale on read-only operations) you can simply set the new option to true on the DefaultEntryOptions and go with it.
By taking an inspiration from the upcoming HybridCache from Microsoft (see above), new entry options have been added to precisely skip reading and/or writing for both the memory (L1) and the distributed (L2) levels.
Now we have 4 options with more granular control:
SkipMemoryCacheReadSkipMemoryCacheWriteSkipDistributedCacheReadSkipDistributedCacheWritePreviously we had 2 options:
SkipMemoryCacheSkipDistributedCacheNow these 2 old ones now act in this way:
true if both the read and the write options are set to true (eg: return SkipMemoryCacheRead && SkipMemoryCacheWrite)Even if they work, to avoid future confusion the 2 old ones have been marked as [Obsolete].
Of course the handy ext methods like SetSkipMemoryCache() still work.
Community user @waynebrantley (thanks!) made me think again about the difference between Remove() and Expire() and how to better handle the different expectations between the two.
Now the behaviour is clearer, and hopefully there will be less surprises down the road.
See here for the original issue.
It is now possible to include the tags of the new Tagging feature when doing observability.
There are 3 new options in FusionCacheOptions:
IncludeTagsInLogsIncludeTagsInTracesIncludeTagsInMetricsThey are pretty self-explanatory, but keep in mind that when in OTEL world we should avoid high-cardinality attributes (eg: attributes with a lot of different values) so, be careful.
Also, there are also new traces and meters for Tagging/Clear operations.
Finally, FusionCache now records more events and exceptions than before, when they happen, giving more insights to work on when doing detective work.
Community user @jarodriguez-itsoft noticed that sometimes the payload in the distributed cache was not as small as it could've been. Because of this the internal shape of the metadata class has been changed, to better reflect the common usage patterns and save memory whenever possible.
This set of changes made it possible to get a metadata-less scenario, which in a lot of cases will lead to smaller payloads in the distributed cache, less network usage and so on.
On top of this, some fields has been changed to a different type to allocate less and consume less cpu, while at the same time better support has been added for cross-nodes entry priority when scaling horizontally.
See here for the original issue.
ReThrowSerializationExceptions does not affect serialization, only deserializationCommunity user @angularsen (thanks!) had an issue with serialization, and long story short the ReThrowSerializationExceptions option can now be used to ignore only deserialization exceptions, not serialization ones (since basically an error while serializing means that something must be fixed).
See here for the original issue.
By taking an inspiration from the upcoming HybridCache from Microsoft (see above), FusionCache now handles immutable objects better when using Auto-Clone: if an object is found to be immutable, it will now skip the cloning part, to get even better perfs.
It has been noticed by community user @Coelho04 (thanks!) that fail-safe did not activate correctly when the factory failed with ctx.Fail("Oops") and the factory was running in the background (because of a soft timeout or eager refresh).
This is now fixed.
See here for the original issue.
[Obsolete] members has been marked as errorsAll the members previously marked as [Obsolete("Message")] are now marked as [Obsolete("Message", true)], meaning if you are still using them your project will not compile.
They have been obsolete for a long time now, and this should not be a problem for anyone (and, btw, the needed changes are minuscule).
New events have been added for the Tagging and Clear features.
InstanceIds (saves space in logs and traces)A minor change, but the auto-generated InstanceId for each FusionCache instance are now shorter, saving some space on logs/network.
Thanks to the new features, the HybridCache support and more, the tests just crossed the 1K mark (1.1K to be precise). While at it, I made some of them faster without the need to wait so long to test complex temporal behaviours (but, still, they'll take some time).
The docs have been updated with the new features, including Tagging, Clear and Microsoft HybridCache support.
Since this is a MAJOR version change (v1 -> v2) there have been multiple binary breaking changes, and a single compile-time one.
Having said that, unless someone somehow decided to re-implement FusionCache itself, a simple package update + full recompile should do the trick, since thanks to overloads and whatnot all the existing code should work as before (and, in case that is not the case, please let me know!).
Also, as said at the top, the wire format version has changed: read more here and here.
For the full v2 update guide, please read here.
Nothing published for this version
Nothing published for this version
Nothing published for this version
This is a small version, just to update some transitive packages with security vulnerabilities.
This is a small version, just to update some transitive packages with security vulnerabilities.
The affected transitive packages are:
System.Text.JsonMessagePackMicrosoft.Extensions.Caching.MemoryTo that to update Microsoft.Extensions.Caching.Memory, an update for System.Diagnostics.DiagnosticSource was also needed.
This is all.
PS: if you have some time, please read the Tagging proposal (eg: evict by tag + clear), which is planned for v2.0. This will be one of the biggest and most important features of FusionCache ever. Any help is welcome!
> Although when updating to a new version it's the norm to update all referenced packages at once, this time is even more important. Because of a smal
[!IMPORTANT] Although when updating to a new version it's the norm to update all referenced packages at once, this time is even more important. Because of a small change in the
IFusionCacheSerializerinterface, it is highly suggested to update all packages, including in transitive dependencies.
It is now possible to use RecyclableMemoryStreams with some of the supported serializers.
It's opt-in, meaning totally optional, and it's possible to use the default configuration or to specify one in the constructor, for maximum control and to fine-tune it however we want.
Thanks @viniciusvarzea for the suggestion!
See here for the original issue.
Community user @dotTrench noticed that when using OpenTelemetry, GET activities (TryGet, GetOrDefault, etc) were not including a useful bit of information: the hit/miss status.
While adding support for it via an extra tag, it was also noticed that it was not including another useful bit of information: the stale/fresh status.
Now this is solved, thanks to 2 new tags.
See here for the original issue.
Since v1.3.0 it's possible to trigger a factory fail without throwing an exception, so that fail-safe can kick in and do its thing.
But what happens if fail-safe is not enabled or if there's no stale value to fall back to?
Previously a plain Exception was being thrown, but that is hardly a best practice: now a more specific exception type has been created and will be thrown instead, namely FusionCacheFactoryException.
See here for the original issue.
Previously serializers did not support cancellation: now this is supported, via the standard CancellationTokens.
Thanks @b-c-lucas for noticing it!
See here for the original issue.
Community user @MarkCiliaVincenti contributed with a PR that improved the performance of FusionCacheProvider, used with Named Caches, thanks to the use of FrozenDictionary.
See here for the original PR.
Size of an entry loaded in L1 from L2 (docs)Community user @Amberg noticed that when the MemoryCache (L1) passed to FusionCache had a SizeLimit configured, and an entry wasbeing saved with a Size specified, that was not used when automatically getting the same entry from another node via the distributed cache, causing an issue.
Now this is solved, in 2 different scenarios:
See here for the original issue.
As always some tests have been added for each new feature. On top of that though, the testes have been changed to make them even more resilient to microscopic differences between different runtimes, OSs, etc: most of the problems were related to this almost unknown behaviour. This helped make the entire test suite even more stable and with a predictable outcome, both locally and on GitHub actions.
Overall, FusionCache currently has around 750 tests, including combinatorial params.
See here for some juicy details.
Updated some docs with the latest new things.
Communicty user @dependabot (😅) noticed CVE-2024-30105 and promptly bumped the referenced version of the System.Text.Json package.
In general is never a good idea to mutate data retrieved from the cache: it should always be considered immutable/readonly. To see why, read more in the docs.
Not all the scenarios where mutating a piece of data we got from the cache are necessarily wrong though, as users may have a particular use case where that may be needed, and ideally they should be abe to do that in an easy (and optimized!) way, by following the tried and true "it just works" mindset.
With Auto-Clone this is now possible.
A couple of details:
EnableAutoClone option)Thanks to community users @JarrodOsborne and @kzkzg !
See here for the original issue.
Currently the way to activate fail-safe is for a factory to throw an exception.
This makes sense, since the whole point of fail-safe is to protect us when an error occurs while executing a factory.
But there may be other ways to do it, for example by using a variation of the Result Pattern or similar approaches, in which throwing an exception is not necessary.
This is now possible thanks to the new Fail(...) method on the FusionCacheFactoryExecutionContext<TValue> type, which we can access when executing a factory.
A quick example:
var productResult = await cache.GetOrSetAsync<Result<Product>>(
$"product:{id}",
async (ctx, ct) =>
{
var productResult = GetProductFromDb(id);
if (productResult.IsSuccess == false)
{
return ctx.Fail(productResult.Error);
}
return productResult;
},
opt => opt.SetDuration(duration).SetFailSafe(true)
);
Thanks to community user @chrisbbe that noticed it!
See here for the original issue.
Previously it was not possible to use adaptive caching when an error occurred during a factory execution. This was usually not a big issue, but it left a particular edge case not fully uported: selectively enabling/disabling fail-safe on errors. Now this is possible, in the usual unified way.
Thanks to community user @cmeyertons for spotting it, and for creating the PR that solved it.
See here for the original issue.
Thanks to a note by community user @thompson-tomo FusionCache now multi-targets different .NET vesions. This was not needed per-se, but by doing it FusionCache can now have less dependencies for some TFMs.
See here for the original issue.
Community user @0xced contributed with a PR that improved the performance of FusionCacheProvider, used with Named Caches.
See here for the original PR.
Communicty user @dependabot (😅) noticed CVE-2024-30105 and promptly bumped the referenced version of the System.Text.Json package.
Note that this is only related to the package ZiggyCreatures.FusionCache.Serialization.SystemTextJson.
Some tests have been added for each new feature, and overall better snapshot tests.
Updated some docs with the latest new things.
Since .NET 8 we now have native support for multiple services of the same type, identified by different names, thanks to the addition of so called key
Since .NET 8 we now have native support for multiple services of the same type, identified by different names, thanks to the addition of so called keyed services.
The idea is basically that we can now register services not only by type but also by specifying the name, like this:
services.AddKeyedSingleton<MyService>("foo");
services.AddKeyedSingleton<MyService>("bar");
and later is possible to resolve it by both the type and a name.
Another way is to simply mark a constructor parameter or web action with the [FromKeyedServices] attribute, like this:
app.MapGet("/foo", ([FromKeyedServices("foo")] MyService myService) => myService.Whatever(123));
app.MapGet("/bar", ([FromKeyedServices("bar")] MyService myService) => myService.Whatever(123));
From now on, when registering a named cache, we can simply add AsKeyedServiceByCacheName() like this:
services.AddFusionCache("MyCache")
.AsKeyedServiceByCacheName();
and later we'll be able to have the named cache both as usual:
app.MapGet("/foo", (IFusionCacheProvider cacheProvider) => {
var cache = cacheProvider.GetCache("MyCache");
cache.Set("key", 123);
});
and as a keyed service, like this:
app.MapGet("/foo", ([FromKeyedServices("MyCache")] IFusionCache cache) => {
cache.Set("key", 123);
});
We can even use AsKeyedService(object? serviceKey) and specify a custom service key like for any other keyed service in .NET.
On top of being able to register FusionCache as a keyed service, we can even consume keyed services as FusionCache components, like memory cache, distributed cache, serializer, backplane, etc.
For more read at the official docs.
See here for the original issue.
PreferSyncSerialization optionIt has been observed that in some situations async serialization and deserialization can be slower than the sync counterpart: this has nothing to do with FusionCache itself, but how serialization works in general.
So I added a new option called PreferSyncSerialization (default: false, fully backward compatible), that can allow the sync version to be preferred.
See here for the original issue.
Community user @imperugo noticed that when using the backplane with OpenTelemetry traces enabled, all the spans for the notifications incoming via the backplane were put under one single parent span, basically creating a single mega-span "containing" all the others.
Ideally, each span for each notification should be on their own, and now this is the case.
Also while I was at it I noticed another couple of things that, if added to the traces, could make the developer experience better. In detail:
So yeah, I took this opportunity to make the overall experience better.
Finally, since backplane notifications can create a lot of background noise inside observability tools, I changed the default so that, even when there's a backplane setup, traces for backplane notifications are not enabled: to change this simply enable it at setup time.
See here for the original issue.
ChaosMemoryCacheAmong all the chaos-related components already available, one to work with IMemoryCache was missing: not anymore.
Some more tests have been added, including better cross-platform snapshot tests.
Updated some docs with the latest new things.
Since .NET 8 we now have native support for multiple services of the same type, identified by different names, thanks to the addition of so called key
Since .NET 8 we now have native support for multiple services of the same type, identified by different names, thanks to the addition of so called keyed services.
The idea is basically that we can now register services not only by type but also by specifying the name, like this:
services.AddKeyedSingleton<MyService>("foo");
services.AddKeyedSingleton<MyService>("bar");
and later is possible to resolve it by both the type and a name.
Another way is to simply mark a constructor parameter or web action with the [FromKeyedServices] attribute, like this:
app.MapGet("/foo", ([FromKeyedServices("foo")] MyService myService) => myService.Whatever(123));
app.MapGet("/bar", ([FromKeyedServices("bar")] MyService myService) => myService.Whatever(123));
From now on, when registering a named cache, we can simply add AsKeyedService() like this:
services.AddFusionCache("MyCache")
.AsKeyedService();
and later we'll be able to have the named cache with something like this:
app.MapGet("/foo", ([FromKeyedServices("MyCache")] IFusionCache cache) => {
cache.Set("key", 123);
});
Of course the named cache provider way is still available, like this:
app.MapGet("/foo", (IFusionCacheProvider cacheProvider) => {
var cache = cacheProvider.GetCache("foo");
cache.Set("key", 123);
});
See here for the original issue.
PreferSyncSerialization optionIt has been observed that in some situations async serialization and deserialization can be slower than the sync counterpart: this has nothing to do with FusionCache itself, but how serialization works in general.
So I added a new option called PreferSyncSerialization (default: false, fully backward compatible), that can allow the sync version to be preferred.
See here for the original issue.
ChaosMemoryCacheAmong all the chaos-related components already available, one to work with IMemoryCache was missing: not anymore.
Some more tests have been added.
Updated some docs with the latest new things.
The theme for this release is some bug fixes, general quality of life improvements and some minor perf optimizations.
The theme for this release is some bug fixes, general quality of life improvements and some minor perf optimizations.
OnMiss eventsCommunity user @ConMur noticed that sometimes, in a couple of code paths related to distributed cache operations, FusionCache was missing some OnMiss events (no pun intended): now this has been fixed.
See here for the original issue.
FailSafeMaxDuration handlingUser @F2 and user @sabbadino both noticed that fail-safe max duration was not being respected all the times, particularly when multiple fail-safe activations actually occurred in sequence there was in fact the risk of extending the physical duration of the cache more than what should've been correct. This has been fixed (while also introducing some nice memory and cpu savings!).
See here and here for the original issues.
While doing some extensive testing community user @martindisch discovered a rare case of deadlock that was happening only when all of these conditions were met simultaneously:
GetOrSet[Async] while passing a CancellationTokenThis issue kicked off an experimentation about a reworking of FusionCache internals regarding the general theme of cancellations of background factory executions in general (eager refresh, background factory completion with soft/hard timeouts, etc): I am happy to say that now the deadlock is gone for good. To do that well I slightly changed the behaviour of FusionCache regarding background factory executions: now they cannot be cancelled anymore by cancelling the original request that generated them, since it doesn't make that much sense to begin with, since a cancellation is used to cancel the current operation, but a background execution (particularly with eager refresh) is basically a side effect, which does have a life of its own, so it doesn't make a lot of sense to cancel that, too.
All in all, there should be realistically no discernible externally observable difference in behaviour (and no more deadlocks!).
Finally, I've added some tests to detect these scenario to avoid future regressions.
See here for the original issue.
AutoRecoveryDelay default valueThe default value for AutoRecoveryDelay has been changed from 2s to 5s, to better align with the standard reconnect timing of StackExchange.Redis, which is the most commonly used implementation for the distributed cache and the backplane.
The idea is about "sensible defaults" and the overarching theme of "it just works": if the default distributed cache and backplane are Redis, let's just make sure that the defualt experience is better aligned with that (and also, when bad things happen in production, automatically recovering from it with a slightly longer delay is, pragmatically, really not a big deal).
Thanks to @SimonCropp the code has been cleaned up a little bit here, updated to the latest C# features there, plus some other minor tweaks. Thanks Simon!
In this release I've been able to squeeze in some minor but nice memory/cpu optimizations.
I added some more tests to have a higher code coverage.
Updated some docs with the latest new things.
Let's see what this release includes.
Yes, it finally happened.
Let's see what this release includes.
FusionCache always tried to be as optimized as possible, but sometimes useful new features took some precedence over micro-optimizing this or that.
Now that all the major features (and then some) are there, it was time to do a deep dive and optimize a cpu cycle here, remove an allocation there and tweak some hot path to achieve the best use of resources.
So here's a non-comprehensive list of nice performance improvements in this release:
Oh, and thanks to community member @neon-sunset for the issue highlighting some shortcomings, that now have been solved!
See here for the issue.
When executing an Eager Refresh, the initial check for an updated cache entry on the distributed cache is now totally non-blocking, for even better performance.
IgnoreIncomingBackplaneNotifications option (docs)FusionCache always allowed to optionally skip sending backplane notifications granularly, for each operation (or globally thanks to DefaultEntryOptions): it was not possible though to ignore receiving them.
Now we may be thinking "why would I want to use a backplane, but not receive its notifications?" and the answer to that can be found in the feature request made by community member @celluj34 .
See here for the issue.
This is linked to the evolution of nullable reference types, nullables with generics and the related static analysis with each new version of c# and its compiler.
Along the years I tried to adjust the annotations to better handle generic types + nullables with each new version, because what the compiler allowed me to do and was able to infer changed at every release (the first version had problems with generics without where T : class/struct constraints, for example).
I've now updated them to reflect the latest behaviour, so that it's now more strict in the generic signatures, mostly for GetOrSet<T> and GetOrSetAsync<T>: in previous versions the return type was always nullable, so when calling GetOrSet<Person> we would have a return value of Person? (nullable) even if the call was not GetOrSet<Person?>.
Now this is better.
Thanks for community member @angularsen for highlighting this.
See here for the issue.
FusionCacheEntryOptions.Size to be nullable (docs)The type of the Size option in the FusionCacheEntryOptions type has been historically long (default: 1): the underlying Size option in the MemoryCacheEntryOption type is instead long? (default: null).
So, to better align them, now the types and default values are the same.
Not technically a problem per se, but with the release of the new and improved auto-recovery in v0.24.0, I had to add a little bit of reflection usage to support complex scenario of recovering some of the transient distributed errors.
Now, the small amount of code that was using reflection is gone, and this in turn means:
See here for the issue.
With v0.26.0 native support for Open Telemetry has been added to FusionCache.
Now community members @JoeShook noticed that the eviction reason was missing from the Eviction counter, which could be in fact useful.
Now it has been added, thanks Joe!
See here for the PR.
Community member @rafalzabrowarny noticed that FusionCache was adding a tag to the metrics, specifically one with the cache instance id: now, since it's a random value generated for every FusionCache instance, it will have a high cardinality and that is usually problematic with APM platforms and tools.
Now it's gone, thanks Rafał!
See here for the issue.
CacheNames optionsWith the introduction of the builder in v0.20 FusionCache got a nice way to configure the various options and components, in a very flexible way.
In one particular scenario though, it was possible to specify something incoherent: a single instance with multiple CacheNames, specified in different ways by using both the high level AddFusionCache("MyCache") and the WithOptions(...) methods.
A couple of examples:
services.AddFusionCache("foo")
.WithOptions(options => {
options.CacheName = "bar";
});
or, more subtly:
services.AddFusionCache()
.WithOptions(options => {
options.CacheName = "bar";
});
Now FusionCache correctly detects this scenario and throws an exception as soon as possible, helping the developer by showing the golden path to follow and how to do to solve it.
Thanks @albx for spotting this!
See here for the issue.
Again with the builder, when using the TryWithAutoSetup() method in the builder it now also try to check for registered memory lockers by calling TryWithMemoryLocker(), automatically.
I added some more tests to have a higher code coverage, and made the snapshot tests better.
More detailed log messages in some areas where they could've been better (mostly related to the backplane).
Updated some docs with the latest new things.
> Please try this preview2 release and let me know if you find any issue, so the v1.0 can be as good as possible: from now until v1.0 is out I will no
[!IMPORTANT]
Yep, it's almostv1.0time!Please try this
preview2release and let me know if you find any issue, so thev1.0can be as good as possible: from now untilv1.0is out I will no longer consider requests for new features.Thanks 🙏
FusionCache always tried to be as optimized as possible, but sometimes useful new features took some precedence over micro-optimizing this or that.
Now that all the major features (and then some) are there, it was time to do a deep dive and optimize a cpu cycle here, remove an allocation there and tweak some hot path to achieve the best use of resources.
So here's a non-comprehensive list of nice performance improvements in this release:
Oh, and thanks to community member @neon-sunset for the issue highlighting some shortcomings, that now have been solved!
See here for the issue.
When executing an Eager Refresh, the initial check for an updated cache entry on the distributed cache is now totally non-blocking, for even better performance.
IgnoreIncomingBackplaneNotifications option (docs)FusionCache always allowed to optionally skip sending backplane notifications granularly, for each operation (or globally thanks to DefaultEntryOptions): it was not possible though to ignore receiving them.
Now we may be thinking "why would I want to use a backplane, but not receive its notifications?" and the answer to that can be found in the feature request made by community member @celluj34 .
See here for the issue.
This is linked to the evolution of nullable reference types, nullables with generics and the related static analysis with each new version of c# and its compiler.
Along the years I tried to adjust the annotations to better handle generic types + nullables with each new version, because what the compiler allowed me to do and was able to infer changed at every release (the first version had problems with generics without where T : class/struct constraints, for example).
I've now updated them to reflect the latest behaviour, so that it's now more strict in the generic signatures, mostly for GetOrSet<T> and GetOrSetAsync<T>: in previous versions the return type was always nullable, so when calling GetOrSet<Person> we would have a return value of Person? (nullable) even if the call was not GetOrSet<Person?>.
Now this is better.
Thanks for community member @angularsen for highlighting this.
See here for the issue.
FusionCacheEntryOptions.Size to be nullable (docs)The type of the Size option in the FusionCacheEntryOptions type has been historically long (default: 1): the underlying Size option in the MemoryCacheEntryOption type is instead long? (default: null).
So, to better align them, now the types and default values are the same.
I added some more tests to have a higher code coverage, and made the snapshot tests better.
preview1)Not technically a problem per se, but with the release of the new and improved auto-recovery in v0.24.0, I had to add a little bit of reflection usage to support complex scenario of recovering some of the transient distributed errors.
Now, the small amount of code that was using reflection is gone, and this in turn means:
See here for the issue.
With v0.26.0 native support for Open Telemetry has been added to FusionCache.
Now community members @JoeShook noticed that the eviction reason was missing from the Eviction counter, which could be in fact useful.
Now it has been added, thanks Joe!
See here for the PR.
Community member @rafalzabrowarny noticed that FusionCache was adding a tag to the metrics, specifically one with the cache instance id: now, since it's a random value generated for every FusionCache instance, it will have a high cardinality and that is usually problematic with APM platforms and tools.
Now it's gone, thanks Rafał!
See here for the issue.
CacheNames optionsWith the introduction of the builder in v0.20 FusionCache got a nice way to configure the various options and components, in a very flexible way.
In one particular scenario though, it was possible to specify something incoherent: a single instance with multiple CacheNames, specified in different ways by using both the high level AddFusionCache("MyCache") and the WithOptions(...) methods.
A couple of examples:
services.AddFusionCache("foo")
.WithOptions(options => {
options.CacheName = "bar";
});
or, more subtly:
services.AddFusionCache()
.WithOptions(options => {
options.CacheName = "bar";
});
Now FusionCache correctly detects this scenario and throws an exception as soon as possible, helping the developer by showing the golden path to follow and how to do to solve it.
Thanks @albx for spotting this!
See here for the issue.
Again with the builder, when using the TryWithAutoSetup() method in the builder it now also try to check for registered memory lockers by calling TryWithMemoryLocker(), automatically.
More detailed log messages in some areas where they could've been better (mostly related to the backplane).
Updated some docs with the latest new things.
> Please try this preview1 release and let me know if you find any issue, so the v1.0 can be as good as possible: from now until v1.0 is out I will no
[!IMPORTANT]
Yep, it's almostv1.0time!Please try this
preview1release and let me know if you find any issue, so thev1.0can be as good as possible: from now untilv1.0is out I will no longer consider requests for new features.Thanks 🙏
Not technically a problem per se, but with the release of the new and improved auto-recovery in v0.24.0, I had to add a little bit of reflection usage to support complex scenario of recovering some of the transient distributed errors.
Now, the small amount of code that was using reflection is gone, and this in turn means:
See here for the issue.
With v0.26.0 native support for Open Telemetry has been added to FusionCache.
Now community members @JoeShook noticed that the eviction reason was missing from the Eviction counter, which could be in fact useful.
Now it has been added, thanks Joe!
See here for the PR.
Community member @rafalzabrowarny noticed that FusionCache was adding a tag to the metrics, specifically one with the cache instance id: now, since it's a random value generated for every FusionCache instance, it will have a high cardinality and that is usually problematic with APM platforms and tools.
Now it's gone, thanks Rafał!
See here for the issue.
CacheNames optionsWith the introduction of the builder in v0.20 FusionCache got a nice way to configure the various options and components, in a very flexible way.
In one particular scenario though, it was possible to specify something incoherent: a single instance with multiple CacheNames, specified in different ways by using both the high level AddFusionCache("MyCache") and the WithOptions(...) methods.
A couple of examples:
services.AddFusionCache("foo")
.WithOptions(options => {
options.CacheName = "bar";
});
or, more subtly:
services.AddFusionCache()
.WithOptions(options => {
options.CacheName = "bar";
});
Now FusionCache correctly detects this scenario and throws an exception as soon as possible, helping the developer by showing the golden path to follow and how to do to solve it.
Thanks @albx for spotting this!
See here for the issue.
Again with the builder, when using the TryWithAutoSetup() method in the builder it now also try to check for registered memory lockers by calling TryWithMemoryLocker(), automatically.
More detailed log messages in some areas where they could've been better (mostly related to the backplane).
Updated some docs with the latest new things.
> This version supersede v0.25.0 (now deprecated) because of a small breaking change: although it technically is a breaking change, it is about the ne…
[!IMPORTANT]
This version supersedev0.25.0(now deprecated) because of a small breaking change: although it technically is a breaking change, it is about the newIFusionCacheMemoryLockerintroduced just a week ago, so unless you are already implementing your own custom memory locker it will not be a problem.Apart from this,
v0.26.0is basically the same asv0.25.0, so please update tov0.26.0as soon as possible so you'll be ready for the bigv1.0that will be released very soon.
FusionCache now natively supports full observability, thanks to the great native support of OpenTelemetry in .NET via the core Activity and Meter classes without any extra dependency to produce them.
In general, the 3 main signals in the observability world are traces, metrics and logs.
FusionCache always supported logging, and even in a pretty advanced and customizable way.
Now the two remaining pieces are finally here: traces and metrics.
It is possible to opt-in to generate traces and metrics for both:
GetOrSet/Set/Remove operations, Hit/Miss events, etcThere's also a new package specific for OpenTelemetry that adds native support to instrument our applications, with FusionCache specific options ready to use, like including low-level signals or not.
It is then possible to simply plug one of the existing OpenTelemetry-compatible collectors for systems like Jaeger, Prometheus or Honeycomb and voilà, there we have full observability of our FusionCache instances.
Here's an example of how to set it up without dependency injection:
// SETUP TRACES
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
.Build();
// SETUP METRICS
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
.Build();
or, via dependency injection:
services.AddOpenTelemetry()
// SETUP TRACES
.WithTracing(tracing => tracing
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
)
// SETUP METRICS
.WithMetrics(metrics => metrics
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
);
The end result of all of this, when viewed for example in Honeycomb, is something like this:
Quite nice, uh 😏 ?
Oh, and I can't thank @martinjt enough for the support!
See here for the issue.
FusionCache always protected us from the Cache Stampede problem, but the internals of the memory locking mechanism have always been private.
Now no more, and thanks to the new IFusionCacheMemoryLocker interface the community may come up with different designs and implementations.
The builder has also been extended with support for configuring different memory lockers thanks to new methods like WithRegisteredMemoryLocker, WithMemoryLocker(locker), WithStandardMemoryLocker() and more.
See here for the issue.
NOTE: this version contains a small breaking change regarding the params in the methods of IFusionCacheMemoryLocker (swapped the position of key and operationId, to be 100% consistent with the rest of the codebase. As explained in the note at the top it is something that realistically will not change anything, but it's good to know.
SkipDistributedCacheReadWhenStale bugThanks to community member @angularsen I fixed a small bug related to SkipDistributedCacheReadWhenStale not working as expected during get-only operations (TryGet, GetOrDefault).
See here for the issue.
Minor, but still: FusionCache now better cleans up processed auto-recovery items.
Updated some docs and added some new ones (Observability, etc).
> This version has been superseded by v0.26.0 because of a small breaking change: although it technically is a breaking change, it is about the new IF…
[!IMPORTANT]
This version has been superseded byv0.26.0because of a small breaking change: although it technically is a breaking change, it is about the newIFusionCacheMemoryLockerintroduced just a week ago, so unless you are already implementing your own custom memory locker it will not be a problem.Apart from this,
v0.26.0is basically the same asv0.25.0, so please update tov0.26.0as soon as possible so you'll be ready for the bigv1.0that will be released very soon.
FusionCache now natively supports full observability, thanks to the great native support of OpenTelemetry in .NET via the core Activity and Meter classes without any extra dependency to produce them.
In general, the 3 main signals in the observability world are traces, metrics and logs.
FusionCache always supported logging, and even in a pretty advanced and customizable way.
Now the two remaining pieces are finally here: traces and metrics.
It is possible to opt-in to generate traces and metrics for both:
GetOrSet/Set/Remove operations, Hit/Miss events, etcThere's also a new package specific for OpenTelemetry that adds native support to instrument our applications, with FusionCache specific options ready to use, like including low-level signals or not.
It is then possible to simply plug one of the existing OpenTelemetry-compatible collectors for systems like Jaeger, Prometheus or Honeycomb and voilà, there we have full observability of our FusionCache instances.
Here's an example of how to set it up without dependency injection:
// SETUP TRACES
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
.Build();
// SETUP METRICS
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
.Build();
or, via dependency injection:
services.AddOpenTelemetry()
// SETUP TRACES
.WithTracing(tracing => tracing
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
)
// SETUP METRICS
.WithMetrics(metrics => metrics
.AddFusionCacheInstrumentation()
.AddConsoleExporter()
);
The end result of all of this, when viewed for example in Honeycomb, is something like this:
Quite nice, uh 😏 ?
Oh, and I can't thank @martinjt enough for the support!
See here for the issue.
FusionCache always protected us from the Cache Stampede problem, but the internals of the memory locking mechanism have always been private.
Now no more, and thanks to the new IFusionCacheMemoryLocker interface the community may come up with different designs and implementations.
The builder has also been extended with support for configuring different memory lockers thanks to new methods like WithRegisteredMemoryLocker, WithMemoryLocker(locker), WithStandardMemoryLocker() and more.
See here for the issue.
SkipDistributedCacheReadWhenStale bugThanks to community member @angularsen I fixed a small bug related to SkipDistributedCacheReadWhenStale not working as expected during get-only operations (TryGet, GetOrDefault).
See here for the issue.
Minor, but still: FusionCache now better cleans up processed auto-recovery items.
Updated some docs and added some new ones (Observability, etc).
Nothing published for this version
Please note that all the existing options named BackplaneAutoRecoveryXyz are now named simply AutoRecoveryXyz: this is not a breaking change though, s…
If you are updating from a previous version, please read here.
The old Backplane Auto-Recovery is now, simply, Auto-Recovery!
It shines above the other features as a way to automatically handle and resolve transient errors with timed retries and other techniques, to do the best it can to avoid leaving your cache in a dire situation, no matter what.
Lately I proceeded with an almost complete rewrite of the internals of the entire distributed part, meaning both the distributed cache and the backplane, and in particular the auto-recovery feature to make it all even better..
This is the culmination of many months of research, experimentation, development, testing, benchmarking and in general a lot of work.
The new Auto-Recovery now supports both the distributed cache and the backplane, either individually or together.
Now it is also active, meaning it handles retries automatically instead of waiting for an external signal to "wake up".
Some of these improvements include:
Every edge case I thought of and all the others reported to me by the community are handled, all automatically.
You can read some of them at the dedicated docs page.
Please note that all the existing options named BackplaneAutoRecoveryXyz are now named simply AutoRecoveryXyz: this is not a breaking change though, since the old ones are still present but marked with the useful [Obsolete] attribute. Simply update to the latest version, recompile, look for some warnings and do the appropriate changes, if any.
In general it is quite complicated to understand what is going on in a distributed system.
When using FusionCache with the distributed cache and the backplane, a lot of stuff is going on at any given time: add to that intermittent transient errors and, even if we can be confident auto-recovery will handle it all automatically, clearly seeing the whole picture can become a daunting task.
It would be very useful to have something that let us clearly see it all in action, something that would let us configure different components, tweak some options, enable this, disable that and let us simulate a realistic workload to see the results.
Luckily there is, and is called Simulator.
This version introduces a better way to handle incoming backplane messages: long story short, it will now take less time for a change to be propagated to all the other nodes, and to be reflected into their local memory cache (only if necessary, to save resources).
Eviction event now pass the cache value (docs)Thanks to a request by community member @giulianob the Eviction event in the memory cache has been made more powerful, and is now passing the cache value being evicted.
This can be useful for example to dispose a value being evicted from the cache, or more.
See here for more.
FusionCache now has 3 new custom exception types that are used to generalize errors of 3 main types: distributed cache errors, serialization errors and backplane errors.
In this way it will be easier to catch exception "groups" in our code instead of special-case it to work with Redis, CosmosDB, etc.
In case the old behaviour is needed for some reason, we can simply set the ReThrowOriginalExceptions options to true.
Timestamps are now more precise, and are used more inside the various heuristics used to handle conflicts and more.
ReThrowBackplaneExceptions optionIt is now possible to more granularly specify if we want to re-throw exceptions happened in the backplane code.
To allow this though we need to disable background execution of the backplane (via the AllowBackgroundBackplaneOperations option), otherwise it would be physically impossible to re-throw them.
Logging messages are now even better, with more useful information.
One that shines in particular and that is fundamental in debugging distributed issues is the inclusion of the InstanceId on top of the CacheName: with this we can better identify who sent messages to who without any doubt.
ConnectionMultiplexerFactory in RedisBackplaneIt is now possible to directly pass an instance of IConnectionMultiplexer to waste less resources, thanks to a PR by the community user @JeffreyM .
Thanks Jeffrey!
NullFusionCache now correctly handles CreateEntryOptionsThanks to a bug report by community member @kelko , a small issue has been fixed with the standard NullFusionCache implementation.
See here for more.
AbstractChaosComponentHistorically all the chaos-related components (eg: ChaosBackplane, ChaosDistributedCache, etc) all re-implement the same core properties and methods to control throws probability, random delays and so on.
Now that these components exist for some time and they are working well, they needed a little refactoring.
So a new AbstractChaosComponent has been created acting as a base class for all chaos-related components, so that they now all inherit from it to result in less code and better evolvability.
See here for more.
Chaos components now supports cancellation via the standard use of CancellationTokens.
The tests have been reorganized, better splitted into different files, they now have a unique abstract base class with some common useful stuff and most of them now have logging enabled, just in case.
Finally I've updated a lot of the existing docs and added some new ones, like for the brand new AutoRecovery feature, for the Simulator and more.
The Backplane is a powerful component in FusionCache and is already a pretty good feature that works really well.
The Backplane is a powerful component in FusionCache and is already a pretty good feature that works really well.
On top of the standard backplane features, auto-recovery shines above the others as a way to automatically handle transient errors with timed retries and other techniques, to do the best it can to avoid leaving your cache in a dire situation, no matter what.
In the last couple of months I proceeded with an almost complete rewrite of the internals of the backplane and in particular the auto-recovery feature, to make it work even better.
Some of these improvements include:
BackplaneAutoRecoveryDelay option (BackplaneAutoRecoveryReconnectDelay is now marked as obsolete)ReThrowBackplaneExceptions entry option, to have even more control of backplane errorsEnableDistributedExpireOnBackplaneAutoRecovery as obsolete, since now everything is fully automaticNow every edge case I thought of and all the others reported to me by the community are handled, all automatically.
Some examples:
And what is needed to handle all of this? Nothing: as always, FusionCache tries to be helpful without any extra care on your side.
Eviction event now pass the cache value (docs)Thanks to a request by community member @giulianob the Eviction event in the memory cache has been made more powerful, and is now passing the cache value being evicted.
This can be useful for example to dispose a value being evicted from the cache, or more.
See here for more.
NullFusionCache now correctly handles CreateEntryOptionsThaks to a bug report by community member @kelko , a small issue has been fixed with the standard NullFusionCache implementation.
See here for more.
AbstractChaosComponentHistorically all the chaos-related components (eg: ChaosBackplane, ChaosDistributedCache, etc) all re-implement the same core properties and methods to control throws probability, random delays and so on.
Now that these components exist for some time and they are working well, they needed a little refactoring.
So a new AbstractChaosComponent has been created acting as a base class for all chaos-related components, so that they now all inherit from it to result in less code and better evolvability.
See here for more.
> The existing NullFusionCache class has been moved in the new namespace, and this is a (small) breaking change.
The Backplane is a powerful component in FusionCache and is already a pretty good feature that works really well.
Now some more scenarios and edge cases are handled even better:
BackplaneAutoRecoveryMaxItems to unlimitedMemoryBackplane for better concurrencySee here for more.
The auto-recovery feature of the Backplane is already working pretty well, but sometimes there are situations where it could do a little more, a little better.
Now these scenarios are covered way better:
EnableDistributedExpireOnBackplaneAutoRecovery option)BackplaneAutoRecoveryReconnectDelay option)See here for more.
Log messages have been fine tuned even more, with greater details where needed, some extra log messages removed when they were not needed, and finally better wording in certain circumstances, which should help clarify the timing of some events eve more.
See here for more.
In FusionCache v0.22.0 the NullFusionCache has been introduced, which is an implementation of the Null Object Pattern.
Now these implementations are also available:
NullSerializer (impl of IFusionCacheSerializer)NullDistributedCache (impl of IDistributedCache)NullBackplane (impl of IFusionCacheBackplane)NullPlugin (impl of IFusionCachePlugin)There's also a new, specific namespace (ZiggyCreatures.Caching.Fusion.NullObjects) for these classes, to avoid polluting the root namespace.
See here for more.
[!WARNING]
The existingNullFusionCacheclass has been moved in the new namespace, and this is a (small) breaking change.
ChaosPluginFusionCache already has a set of chaos-engineering related classes like ChaosBackplane, ChaosDistributedCache and more, to ease testing how the system reacts to malfunctioning components, but in a controlled way.
A ChaosPlugin was missing: now not anymore.
See here for more.
FusionCache now supports expiring an entry explicitly. It can behave in 2 different ways, based on the fact that fail-safe is enabled or not:
Expire() method (docs)FusionCache now supports expiring an entry explicitly. It can behave in 2 different ways, based on the fact that fail-safe is enabled or not:
In this way the intent is clear, while still having space for some additional optimizations and support for problematic scenarios.
Here's an example:
await cache.ExpireAsync("foo");
Thanks to the community member @th3nu11 for getting started with the idea.
See here for the original issue.
SkipMemoryCache option (docs)Although very rare, sometimes it may be useful to skip the memory cache: now it is easily possible thanks to the new SkipMemoryCache option.
See here for the original issue.
FusionCache now includes the CacheName in each log message, which is now important since the introduction of Named Caches in v0.20.0.
On top of that, when logging about backplane messages, it now also include the CacheInstanceId as an extra help when going detective mode.
See here for the original issue.
NullFusionCacheThanks to some input from community member @SorenZ , FusionCache now provides a native implementation of the Null Object Pattern for when it's needed.
See here for the original issue.
FusionCache now keeps better track of the timestamp of when a cached value has been originally created.
Long story short: this will better track times, and allow for more sophisticated decisions regarding which cache entry version to use in some circumstances.
See here for the original issue.
Thanks to community member @CM2Walki 's request, durations equals to (or less than) TimeSpan.Zero are now natively supported, with optimized code paths.
It's not as simple as doing nothing, and it's possible to read more in the original issue's description.
Anyway, long story short: it just works 😊
See here for the original issue.
When working with Named Caches FusionCache internally works with the DI container to have all the registered FusionCache instances to be provided via the new IFusionCacheProvider interface.
The way it worked until today is that it simply instantiated all the registered ones, immediately.
From now on a lazy handling has been introduced, and cpu and memory will be saved, automatically.
See here for the original issue.
While disposing a FusionCache instance, distributed caches and backplanes are now automatically removed and/or unsubscribed from. Not that it was a huge problem, but still: better cleanup is better, amirite?
See here for the original issue.
Backplane notifications handling is now even better: the order of some internal operations is more streamlined, some hot paths have been optimized and less memory is being allocated.
There were a couple of very rare edge cases where, at least theoretically, it could've been possible to not release one of the internal locking primitives used to protect us from Cache Stampede.
Even if they never actually happened, now they cannot happen even theoretically.
More cases and more options are now supported while using adaptive caching: nothing specific to do, they now just work.
To see which options are supported with Adaptive Caching, just take a look at the Options docs and look for the 🧙♂️ icon.
When using Eager Refresh the distributed cache will now also be checked, before executing the factory: this is useful in case some fresh version of the data is arrived there in the meantime.
Again, nothing extra to do here.
There are now tests that automatically verify that old binary payloads, generated by old versions of the available serializers, can be deserialized correctly by the current version of the serializers.
This is important to guarantee that when updating a live system that uses a distributed cache that is already filled with some data, it will be possible to do so safely without having to do any extra migration activity or data loss.
See here for the original issue.
Some general performance optimizations regarding cpu usage, memory allocations and more.
[Obsolete] usageSome members that have been marked with the [Obsolete] attribute from some time, are now also marked with the error flag: there will still be helpful error messages on how to update existing code, but now that that code update must be completed.
This is important for the evolution of FusionCache, and for the upcoming v1.0.
FusionCache now fully supports conditional refresh, which is conceptually similar to conditional requests in HTTP.
FusionCache now fully supports conditional refresh, which is conceptually similar to conditional requests in HTTP.
Basically it is a way to cache and re-use either an ETag, a LastModified date or both, so that it is possible to save resources by not fully getting a remote resource (think: a remote http service response) in case it was not changed since the last time we got it.
Thanks to the community member @aKzenT for the invaluable help with the design discussion.
See here for the original issue.
It is now possible to tell FusionCache to eagerly start refreshing a value in the cache even before it's expired, all automatically and in the background (without blocking).
For example we can tell FusionCache to cache something for 10 min but eagerly start refreshing it after 90% of that (9 min) in the background, as soon as a GetOrSet<T>(...) call is made after the specified threshold: in this way fresh data will be ready earlier, and without having to wait for the refresh to complete when it would've expired.
Both eager refresh and the usual normal refresh + factory timeouts can be combined, without any problems.
See here for the original issue.
A new event has been added, for when eager refresh actually occurs.
WithoutLogger() builder method (docs)With the introduction of the Builder in the v0.20.0 release, something was missing: a way to tell FusionCache to not use a logger, at all: now this is fixed.
Thanks to community member @sherman89 for pointing that out.
See here for the original issue.
The type for the factory execution context has changed, from FusionCacheFactoryExecutionContext to FusionCacheFactoryExecutionContext<TValue>: this has been done to support conditional refresh and have access to the stale value already cached, which requires knowing the type upfront.
Most existing code should be fine: the only noticeable difference is that in some situations the C# compiler is, for some reasons, not able to do type inference correctly.
Because of this, in some instances a code like this:
var product = cache.GetOrSet(...);
must be updated to explicitly add the TValue type, like this:
var product = cache.GetOrSet<Product>(...);
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change befo
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change before the final release.
Having said that, you should also know that this version is already very polished, the api design surface area well modeled, performance-tuned, with full xml-docs and it has all the bells and whistles of a normal release.
FusionCache now fully supports conditional refresh, which is conceptually similar to conditional requests in HTTP.
Basically it is a way to cache and re-use either an ETag, a LastModified date or both, so that it is possible to save resources by not fully getting a remote resource (think: a remote http service response) in case it was not changed since the last time we got it.
Thanks to the community member @aKzenT for the invaluable help with the design discussion.
See here for the issue.
It is now possible to tell FusionCache to eagerly start refreshing a value in the cache even before it's expired, all automatically and in the background (without blocking).
For example we can tell FusionCache to cache something for 10 min but eagerly start refreshing it after 90% of that (9 min) in the background, as soon as a GetOrSet(...) call is made after the specified threshold: in this way the fresh data will be ready earlier, and without having to wait for the refresh to complete when it would've expired.
Both eager refresh and the usual normal refresh + factory timeouts can be combined, without any problems.
See here for the issue.
A new event has been added, for when eager refresh actually occurs.
WithoutLogger() builder methodWith the introduction of the Builder in the v0.20.0 release, something was missing: a way to tell FusionCache to not use a logger, at all: now this is fixed.
Thanks to community member @sherman89 for pointing that out.
See here for the issue.
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change befo
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change before the final release.
Having said that, you should also know that this version is already very polished, the api design surface area well modeled, performance-tuned, with full xml-docs and it has all the bells and whistles of a normal release.
FusionCache now fully supports conditional refresh, which is conceptually similar to conditional requests in HTTP.
Basically it is a way to cache and re-use either an ETag, a LastModified date or both, so that it is possible to save resources by not fully getting a remote resource (think: a remote http service response) in case it was not changed since the last time we got it.
Thanks to the community member @aKzenT for the invaluable help with the design discussion.
See here for the issue.
It is now possible to tell FusionCache to eagerly start refreshing a value in the cache even before it is expired.
For example we can tell FusionCache to cache something for 10min but eagerly start refreshing it after 9min in the background, so that it will be ready earlier without waiting for the refresh to end.
Although it's basically the same as caching something directly for 9min + enabling fail-safe + setting a very low factory soft timeout like 10ms, some community members requested it because it felt more intuitive this way, while others felt the other way around: therefore the addition, to support both approaches and be more welcoming.
Also, both approaches can be combined without problems.
See here for the issue.
WithoutLogger() builder methodWith the introduction of the Builder in the v0.20.0 release, something was missing: a way to tell FusionCache to not use a logger, at all: now this is fixed.
Thanks to community member @sherman89 for pointing that out.
See here for the issue.
If you are updating from a previous version, please read here.
If you are updating from a previous version, please read here.
There's now a really easy to use and flexible fluent API that supports the builder pattern. This allows a nice modular setup of FusionCache when using dependency injection, with the ability to add components and configure them with a couple of keystrokes, like:
services.AddFusionCache()
.WithSerializer(
new FusionCacheSystemTextJsonSerializer()
)
.WithDistributedCache(
new RedisCache(new RedisCacheOptions()
{
Configuration = "..."
})
)
.WithBackplane(
new RedisBackplane(new RedisBackplaneOptions()
{
Configuration = "..."
})
)
;
Thanks to the community member @aKzenT for the invaluable help with the design discussion.
See here for the original issue.
FusionCache now natively support multiple named caches via dependency injection, thanks to the new IFusionCacheProvider interface/service.
This makes it easy to register and retrieve different caches, potentially with different underlying caching storage (but not necessarily) and different configurations.
This is even easier thanks to the aforementioned Builder Pattern support, like this:
// USERS CACHE
services.AddFusionCache("UsersCache")
.WithDefaultEntryOptions(opt => opt
.SetDuration(TimeSpan.FromSeconds(10))
)
;
// PRODUCTS CACHE
services.AddFusionCache("ProductsCache")
.WithDefaultEntryOptions(opt => opt
.SetDuration(TimeSpan.FromSeconds(30))
.SetFailSafe(true, TimeSpan.FromMinutes(10))
)
;
Then you can depend on an IFusionCacheProvider service and easily ask to it for a certain cache with a GetCache("MyCache") call.
For example in an mvc controller you can go like this:
public class HomeController : Controller
{
IFusionCache _usersCache;
IFusionCache _productsCache;
public HomeController(IFusionCacheProvider cacheProvider)
{
_productsCache = cacheProvider.GetCache("ProductsCache");
_usersCache = cacheProvider.GetCache("UsersCache");
}
public IActionResult Product(int id)
{
_productsCache.GetOrDefault<Product>($"product:{id}");
// ...
}
}
And again, thanks to the community member @aKzenT for the invaluable help with the design discussion here, too.
See here for the original issue.
CacheKeyPrefix option (docs)Since there's now native support for multiple named caches, I'm currently playing with the idea of adding support for a CacheKeyPrefix option, that would be added in front of any cache key you specify with a certain FusionCache instance. This can be helpful to avoid cache key collisions when working with multiple named caches all sharing the same underlying caching storage mechanism (eg: memory, Redis, MongoDB, etc).
There's now native support for infinite expirations, with specific optimizations in the code to avoid exceptions and for better perf.
See here for more.
Two new options have been added to control the level for plugins info/error log entries.
See here for more.
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change befo
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change before the final release.
Having said that, you should also know that this version is already very polished, the api design surface area well modeled, performance-tuned, with full xml-docs and it has all the bells and whistles of a normal release.
ℹ NOTE: if you are updating from a previous version, please read here.
Ok, enough with the warnings: let's talk about the features 🎉
There's now a really easy to use and flexible fluent API that supports the builder pattern. This allows a nice modular setup of FusionCache when using dependency injection, with the ability to add components and configure them with a couple of keystrokes, like:
services.AddFusionCache()
.WithSerializer(
new FusionCacheSystemTextJsonSerializer()
)
.WithDistributedCache(
new RedisCache(new RedisCacheOptions()
{
Configuration = "..."
})
)
.WithBackplane(
new RedisBackplane(new RedisBackplaneOptions()
{
Configuration = "..."
})
)
;
NOTE: The api surface has changed a little bit from v0.20.0-preview1.
Thanks to the community member @aKzenT for the invaluable help with the design discussion.
See here for the issue. See here for the docs.
FusionCache now natively support multiple named caches via dependency injection, thanks to the new IFusionCacheProvider interface/service.
This makes it easy to register and retrieve different caches, potentially with different underlying caching storage (but not necessarily) and different configurations.
This is even easier thanks to the aforementioned Builder Pattern support, like this:
// USERS CACHE
services.AddFusionCache("UsersCache")
.WithDefaultEntryOptions(opt => opt
.SetDuration(TimeSpan.FromSeconds(10))
)
;
// PRODUCTS CACHE
services.AddFusionCache("ProductsCache")
.WithDefaultEntryOptions(opt => opt
.SetDuration(TimeSpan.FromSeconds(30))
.SetFailSafe(true, TimeSpan.FromMinutes(10))
)
;
Then you can depend on an IFusionCacheProvider service and easily ask to it for a certain cache with a GetCache("MyCache") call.
For example in an mvc controller you can go like this:
public class HomeController : Controller
{
IFusionCache _usersCache;
IFusionCache _productsCache;
public HomeController(IFusionCacheProvider cacheProvider)
{
_productsCache = cacheProvider.GetCache("ProductsCache");
_usersCache = cacheProvider.GetCache("UsersCache");
}
public IActionResult Product(int id)
{
_productsCache.GetOrDefault<Product>($"product:{id}");
// ...
}
}
And again, thanks to the community member @aKzenT for the invaluable help with the design discussion here, too.
See here for the issue. See here for the docs.
CacheKeyPrefix optionSince there's now native support for multiple named caches, I'm currently playing with the idea of adding support for a CacheKeyPrefix option, that would be added in front of any cache key you specify with a certain FusionCache instance. This can be helpful to avoid cache key collisions when working with multiple named caches all sharing the same underlying caching storage mechanism (eg: memory, Redis, MongoDB, etc).
There's now native support for infinite expirations, with specific optimizations in the code to avoid exceptions and for better perf.
See here for more.
Two new options have been added to control the level for plugins info/error log entries.
See here for more.
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change befo
This is a pre-release of FusionCache, so please be aware that although it contains some shiny new stuff (see below), it is also subject to change before the final release.
Having said that, you should also know that this version is already very polished, the api design surface area well modeled, performance-tuned, with full xml-docs and it has all the bells and whistles of a normal release.
Ok, enough with the warnings: let's talk about the features 🎉
There's now a really easy to use and flexible fluent API that supports the builder pattern. This allows a nice modular setup of FusionCache when using dependency injection, with the ability to add components and configure them with a couple of keystrokes, like:
services.AddFusionCache(b => b
.WithSerializer(
new FusionCacheSystemTextJsonSerializer()
)
.WithDistributedCache(
new RedisCache(new RedisCacheOptions()
{
Configuration = "..."
})
)
.WithBackplane(
new RedisBackplane(new RedisBackplaneOptions()
{
Configuration = "..."
})
)
);
Thanks to the community member @aKzenT for the invaluable help with the design discussion.
See here for more.
FusionCache now natively support multiple named caches via dependency injection, thanks to the new IFusionCacheProvider interface/service.
This makes it easy to register and retrieve different caches, potentially with different underlying caching storage (but not necessarily) and different configurations.
This is even easier thanks to the aforementioned Builder Pattern support, like this:
// USERS CACHE
services.AddFusionCache("UsersCache", b => b
.WithDefaultEntryOptions(opt => opt
.SetDuration(TimeSpan.FromSeconds(10))
)
);
// PRODUCTS CACHE
services.AddFusionCache("ProductsCache", b => b
.WithDefaultEntryOptions(opt => opt
.SetDuration(TimeSpan.FromSeconds(30))
.SetFailSafe(true, TimeSpan.FromMinutes(10))
)
);
Then you can depend on an IFusionCacheProvider service and easily ask to it for a certain cache with a GetCache("MyCache") call.
For example in an mvc controller you can go like this:
public class HomeController : Controller
{
IFusionCache _usersCache;
IFusionCache _productsCache;
public HomeController(IFusionCacheProvider cacheProvider)
{
_productsCache = cacheProvider.GetCache("ProductsCache");
_usersCache = cacheProvider.GetCache("UsersCache");
}
public IActionResult Product(int id)
{
_productsCache.GetOrDefault<Product>($"product:{id}");
// ...
}
}
And again, thanks to the community member @aKzenT for the invaluable help with the design discussion here, too.
See here for more.
CacheKeyPrefix optionSince there's now native support for multiple named caches, I'm currently playing with the idea of adding support for a CacheKeyPrefix option, that would be added in front of any cache key you specify with a certain FusionCache instance. This can be helpful to avoid cache key collisions when working with multiple named caches all sharing the same underlying caching storage mechanism (eg: memory, Redis, MongoDB, etc).
This decision is not final, and I'm interested in getting the opinions from the community.
After a request by the community member @RMcD a new entry option has been added to be able to specify a fail-safe max duration specific for the distri
DistributedCacheFailSafeMaxDuration option (docs)After a request by the community member @RMcD a new entry option has been added to be able to specify a fail-safe max duration specific for the distributed cache level.
See here for more.
After talking with community member @fkuhnert , an old thought re-emerged: for readonly methods like TryGet[Async] and GetOrDefault[Async] no stale data throttling should occur. This means that, even with fail-safe enabled, if there's some usable stale data it will be returned, BUT not saved. This makes sense, as a TryGet or a GetOrDefault does not suggest a "save" operation (see: Principle of Least Astonishment).
This should not change any apparent behaviour from the outside: the only thing potentially noticeable is that, if you have a large number of TryGet/GetOrDefault calls done on stale data, you may see some more of them going to the distributed cache, that's all.
A new serializer is now available in its own package, to support the ServiceStack JSON serializer.
Thanks @mythz for yout support!
Thanks to the community member @suhrab for spotting an edge case that could have been already handled.
When a user enable fail-safe and specifies a FailSafeMaxDuration lower than the Duration, the situation can feel messy since the thing being asked is not really in line with how FusionCache operates.
To avoid this, a new normalization phase has been added, to make all the values coherent with the situation. In case a normalization occurs, FusionCache will also log it with a (configurable) Warning level.
See here for more.
FactorySuccess event (docs)A new event has been added that will trigger when a non-background factory completes successfully, after a request from community member @bartlomiejgawel (thanks for the tip!).
For the background one, keep using the BackgroundFactorySuccess event that already exists.
See here for more.
When logging is enabled, FusionCache automatically generates a unique operation id per each operation (eg: each GetOrSet/GetOrDefault/TryGet/etc call) to make detective work easier while looking at the logs.
The generation of these operation ids now consumes 83% less cpu time and 45% less memory.
The docs has been expanded and refined: one of these changes is that in the Options now there's a clear indication about which entry options are compatible with adaptive caching, thanks to a chat with @celluj34.
Thanks Joe for the inspiration!
After some requests by the community, a new entry option has been added to skip the distributed cache only in specific calls, in a very granular way.
SkipDistributedCache optionAfter some requests by the community, a new entry option has been added to skip the distributed cache only in specific calls, in a very granular way.
See here for more.
SkipDistributedCacheReadWhenStale optionIt is now possible to skip distributed cache reads when the memory entry was stale: this will lead to a perf boost when the 2nd layer is not actually a distributed cache but just an out-of-process cache, like in mobile apps, standalone apps, games and more.
See here for more.
Thanks to an issue opened by @RMcD , it has been discovered that MemoryPack has a quite strange and non-standard way to handle transitive dependencies + code generation regarding .NET Standard 2.1 and .NET 7. After having opened an issue on its repo + some back and forth with its author (thanks to @neuecc for your openness and support!), a solution has been found. The issue there remains, but at least now the integration between FusionCache and MemoryPack is good to go, even on .NET 7!
See here for more.
EnableBackplaneNotifications option to (inverted) SkipBackplaneNotificationsA small rename so that now everything is more aligned and intuitive.
See here for more.
Augmented some online docs and inline XML docs, for a better experience while coding.
A new serializer is now available in its own package, to support the new MemoryPack serialization format.
A new serializer is now available in its own package, to support the new MemoryPack serialization format.
It is based on the amazing work by @neuecc , and this new serializer seems to be already the fastest serializer in the .NET space.
Thanks for your hard work Yoshifumi!
After a couple of releases where it was disabled by default, the initial response in real-world projects has been positive: therefore I decided to enable the auto-recovery feature by default for everyone 🎉
PS: of course you can always turn it off in case you are having problems.
A new serializer is now available in its own package, to support the Protobuf serialization format.
A new serializer is now available in its own package, to support the Protobuf serialization format.
It is based on of the most used Protobuf serializers on .NET: protobuf-net (repo here) by @mgravell : thanks for your hard work!
[DebuggerDisplay] usagesSome class have been decorated with the [DebuggerDisplay] attribute, for a better debugging experience.
Some methods and properties have been decorated even better with nullability annotations, so that static flow analysis can help us catch even more potential NREs (null reference exceptions).
I never noticed that and, since it is only used internally, nobody really paid any attention to that but the community user @luizhtm was spot on in noticing a typo in the Fusio(n)CacheChaosUtils utility class: a missing "n"!
Now there's the correct one with the right name, but temporarily the old one also remains: the entire class and every method inside has been marked as [Obsolete] with an explanation of the issue and how to correct any reference.
Thanks again @luizhtm !
Added a couple more helpful descriptions.
A new serializer is now available in its own package, to support the MessagePack serialization format.
A new serializer is now available in its own package, to support the MessagePack serialization format.
It is based on the most used one on .NET: MessagePack (repo here) by @neuecc : thanks for your hard work!
ReThrowSerializationExceptionsA new option has been added to better control de/serialization exceptions, and the internal flow has been made better around those potential exceptions.
NOTE: contrary to the already existing ReThrowDistributedCacheExceptions which is disabled by default, this option is enabled by default. The rationale is that, while an error while talking to the distributed cache may be transient (because the distributed cache is temporarily down, there's a network error, etc), de/serialization should either always work or not, and typically any error is because of an unsupported data type or a missing configuration, and that is something that we should know as soon as possible and not pretend like it can magically go away later with a retry (like, instead, a transient distributed cache error instead).
ChaosSerializerA new ChaosSerializer has been added (in the ZiggyCreatures.FusionCache.Chaos package) to better handle fail scenarios during de/serialization.
Fixed some typos and added a couple more helpful descriptions.
FusionCache now has a backplane auto-recovery feature!
FusionCache now has a backplane auto-recovery feature!
It has been added to automatically recover from transient errors in the backplane by keeping a local queue of the notifications that have not been sent successfully. These notifications will be automatically retried as soon as the backplane will become available again, without having to do anything.
It also handles common edge cases, like out of order notifications, and it can also be limited in size to avoid too consuming too much memory, with a sensible heuristic about which notifications to keep.
🧪 NOTE: for now the feature is experimental, and must be manually enabled via the new EnableBackplaneAutoRecovery option.
More info here.
The chaos-related utilities and components, like ChaosDistributedCache and ChaosBackplane, have been moved to a separate project (ZiggyCreatures.FusionCache.Chaos).
This should also slightly reduce dependencies and code size of the main package.
Added links to the related online documentation in the xml docs for most options, and fixed some typos.
Added a page about Logging.
Added a chapter about the lock timeout option in the Cache Stampede page.
Added a chapter about notifications behaviour in the Backplane page.
Added a chapter about auto-recovery in the Backplane page.
Some members marked as [Obsolete] from a very very long time have been finally removed to clean up the code.
A member of the community (@yzhoholiev , thanks!) noticed that the local (memory cache) expiration, when coming from the distributed cache, was not go
A member of the community (@yzhoholiev , thanks!) noticed that the local (memory cache) expiration, when coming from the distributed cache, was not good enough: with this fix the inferred memory cache expiration in those situations is more precise. In some scenario a little bit more memory may be used with the distributed cache (eg: when not using fail-safe, otherwise it stays the same) but that should not be very frequent and the additional memory should reasonably not be a problem.
See here for more.
Added a new entry option DistributedCacheDuration (as a nullable TimeSpan). This serves as an optional specific duration for the distributed cache (if
DistributedCacheDurationAdded a new entry option DistributedCacheDuration (as a nullable TimeSpan).
This serves as an optional specific duration for the distributed cache (if you are using one) to allow custom overrides of the "main" duration: in this way it is now possible for example to specify a duration in the memory cache of 1 min and a duration in the distributed cache of, say, 1 hour.
In theory this is useless if you are using a backplane but, in case you prefer not to or cannot for some reason, this would mitigate the synchronization problems you may encounter in a multi-node scenario.
See here for more.
FusionCache now supports SourceLink, which should make your debugging experience easier.
See here for more.
FusionCache now supports Deterministic Builds, which is a nice addition.
See here for more.
Duplicate() method overrideThe override removed has been marked [Obsolete] for a very very long time and hopefully nobody should've been using it.
This release includes a lot of small features, changes and fixes.
This release includes a lot of small features, changes and fixes.
In a previous release there has been a small regression in the events emitted during a GetOrSet call: now it has been fixed.
See https://github.com/jodydonetti/ZiggyCreatures.FusionCache/issues/49
failSafeDefaultValue providedHistorically the soft timeout, if specified, has been used only when there was a fallback value in the form of an already expired cache entry.
Sadly, after having introduced the failSafeDefaultValue param, that has not been used to enable the soft timeout.
Now this is resolved thanks to @alexmaek , who also made their first contribution!
See https://github.com/jodydonetti/ZiggyCreatures.FusionCache/pull/67
Note This feature has been rolled back in v0.11.1 release because it was not the right move. See the pull request above for more!
Following a community request, it is now possible to enable re-throwing of distributed cache exceptions, if you feel like it.
This is done via the new ReThrowDistributedCacheExceptions option on the FusionCacheEntryOptions object.
See https://github.com/jodydonetti/ZiggyCreatures.FusionCache/issues/34
Now synthetic timeouts are handled in a more specific way, and there's a new BackplaneSyntheticTimeoutsLogLevel option in the FusionCacheEntryOptions object.
The internal flow on backplane exceptions is now better, to let the (optional) circuit breaker do its job more easily.
Nothing published for this version
FusionCache now supports adaptive caching!
FusionCache now supports adaptive caching!
This means having new GetOrSet overloads where it is possible to change some options inside the factory, to be able to adapt (hence the name of the feature) some of these options to the object being cached. A typical example is caching a fresh news article for a small Duration, and an old one for a higher one.
More examples and explanations in the related documentation.
There's a new optimization that kicks in automatically during a GetOrSet call if:
IsFailSafeEnabled)FactorySoftTimeout has been specifiedLockTimeout has NOT been specified (pretty common)In this case it may happen that a during multiple concurrent GetOrSet calls for the same key, the first one acquired the lock and start executing the factory. During this time the other GetOrSet calls for the same cache key are put on hold (to prevent a cache stampede, see here). But if the factory takes too much time it doesn't make sense to wait for it for the other callers, if they allow fail-safe and there's stale data to use as a fallback.
So with this optimization this is exactly what happens, maybe granting a perf boost in thee situations.
NOTE: these early-returning GetOrSet calls btw will NOT temporarily re-save the stale data in the cache, because the currently running factory will do so nonetheless, and because doing so does not incur in extra factory calls, so we are still protected from the cache stampede problem.
Thanks to a suggestion by @JoeShook , FusionCache now emit events for cache hit with isStale set to true not only when a fail-safe is being activated, but in all subsequent cache hits until the entry is replaced by a successful factory execution, which frankly makes more sense.
HasDistributedCacheA new bool property has been added to IFusionCache to let you know if there is a distributed cache configured (like the already existing HasBackplane).
Added a warning log when setting up a backplane in this scenario:
DefaultEntryOptions.EnableBackplaneNotifications is set to trueThis is important to prevent shooting yourself in the foot without knowing it, and that may happen because without a distributed cache there is no shared state between nodes, and if by default the backplane notifications are enabled it means that every time something is put into the cache in a node, all the other nodes will wipe their copy, creating a never ending update-remove-update-remove-etc loop.
You can read more about a scenario like this in the backplane documentation.
FusionCache now supports adaptive caching!
FusionCache now supports adaptive caching!
This means having new GetOrSet overloads where it is possible to change some options inside the factory, to be able to adapt (hence the name of the feature) some of these options to the object being cached. A typical example is caching a fresh news article for a small Duration, and an old one for a higher one.
More examples and explanations in the related documentation.
There's a new optimization that kicks in automatically during a GetOrSet call if:
IsFailSafeEnabled)FactorySoftTimeout has been specifiedLockTimeout has NOT been specified (pretty common)In this case it may happen that a during multiple concurrent GetOrSet calls for the same key, the first one acquired the lock and start executing the factory. During this time the other GetOrSet calls for the same cache key are put on hold (to prevent a cache stampede, see here). But if the factory takes too much time it doesn't make sense to wait for it for the other callers, if they allow fail-safe and there's stale data to use as a fallback.
So with this optimization this is exactly what happens, maybe granting a perf boost in thee situations.
NOTE: these early-returning GetOrSet calls btw will NOT temporarily re-save the stale data in the cache, because the currently running factory will do so nonetheless, and because doing so does not incur in extra factory calls, so we are still protected from the cache stampede problem.
HasDistributedCacheA new bool property has been added to IFusionCache to let you know if there is a distributed cache configured (like the already existing HasBackplane).
Added a warning log when setting up a backplane in this scenario:
DefaultEntryOptions.EnableBackplaneNotifications is set to trueThis is important to prevent shooting yourself in the foot without knowing it, and that may happen because without a distributed cache there is no shared state between nodes, and if by default the backplane notifications are enabled it means that every time something is put into the cache in a node, all the other nodes will wipe their copy, creating a never ending update-remove-update-remove-etc loop.
You can read more about a scenario like this in the backplane documentation.
Please try it out and let me know so I can push the final version out.
FusionCache now has a fully functioning backplane, to ease synchronization between nodes in a multi-node scenario.
FusionCache now has a fully functioning backplane, to ease synchronization between nodes in a multi-node scenario.
It's very easy to setup and requires no additional work: it just works.
There are currently 2 implementations: one memory-only (mainly for testing) and one for Redis.
The backplane, like the 2nd level cache, is fully featured including events and logging and, since it talks to a separate system (eg: a Redis or Memcached instance), it natively support a simple circuit-breaker to better handle transient errors, again like the 2nd level cache.
Since the v0.9.0 is a big release with a great new feature, I took the chance and tried to improve the docs.
Of course there's the new part about the backplane and how to use it in various situations (both with and without the distributed cache).
I also collected all the IDistributedCache implementations available on Nuget, which is something I hope can be useful to the community as they can serve as the secondary cache layer.
Finally some typos have been corrected and a lot of small parts in general have been added where I felt they were missing.
Thanks to a tip by the community (see here https://github.com/jodydonetti/ZiggyCreatures.FusionCache/issues/38), I changed a log level used when no fallback entry was available for a fail-safe activation, since it seemed more correct this way.
CacheKeyPrefix optionThe FusionCacheOptions.CacheKeyPrefix option is now fully obsolete: it has been marked with the [Obsolete] attribute including the additional error flag, and is hidden via the [EditorBrowsable] attribute so its use will not compile anymore (see #33 for more).
Evict methodThe Evict method was just something theoretically used to create the backplane, nothing to be used in the normal FusionCache usage.
Since in the end the final backplane design did not need this method, it has been removed to keep a more streamlined API.
This is the third and last BETA release containing the new Backplane #11 🎉.
This is the third and last BETA release containing the new Backplane #11 🎉.
It contains everything that was already in alpha1, alpha2, beta1 and beta2 plus:
In general this is the final polishing pass of everything.
The new docs are finished, particularly the ones about the new backplane and how to use it in various situations (both with and without the distributed cache). I also collected all the IDistributedCache implementations available on Nuget, which is something I hope can be useful to the community as they can serve as the secondary cache layer. Finally some typos have been corrected and more parts in general have been added where I felt they were missing.
The tentative new Publish[Async] method was experimentally introduced a little while ago: it served its purpose, and since it was just an experiment and realliy only used internally, I decided to remove it before the next official version, so to keep a clean a slim api.
The tentative new Evict method was experimentally introduced a little while ago: it served its purpose, and since it was just an experiment and realliy only used internally, I decided to remove it before the next official version, so to keep a clean a slim api.
Please try it and let me know so I can push the final version out!
This is the second BETA release containing the new Backplane #11 🎉.
This is the second BETA release containing the new Backplane #11 🎉.
It contains everything that was already in alpha1, alpha2 and beta1 plus:
Because of some local code explorations + git reverts, I haven't in fact pushed the code for the backplane auto-setup in DI: this means that in a DI scenario we were not, in fact, using the backplane, even if properly configured. Yep, I'm that dumb 😑
Better initial backplane subscription handling, with a design that is more open for future extensibility.
Please try it and let me know so I can push the final version out!
This is the first BETA release containing the new Backplane #11 🎉.
This is the first BETA release containing the new Backplane #11 🎉.
It contains everything that was already in alpha1 and alpha2 plus:
In preparation for the big official release I've changed a couple of names to make them prettier and shorter. For example I went from SendBackplaneNotification to Publish, etc
Now backplane notifications are more granular, differentiating between entry SET and REMOVE. Also added the instant in which a notification has been generated, for a better synchronization.
Way better peformance for serialization of backplane messages (RedisBackplane).
Added backplane options to the log string for FusionCacheEntryOptions.
HasBackplaneA new bool property has been added to IFusionCache to let you know if there is a backplane.
Please try it and let me know so I can push the final version out!
This is the second alpha release containing the new Backplane #11 🎉.
This is the second alpha release containing the new Backplane #11 🎉.
It contains:
For both message sent/received.
Added logging about the backplane.
Also, thanks to a tip by the community (see here #38), I changed a log level used when no fallback entry was available for a fail-safe activation, since it seemed more correct this way.
Please try it and let me know so I can push the final version out!
Of course, everything in the alpha1 is still included.
Finally, this is the first (alpha) release containing the Backplane #11 🎉.
Finally, this is the first (alpha) release containing the Backplane #11 🎉.
FusionCache finally has a fully functioning backplane: see here for more.
CacheKeyPrefixThe FusionCacheOptions.CacheKeyPrefix option is now fully obsolete: it has been marked with the [Obsolete] attribute including the additional error flag, so its use will not compile anymore (see #33 for more).
Please try it and let me know so I can push the final version out!
This is a small release, in preparation of the big one where the Backplane #11 will be added 🎉.
This is a small release, in preparation of the big one where the Backplane #11 will be added 🎉.
CacheNameIt is now possible to specify a cache name, namely a logical name that identify a cache.
It can be used for identification, and in a multi-node scenario it is typically shared between nodes to create a logical association that may be useful to have them communicate together (ref Backplane).
It is possible to specify it in the FusionCacheOptions, and is acessible as a read-only prop directly on any FusionCache instance.
InstanceIdEach time a new FusionCache instance is created (eg: via a new FusionCache(...) directly or via DI) a new id will be generated, globally and uniquely identifying that specific instance.
It can be useful to uniquely identify a single instance in a multi-node scenario, for example to precisely route notifications to each one (ref Backplane).
It is acessible as a read-only prop directly on any FusionCache instance.
Evict methodA new Evict method has been added: this method evicts an entry from the cache, like the Remove method, but with 2 very important differencs:
Again, this is useful in the Backplane that is coming.
It is only available in a sync fashion and not in an async one, since it acts only locally and there's nothing to do asynchronously.
[Obsolete] for future removalThe CacheKeyPrefix option is now obsolete: it still works, but will be kinda removed in the next version.
See here for more info.
Added a couple of small perf optimizations here and there.
A new FusionCacheOptions.DistributedCacheKeyModifierMode option has been added, so that you can now control how the cache key will be modified to be u
A new FusionCacheOptions.DistributedCacheKeyModifierMode option has been added, so that you can now control how the cache key will be modified to be used in the distributed cache (Prefix, Suffix or None).
The default value is Prefix but, if for example you are having problems with Redis ACLs (which are prefix-based), you can change this to Suffix (or even None) to solve them.
Thanks to RogerSep for the hint about Redis ACLs, I hope this will solve your problem!
Is this a breaking change? In short, no. To expand on it a little bit more, it could be if you directly used a Task returned from one of the async met…
Task<T> to ValueTask<T>The async part of the api surface area has been migrated from using the Task<T> type to the ValueTask<T> type.
This allows saving a good amount of memory allocations, making our apps more performant.
Is this a breaking change? In short, no.
To expand on it a little bit more, it could be if you directly used a Task<T> returned from one of the async methods, instead of awaiting it normally. In that case simply add .AsTask() to turn the ValueTask<T> into a Task<T> and everything will be fine.
In all other normal usage scenarios, just awaiting on one of the async methods would work absolutely the same, while also allocating less memory 🎉
I've finally removed the TryGetResult<T> type, marked as [Obsolete] from a lot of time now.
It has been replaced a long ago with the MaybeValue<T> type, which is better designed and used also as an input, and not just an output.
For more information about the change please read the "Breaking change" section of the v0.1.3 release.
The same goes for the Success prop in the MaybeValue<T> type, also marked as [Obsolete] since the beginning and added just to allow a more pleasant transition from the old type to the new one.
Thanks to the the great Marc Gravell and Stephen Toub for their writings on this subject, in particular this and this which helped clear my mind on the subject.
One column per quarter.