Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This section describes what ICacheRefresher and ICacheRefresher<T> are and how to use them to invalidate your cache correctly including load balanced environments
This interface has been in the Umbraco core for a significant period. However, it has really only been used to ensure that content cache is refreshed among all server nodes participating in a load balanced scenario.
An ICacheRefresher
is the primary method that invalidates any cache needing refreshment or removal. This applies regardless of a load balanced environment.
There are now a few different types of ICacheRefreshers
in the Umbraco core. It is important to understand the differences between them and how cache invalidation works across multiple server nodes.
This section refers to how to implement caching features in the Umbraco application in a consistent way that will work in both single server environments and load balanced (multi-server) environments. The caching described in this section relates to application caching in the context of a web application only.
Please read this if you are Caching
Although caching is a pretty standard concept it is very important to make sure that caching is done correctly and consistently. It is always best to ensure performance is at its best before applying any cache and also beware of over caching as this can cause degraded performance in your application because of cache turnover.
In normal environments caching seems to be a pretty standard concept. If you are a package developer or developer who is going to publish a codebase to a load balanced environment then you need to be aware of how to invalidate your cache properly, so that it works in load balanced environments. If it is not done correctly then your package and/or codebase will not work the way that you would expect in a load balanced scenario.
If you are caching business logic data that changes based on a user's action in the backoffice and you are not using an _ICacheRefresher_** then you will need to review your code and update it based on the below documentation.**
You can update and insert items in the cache.
The standard way to invalidate cache in Umbraco is to implement an ICacheRefresher
.
The interface consists of the following methods:
Guid RefresherUniqueId { get; }
Which you'd return your own unique GUID identifier
string Name { get; }
The name of the cache refresher (informational purposes)
void RefreshAll();
This would invalidate or refresh all caches of the caching type that this ICacheRefresher
is created for. For example, if you were caching Employee
objects, this method would invalidate all Employee
caches.
void Refresh(int Id);
This would invalidate or refresh a single cache for an object with the provided int
id.
void Refresh(Guid Id);
This would invalidate or refresh a single cache for an object with the provided GUID id.
void Remove(int Id);
This would invalidate a single cache for an object with the provided int
id. In many cases Remove and Refresh perform the same operation but in some cases Refresh
doesn't remove/invalidate a cache entry, it might update it. Remove
is specifically used to remove/invalidate a cache entry.
Some of these methods may not be relevant to the needs of your own cache invalidation so not all of them may need to perform logic.
There are 2 other base types of ICacheRefresher
which are:
ICacheRefresher<T>
- this inherits from ICacheRefresher
and provides a set of strongly typed methods for cache invalidation. This is useful when executing the method to invoke the cache refresher, when you have the instance of the object already since this avoids the overhead of retrieving the object again.
void Refresh(T instance);
- this would invalidate/refresh a single cache for the specified object.
void Remove(T instance);
- this would invalidate a single cache for the specified object.
IJsonCacheRefresher
- this inherits from ICacheRefresher
but provides more flexibility if you need to invalidate cache based on more complex scenarios (e.g. the MemberGroupCacheRefresher).
void Refresh(string jsonPayload)
- Invalidates/refreshes any cache based on the information provided in the JSON. The JSON value is any value that is used when executing the method to invoke the cache refresher.
There are several examples of ICacheRefresher
's in the core: https://github.com/umbraco/Umbraco-CMS/tree/v9/dev/src/Umbraco.Core/Cache
To execute your ICacheRefresher
you call these methods on the DistributedCache
instance (the DistributedCache
object exists in the Umbraco.Cms.Core.Cache
namespace):
void Refresh<T>(Guid cacheRefresherId, Func<T, int> getNumericId, params T[] instances)
This executes an ICacheRefresher<T>.Refresh(T instance)
of the specified cache refresher Id
void Refresh(Guid cacheRefresherId, int id)
This executes an ICacheRefresher.Refresh(int id)
of the specified cache refresher Id
void Refresh(Guid cacheRefresherId, Guid id)
This executes an ICacheRefresher.Refresh(Guid id)
of the specified cache refresher Id
void Remove(Guid refresherGuid, int id)
This executes an ICacheRefresher.Remove(int id)
of the specified cache refresher Id
void Remove<T>(Guid refresherGuid, Func<T, int> getNumericId, params T[] instances)
This executes an ICacheRefresher<T>.Remove(T instance)
of the specified cache refresher Id
void RefreshAll(Guid refresherGuid)
This executes an ICacheRefresher.RefreshAll()
of the specified cache refresher Id
So when do you use these methods to invalidate your cache?
This really comes down to what you are caching and when it needs to be invalidated.
When an ICacheRefresher
is executed via the DistributedCache
a notification is sent out to all servers that are hosting your web application to execute the specified cache refresher. When not load balancing, this means that the single server hosting your web application executes the ICacheRefresher
directly. However when load balancing, this means that Umbraco will ensure that each server hosting your web application executes the ICacheRefresher
so that each server's cache stays in sync.
To use the extensions add a using to Umbraco.Extensions
; You can then invoke them on the injected DistributedCache
object.
The server messenger broadcasts 'distributed cache notifications' to each server in the load balanced environment. The server messenger ensures that the notification is processed on the local environment.
See our example on how to cache tags.
You should always be doing this consistently with the best practices listed below. You shouldn't be using HttpRuntime.Cache or HttpContext.Current.Cache directly. Instead, you should always be accessing it via the AppCaches cache helper (Umbraco.Cms.Core.Cache
).
The AppCaches
which can be found in namespace Umbraco.Cms.Core.Cache
contains types of cache: Runtime Cache, Request Cache and Isolated Caches.
Runtime Cache is the most commonly used and is synonymous with HttpRuntime.Cache. Request cache is cache that exists only for the current request. This is synonymous with HttpContext.Current.Items and isolated caches. These are used by for example repositories, to ensure that each cached entity type has its own cache. When they have their own cache, lookups are fast and the repository does not need to search through all keys on a global scale.
If you wish to use the AppCaches in a class, you need to use Dependency Injection (DI) in your constructor:
Broadcasts distributed cache notifications to all servers of a load balanced environment. Also ensures that the notification is processed on the local environment.
For a specified ICacheRefresher, the implemented methods will:
Notify the distributed cache
Invalidate specified items
Notify all servers of specified items removal
Notify all servers of invalidation of a object
Notify all servers of a global invalidation (clear the complete cache)
This section describes how you should be getting/adding/updating/inserting items in the cache.
The recommended way to put data in and get data out is to use one of the many overloaded methods of: GetCacheItem
. The GetCacheItem
methods (all except one) are designed to "Get or Add" to the cache. For example, the following will retrieve an item from the cache and if it doesn't exist will ensure that the item is added to it:
where _appCaches
is injected as type AppCaches
.
Notice 2 things:
The GetCacheItem
method is strongly typed and
We are supplying a callback method which is used to populate the cache if it doesn't exist.
The example above will retrieve a strongly typed object of MyObject
from the cache with the key of "MyCacheKey", if the object doesn't exist in the cache a new instance of MyObject
will be added to it with the same key.
There are a couple of overloads of GetCacheItem
allowing you to customize how your object is cached from cache dependencies to expiration times.
To use this generic implementation, add the Umbraco.Extensions
namespace to your code.
One of the overloads of GetCacheItem
doesn't specify a callback, this will allow you to retrieve an item from the cache without populating it if it doesn't exist.
An example of usage:
where _appCaches
is injected as type AppCaches
.
Sometimes you might want to put something in the cache without retrieving it. In this case there is an InsertCacheItem<T>
method. This method will add or update the cache item specified by the key so if the item already exists in the cache, it will be replaced.
Information on how to insert and delete from the runtime cache
This article will show you how to insert and delete from the runtime cache.
For this example we're working with tags. On my site I have two tag properties:
One on every page using the tag group default
One on my blog posts using the tag group blog
We're going to expose an endpoint that allows us to get the tags from each group.
The tags from the default
should be cached for a minute and the blog
tags will be cached until site restart or if you publish a blog post node in the Backoffice.
Why work with tags? Because they're not cached by default.. which makes them ideal for demo purposes :)
First we want to create our CacheTagService
. In this example it's a basic class with one method (GetAll
) that wraps Umbraco's TagQuery.GetAllTags()
.
As you can see we inherit from the ICacheTagService
interface. All that has is:
The interface was created to better register it so we can use dependency injection. You can register your own classes like so:
Now you can inject ICacheTagService
in any constructor in your project - wohooo!
Now that we have our service it's time to create an endpoint where we can fetch the (cached) tags.
The example below uses UmbracoApiController which is obsolete in Umbraco 14 and will be removed in Umbraco 15.
/umbraco/api/tags/getblogtags
/umbraco/api/tags/getdefaulttags
Everything should now work as expected when it comes to getting tags. However, if I go to my Backoffice and add a new tag to the blog
group the changes aren't shown on the endpoint. Let's fix that.
To clear the cache we need a notification handler in which we register to the ContentPublishedNotification
event on the ContentService
. This allows us to run a piece of code whenever you publish a node.
Now that we have our notification we also need to register it. Add builder.AddNotificationHandler<ContentPublishedNotification, Notification>();
to the Compose
method in the Composer
class so it becomes:
Awesome! Now we have set up caching on our tags - making the site a bit faster.
.