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)

• 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 on the local environment.

Getting and clearing cached content

See our example on how to cache tags.

ApplicationCache

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.

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

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.

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

using System;
using System.Collections.Generic;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PublishedCache;
using Umbraco.Extensions;

namespace Doccers.Core.Services.Implement;

public class CacheTagService : ICacheTagService
{
    private readonly ITagQuery _tagQuery;
    private readonly IAppPolicyCache _runtimeCache;

    public CacheTagService(ITagQuery tagQuery, AppCaches appCaches)
    {
        _tagQuery = tagQuery;
        // Get the RuntimeCache from appCaches
        // and assign to our private field.
        _runtimeCache = appCaches.RuntimeCache;
    }

    public IEnumerable<TagModel> GetAll(
        string group,
        string cacheKey,
        TimeSpan? timeout = null)
    {
        // GetCacheItem will automatically insert the object
        // into cache if it doesn't exist.
        return _runtimeCache.GetCacheItem(cacheKey, () =>
        {
            return _tagQuery.GetAllTags(group);
        }, timeout);
    }
}

As you can see we inherit from the ICacheTagService interface. All that has is:

using System;
using System.Collections.Generic;
using Umbraco.Cms.Core.Models;

namespace Doccers.Core.Services;

public interface ICacheTagService
{
    IEnumerable<TagModel> GetAll(
        string group,
        string cacheKey,
        TimeSpan? timeout = null);
}

The interface was created to better register it so we can use dependency injection. You can register your own classes like so:

using Doccers.Core.Services;
using Doccers.Core.Services.Implement;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

namespace Doccers.Core;

public class Composer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.AddScoped<ICacheTagService, CacheTagService>();
    }
}

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.

using System;
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using Doccers.Core.Services;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Web.Common.Controllers;


namespace Doccers.Core.Controllers.Api;

public class TagsController : UmbracoApiController
{
    private readonly ICacheTagService _tagService;

    // Dependency injection rocks!
    public TagsController(ICacheTagService tagService)
    {
        _tagService = tagService;
    }

    [HttpGet]
    public IEnumerable<TagModel> GetDefaultTags()
    {
        // As mentioned earlier we want tags from "default"
        // group to be cached for a minute.
        return _tagService.GetAll("default", "defaultTags",
            TimeSpan.FromMinutes(1));
    }

    [HttpGet]
    public IEnumerable<TagModel> GetBlogTags()
    {
        // If you don't specify a TimeSpan the object(s)
        // will be cached until manually removed or
        // if the site restarts.
        return _tagService.GetAll("blog", "blogTags");
    }
}

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

using System.Linq;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Notifications;

namespace Doccers.Core;

public class Notification : INotificationHandler<ContentPublishedNotification>
{

    private readonly IAppPolicyCache _runtimeCache;

    public Notification(AppCaches appCaches)
    {
        _runtimeCache = appCaches.RuntimeCache;
    }

    public void Handle(ContentPublishedNotification notification)
    {

        if (notification.PublishedEntities.Any(x => x.ContentType.Alias == "blogPost"))
        {
            _runtimeCache.ClearByKey("blogTags");
        }
    }
}

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:

public void Compose(IUmbracoBuilder builder)
{
    builder.Services.AddScoped<ICacheTagService, CacheTagService>();

    builder.AddNotificationHandler<ContentPublishedNotification, Notification>();

}

Awesome! Now we have set up caching on our tags - making the site a bit faster. :)