Atomic.OutputCache for Umbraco

Introduction

Atomic.OutputCache is an Atomic Toolkit package which provides an easy way to maintain Umbraco output cache. It is based on the default .NET output cache introduced in .NET 7.

Installation

It is important to choose the right version of Atomic.OutputCache before adding it to your project. Atomic.OutputCache versioning is coupled to the Umbraco version it is built for. This means that

Umbraco 11 works with Atomic.OutputCache 11, 
Umbraco 12 works with Atomic.OutputCache 12
and so on.

The code below assumes that Atomic.OutputCache with latest version 12.0.0 is being installed on Umbraco 12, and you must adapt it according to your scenario.

The easiest way to get Atomic.OutputCache installed is using the command line (CLI):

dotnet add package Atomic.OutputCache --version 12.0.0

Atomic.OutputCache can also be installed manually from NuGet using Visual Studio. If you need help with that approach, you can get more information here.

Overall, Atomic.OutputCache is a NuGet package and supports all standard ways of installing NuGet packages.

How it works

Controllers

Atomic.OutputCache provides two custom Controllers which you can use in order to take advantage of the .NET output cache.

• CachedAtomicController
  Used to cache Umbraco pages.
• CachedAtomicApiController
  Used to cache API.

Caching qualifiers

When you use the Atomic.OutputCache Controllers, you basically hook into the .NET output caching mechanism. But this doesn't mean that the output will always be cached. We have built two qualifiers which determine if the Request/Response is qualified for caching. Only when all conditions are met, the output is cached. The default cache duration is 15 minutes. 

Here you can see the default conditions of the caching qualifiers.

DefaultRequestQualifier

public static Func<OutputCacheContext, bool> DefaultRequestQualifier = (context) =>
{
	var request = context.HttpContext.Request;

	// Verify the method
	if (!HttpMethods.IsGet(request.Method) && !HttpMethods.IsHead(request.Method))
		return false;

	// Verify existence of authorization headers
	if (!StringValues.IsNullOrEmpty(request.Headers.Authorization) || request.HttpContext.User?.Identity?.IsAuthenticated == true)
		return false;

	// Verify if Umbraco Preview
	if (context.HttpContext.Request.IsPreviewRequest())
		return false;

	return true;
};

DefaultResponseQualifier

public static Func<OutputCacheContext, bool> DefaultResponseQualifier = (context) =>
{
	var response = context.HttpContext.Response;

	// Verify existence of cookie headers
	if (!StringValues.IsNullOrEmpty(response.Headers.SetCookie))
		return false;

	// Check response code
	if (response.StatusCode != StatusCodes.Status200OK)
		return false;

	return true;

};

Of course, if the default caching qualifiers don't work for you, it is possible to override them. It is also possible to change the cache duration or disable the whole caching. Please, check the Customizations section for more info.

When is the cache cleared?

The cache is cleared either when the cache duration expires (by default 15 minutes) or when any content in Umbraco is published.

Caching pages

If you don't use Umbraco Route Hijacking, you basically don't need to do anything, in order your pages to work with the output cache. That's because we have covered you and replaced the Umbraco DefaultControllerType with our CachedAtomicController.

If you use Umbraco Route Hijacking than your Controllers must inherit from CachedAtomicController, in order your pages to work with the output cache.

Caching API

There is only one requirement, if you need caching for your Umbraco API. It is that your API Controllers must inherit from CachedAtomicApiController, in order to work with the output cache. 

CachedAtomicApiController brings even more cool features because it inherits the AtomicApiController from the Atomic.Api package. Please check this page for more info.

Customizations

App settings

In the appsettings.json you can control the cache duration or disable the whole cache if you need:

 "Umbraco": {
    ...
  },
  "AtomicToolkit": {
    "OutputCache": {
      "Enabled": true,
      "CacheExpirationInMinutes": 15
    }
  }

Custom caching qualifiers

To override the default caching qualifiers, you will need an Umbraco IComposer implementation which modifies (Configure) the AtomicOutputCacheOptions. Here is an example:

public class AtomicOutputCacheComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.Configure<AtomicOutputCacheOptions>(c =>
        {
            c.DoesRequestQualify = (context) =>
            {
                // Add your logic here
            };

            c.DoesResponseQualify = (context) =>
            {
                // Add your logic here
            };
        });
    }
}