Caching in custom code

The Xperience API allows developers to cache data in website code. We recommend caching in code for any frequent API calls that load significant data from the Xperience database (or other external sources). For example, caching is typically a good idea when retrieving content in the code of your live site.

The following caching API is available in the CMS.Helpers namespace:

  • CacheHelper – a static class that allows caching of data, and provides several other helper methods related to caching scenarios. Use the following methods:

    • Cache – loads data using a method specified by a delegate parameter and caches the results.
    • CacheAsync – an equivalent of the Cache method for loading and caching data in asynchronous code.
  • IProgressiveCache – interface representing a service for caching. Provides an alternative to the CacheHelper class for data caching operations. An instance of the service can be obtained using dependency injection. Use the following methods:

    • Load – loads data using a method specified by a delegate parameter and caches the results.
    • LoadAsync – an equivalent of the Load method for loading and caching data in asynchronous code.

The following code example shows how to load and cache user data from the Xperience database.

using CMS.DataEngine;
using CMS.Helpers;
using CMS.Membership;


// Ensures loading and caching of data
// Uses CacheSettings that cache the data for 10 minutes under the cache key "customdatasource|users"
// Automatically checks whether the given key is already in the cache
ObjectQuery<UserInfo> data = CacheHelper.Cache(cs => LoadUsers(cs), new CacheSettings(10, "customdatasource|users"));

// Method that loads the required data
// Called only if the data does not already exist in the cache
private ObjectQuery<UserInfo> LoadUsers(CacheSettings cs)
    // Loads all user objects from the database
    ObjectQuery<UserInfo> result = UserInfo.Provider.Get();

    // Sets a cache dependency for the data
    // The data is removed from the cache if the objects represented by the dummy key are modified (all user objects in this case)
    cs.CacheDependency = CacheHelper.GetCacheDependency("cms.user|all");    

    return result;

The caching methods check if the key specified by the CacheSettings object is in the cache:

  • If yes, the method directly loads the data from the cache.
  • If not, the code calls the method specified by the delegate parameter (LoadUsers in the example) with the CacheSettings as a parameter. The method loads the data from the database, sets a cache dependency and saves the key into the cache for the specified number of minutes

You can use the caching API when handling data anywhere in your code.


If you do not need to access or set the CacheSettings in the method that loads the data, you can use a simplified version of the caching methods. For example:

var data = CacheHelper.Cache(LoadUsers, new CacheSettings(10, "customkey"));

private ObjectQuery<UserInfo> LoadUsers()

Asynchronous caching example

using System;
using System.Threading.Tasks;

using CMS.Helpers;


// Asynchronously loads data and ensures caching
var data = await CacheHelper.CacheAsync(async cacheSettings =>
    // Calls an async method that loads the required data (implementation not included in the example)
    var result = await LoadUsersAsync().ConfigureAwait(false);

    cacheSettings.CacheDependency = CacheHelper.GetCacheDependency("cms.user|all");

    return result;
}, new CacheSettings(TimeSpan.FromMinutes(10).TotalMinutes, "customdatasource|users")).ConfigureAwait(false);


When calling the caching methods, you need to specify a CMS.Helpers.CacheSettings object as a parameter. The settings configure the cache key that stores the data. If you set the same cache key name for multiple data loading operations, they share the same cached value.

You can work with the following properties of the CacheSettings:

CacheSettings property





The number of minutes for which the cache stores the loaded data. The default value is 10 minutes.

We recommend using an interval of 1 to 60 minutes.



Sets dependencies for the cache key (use the CacheHelper.GetCacheDependency method to get the dependency object).

Make sure you always set cache dependencies, unless the CacheMinutes interval is set to an extremely short time or the cached content is predominantly static.



A boolean condition that must be fulfilled (true) in order to cache the loaded data.



Indicates whether the data should be cached (based on the cache minutes and condition).



Enables or disabled progressive caching, which ensures that multiple threads accessing the same data only load it once and reuse the result.