Umbraco uses a lazy loaded cache, meaning content is loaded into the cache on an as-needed basis. Whenever a piece of content is shown on the website for the first time it first needs to be loaded into the cache.

Loading the content into the cache causes a delay. This delay is dependent on the latency between your server and your database, but is generally minimal. For certain pages, like the front page, you may not want this delay to be there. The role of cache seeding is meant to solve this issue.

How it works

Cache seeding is based on the concept of an ISeedKeyProvider. The role of the seed key provider is to specify what keys need to be seeded.

There are two types of seed key providers: an IDocumentSeedKeyProvider specifying which document should be seeded, and an IMediaSeedKeyProvider specifying which media should be seeded.

During startup, all the ISeedKeyProviders are run, and the keys they return are seeded into their respective caches, IPublishedContentCache for documents, and IPublishedMediaCache for media. Additionally, whenever a document or media is changed, the cache will immediately be updated with the changed content. This ensures that the content is always present in the cache.

Whenever a piece of content is changed, the seeded keys must be checked, to see if the updated content was seeded. Because of the need the check all seeded keys, Umbraco caches the keys themselves during startup. This means that if you have a dynamic seed key provider, any newly added content will not be considered seeded until the server restarts. For instance, when seeding by Document Type any new content using the specified Document Type will not be seeded until the server is restarted.

Seed key providers

Default implementations

By default, Umbraco ships with two seed key providers for documents, and one for media.

For documents, the ContentTypeSeedKeyProvider seeds all documents of the given Document Types specified in the appSettings.json file.

For documents and media, the BreadthFirstKeyProvider does a breadth-first traversal of the content and media tree respectively. This will seed N number of content specified in the appSettings.json file.

The default seed key provider configuration can be found in the cache settings section..

Custom seed key providers

It is also possible to implement custom seed key providers. These are run alongside the default seed key providers on startup.

The returned keys of all the seed key providers are unioned into a single set. This means there will be no duplicates.

As mentioned above the provided keys are cached. Only the keys returned at startup will be considered seeded until the server restarts and the provider is rerun.

For a specific example of implementing a custom seed key provider, see Creating a Custom Seed Key Provider.

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).

Cache types

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.

Getting the AppCaches

If you wish to use the AppCaches in a class, you need to use Dependency Injection (DI) in your constructor:

public class MyClass
{
    private readonly IRelationService _relationService;

    private readonly IAppPolicyCache _runtimeCache;
    private readonly IAppCache _requestCache;
    private readonly IsolatedCaches _isolatedCaches;
    
    public MyClass(AppCaches appCaches, IRelationService relationService)
    {
        _relationService = relationService;
        _runtimeCache = appCaches.RuntimeCache;
        _requestCache = appCaches.RequestCache;
        _isolatedCaches = appCaches.IsolatedCaches;
    }

    // One example would be to get relations based on a node id. The RelationService hits the database each time and is not something you should call fx from a view that could get hit many times.
    // To get around that limitation you can wrap it in the cache so it only has to retrieve the value from the db once every minute (or whatever you set the timespan to).
    public void DocsService(int nodeId)
    {
        // Gets child relations from the cache if it exists, otherwise gets them and caches them for 1 min.
        var relations = _runtimeCache.GetCacheItem(
            $"ChildRelations_{nodeId}",
            () => _relationService.GetByChildId(nodeId, "umbDocument"), 
            TimeSpan.FromMinutes(1));
    }
}

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.

Adding and retrieving 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. The following retrieves an item from the cache and adds it if it doesn't already exist:

MyObject cachedItem = _appCaches.RuntimeCache.GetCacheItem<MyObject>("MyCacheKey", () => new MyObject());

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 MyObject 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.

Retrieving an item from the cache without a callback

One of the overloads of GetCacheItem doesn't specify a callback. This allows you to retrieve an item from the cache without populating it if it doesn't exist.

An example of usage:

MyObject cachedItem = _appCaches.RuntimeCache.GetCacheItem<MyObject>("MyCacheKey");

where _appCaches is injected as type AppCaches.

Inserting an item into the cache without retrieval

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. If the item already exists in the cache, it will be replaced.

• Setting up caching on the tags property.

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.

Retrieving and Adding items in the cache

You can update and insert items in the cache.

Refreshing/Invalidating cache

ICacheRefresher

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

Executing an ICacheRefresher

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.

What happens when an ICacheRefresher is executed?

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.

Events handling to refresh cache

To use the extensions add a using to Umbraco.Extensions; You can then invoke them on the injected DistributedCache object.

IServerMessenger

The server messenger broadcasts 'distributed cache notifications' to each server in the load-balanced environment. The server messenger ensures that the notification is processed in the local environment.

Getting and clearing cached content

See our example on how to cache tags.

ApplicationCache

This article will show you how to insert and delete from the runtime cache.

Scenario

For this example we're working with tags. On my site I have two tag properties:

1. One on every page using the tag group default

2. 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. The blog tags will be cached until site restart or if you publish a blog post node in the Backoffice.

Example

Why work with tags? Because they're not cached by default.. which makes them ideal for demo purposes :)

TagService

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!

API

Now that we have our service it's time to create an endpoint where we can fetch the (cached) tags.

/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.

Clearing cache on publish

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.

This section describes what ICacheRefresher and ICacheRefresher<T> are and how to use them to invalidate your cache correctly including load balanced environments

What is an ICacheRefresher

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.