Commerce Engine caching

From release 9.2 and later, the Sitecore XC solution supports two cache providers:

  • Memory - recommended for single-server deployments.

  • Redis - recommended for distributed deployments.

Each Commerce Engine service role has a cache store.  The cache store contains multiple caches, which are grouped into data cache stores, according to the artifact store ID associated with their environment. Environments that have the same artifact store ID share the same cache data within the cache store, but their cache data is isolated from environments that have different artifact store IDs.

Note

Sitecore XC caching follows an opt-in model, meaning that caching is disabled by default. You must explicitly enable caching for any commerce entities and non-entities that you want to cache through policy configuration.

Memory caching

For single-server deployments, you can use the Memory cache provider to cache commerce items. All Commerce Engine service roles hosted on the machine use the memory cache store to retrieve cached data, based on the environment ID specified in the request header.

Diagram showing cache stores for in-memory caching.

Distributed caching

For scaled deployments, you can use the Redis cache provider to host a centralized cache store for the system. Each Commerce Engine service role can access the cache store and retrieve cached data, based on the environment ID specified in the request header.

Diagram shows that shows the Redis cache stores for distributed caching.

Cache provider configuration

The cache provider configuration is stored in the Commerce Engine config.json file. You must enable one cache provider, and you can only enable one cache provider at a given time. The Redis cache provider is enabled by default.

},
  "Caching": {
    "Memory": {
      "Enabled": false,
      "CacheStoreName": "Commerce-Memory-Store"
    },
    "Redis": {
      "Enabled": true,
      "CacheStoreName": "Commerce-Redis-Store",
      "Options": {
        "Configuration": "localhost",
        "InstanceName": "Redis"
    }
 }

You can configure the following parameters for your cache provider:

Cache provider

Parameter

Description

Memory

CacheStoreName

Sets the name of the cache store.

EvictionPercentage

Sets the threshold at which the cache removes the least recently used entries to make room for new entries. Default value is 0.2.

MaxSizeInBytes

Sets the maximum size of the cache store, in bytes. The default value is 9223372036854775807.

PollingInterval

Sets the maximum time after which the cache store updates its memory statistics. The default value is 2 minutes.

SizeLimit

Sets the maximum size for a cache within the cache store. The default value is Null.

ExpirationScanFrequency

Sets the minimum length of time between scans for expired items. The default value is 1 minute.

CompactionPercentage

Sets the percentage of cache data to compact when the maximum size is exceeded; the default value is 0.

Redis

CacheStoreName

Sets the name of the cache store.

Configuration

Specifies the connection string for the Redis cache provider.

Note

You can append additional Redis configuration options to the connection string to meet specific deployment requirements.

InstanceName

Sets the Redis instance name.

Entity caching configuration

The Commerce Core plugin provides the policies that govern entity caching for the Commerce Engine.

The EntityCachingPolicy policy defines caching behavior for commerce entities. You can configure an entity caching policy for each entity that you want to cache, as shown in the following example:

{ 
  "$type": "Sitecore.Commerce.Core.EntityCachingPolicy, Sitecore.Commerce.Core", 
  "EntityFullName": "Sitecore.Commerce.Plugin.Content.ContentPath", 
  "AllowCaching": true, 
  "Priority": "Normal", 
  "Expiration": 86400000, 
  "HasNegativeCaching": true, 
  "CacheName": "ContentPaths", 
  "EntityIdPrefix": "Entity-ContentPath" 
} 

The following table describes the parameters in the entity caching policy configuration:

Parameter

Description

EntityFullName

Sets the full name of the entity type to be cached.

AllowCaching

Enables or disables caching for the entity. The default value is true.

Priority

Sets the priority for the cache entry. Possible values are:

  • Low

  • Normal

  • High

  • NeverRemove

Expiration

Sets the length of time after which a cache entry expires, in milliseconds.

AbsoluteExpirationRelativeToNow

Sets the length of time after which a cache entry expires relative to the current timestamp, in milliseconds.

SlidingExpiration

Sets the length of time after which a cache entry expires if it has not been accessed, in milliseconds.

HasNegativeCaching

Enables or disables negative caching for the entity type. Negative caching prevents repeated calls to the SQL Server for entities that have been previously requested and do not exist.

CacheName

Sets the name of the cache for this entity type.

EntityIdPrefix

The prefix to identify the entity type.

Caching policy set

The Sitecore XC solution includes a caching policy set file that contains system caching configuration. All default environments included with the Sitecore XC solution (for example, Habitat) reference the default caching policy set.

The Plugin.Caching.PolicySet-1.0.0.json file is stored in the wwwroot\data\Environments folder and contains caching policies for commerce entities and non-entities.

The caching policy set contains policy configuration for the following commerce entity caches:

  • Content paths cache

  • Content items cache

  • Shops cache

  • Policy Sets cache

  • Entity Indexes cache

  • Promotions cache

  • Promotion Books cache

  • Catalogs cache

  • Categories cache

  • Relationship Definitions cache

  • Sellable Items cache

  • Inventory Sets cache

  • Price Cards cache

  • Price Books cache

  • Localization Entities cache

  • Versioning Entities cache

  • Workflows cache

In addition, the Caching policy set contains caching policy configuration for the following non-entity items:

  • Management cache (caches item model objects from the Commerce Control Panel)

  • Custom Relationships cache (caches a list of custom relationships)

  • Associated/Disassociated Catalogs cache (caches a list of associated and disassociated catalogs for each promotion book)

  • Localized Terms cache (caches a list of commerce localized terms)

  • Customer Statuses cache (caches a list of localized customer statuses)

  • Returns cache policy (caches a list of localized reasons-for-returns)

Caching API commands

You administer caching through the CommerceOps API. You can use the Postman samples (located in the SitecoreCommerce_DevOps collection) to execute the caching commands.

Note

The ClearEnvironmentCache(environmentName) command is deprecated from Sitecore XC release 9.2.

The following table lists the API commands for caching:

Command

Description

GetCacheStores()

Retrieves all the cache stores in the system.

GetCacheStore(name)

Retrieves a named cache store.

GetDataCacheStore(name)

Retrieves the caches within the cache store that match the environment's artifact store ID.

GetCache(name)

Retrieves a named cache. If the cache is not present in the cache store, the system returns a 404 error.

ClearCacheStore()

Clears all the caches within the cache store.

This command is not supported for the Redis cache provider. You must clear the cache store directly in Redis.

ClearDataStoreCaches()

Clears all caches in the data store. The Commerce Engine determines the data store from the environment name specified in the request header.

This command is not supported for the Redis cache provider. You must clear the data store directly in Redis.

ClearCache(name)

Clears the named cache within a cache store.

This command is not supported for the Redis cache provider. You must clear the cache directly in Redis.