Configuring .NET client-side caching

Configure client-side caching on your .NET website by modifying the Web.config file.

Procedure

  1. In your .NET web application, open Web.config for editing.
  2. Ensure that the configSections section contains a sectionGroup section with its name attribute set to sdl.web.delivery.
  3. Ensure that this sectionGroup section contains the following section section:
    <section name="caching" type="Sdl.Web.Delivery.Caching.CacheConfigurationSection, Sdl.Web.Delivery.Caching" allowLocation="true" allowDefinition="Everywhere" /> 
  4. Ensure the presence of a root-level section called sdl.web.delivery, containing a caching section inside it. Set the defaultHandler attribute of this caching element to the name of one of your cache handlers (see below). By default, unless configured otherwise, this cache handler will be caching the content.
  5. By default, the client attempts to connect to a cache for a predefined number of times (5 times) before giving up on that cache for a predefined amount of time (5 minutes). You can change both how often it should try connecting to the cache, and how long it should wait to make a new attempt to connect:
    • To change the number of retries, add a cacheRetries attribute to the caching element and set it to the number of times you want it to attempt to reconnect to a cache before giving up on it.
    • To change how long the client waits before making a new attempt (or series of attempts) to connect to a cache, add a cacheDisableTime attribute to the caching element and set it to the amount of time (in seconds) you want it to wait.
  6. Create a handlers section inside the caching section. This handlers section must contain one or more add elements, specifying the various cache handlers.
  7. For each add subelement you create, set the name attribute to a unique string. One of your add elements must have a name attribute equal to that of the defaultHandler attribute of the caching element.
  8. For each add subelement you create, set the type attribute to one of the following values:
    NullCacheHandler
    Perform no caching at all
    DefaultMemCacheHandler
    Perform default ASP.NET in-memory caching
    CoreMemCacheHandler
    Perform .NET Core in-memory caching
    RedisCacheHandler
    Perform .NET Core distributed caching using a Redis database
    MultiLevelCacheHandler
    Perform multi-level caching.
  9. If you set type to RedisCacheHandler, you can also specify the following further attributes:
    AttributeValue
    instanceThe name of a specific Redis instance for isolating caching data
    compressionA Boolean; set to false to disable compression when writing cache data. Defaults to true.
    compression_limitIf compression is set to true or omitted, set to the size, in number of bytes, of data before it should be compressed. Defaults to the value 256.
  10. If you set type to RedisCacheHandler, also specify an endpoint child element within the add element, with a host attribute set to the Redis host IP address, and a port attribute set to the Redis port.
  11. If you set type to MultiLevelCacheHandler, specify the following subsections:
    level1

    This child element, if it has its enabled attribute set to true, is an in-memory, first-level cache in which items are cached for fast access. (You can set enabled to false to make use of threading support.) You can give the level1 element a policy child element to specify a caching policy (see below) for this in-memory cache.

    caches

    This section represents a list of one or more second-level caches.

    By default, a multi-level cache prioritizes and prefers second-level caches with a fast response time over second-level caches with a slower response time. That is, it uses response time to determine which second-level cache it approaches first. If you want the multi-level cache to approach the second-level caches in the order in which you specify them here, ignoring response time, add a selectionPolicy attribute to the caches element and set it to the value Sequential (the default value, used when the attribute is omitted, is ResponseTime.)

    The caches section contains a simple list of add elements, representing the second-level caches. These add elements have only a name attribute, which must be set to the name of one of the other caches defined in this handlers section. You can specify any combination of caches, regardless of their types, so long as you do not include a multi-level cache in the list. The client automatically synchronizes cached content across these caches.

    If the caches section contains only one add child element, there is nothing to synchronize, and the selectionPolicy attribute is ignored. This setup does still improve performance, however, because there are still two levels of caching.

  12. To specify a global caching policy to determine cache eviction, specify a policy child element within the add element (or in the case of a multi-level cache handler, within the level1 element), and give it one of the following attributes:
    • Use the slidingExpiration attribute to remove items from the cache only if they are not being used for a set period of time. That period, in seconds, is the value of the attribute, and it defaults to the value 300.
    • Alternatively, use the absoluteExpiration attribute to remove items from the cache after a set period of time, regardless of whether they are being used or not. That period, in seconds, is the value of the attribute, and it has no default.

    If neither attribute is specified, a sliding expiration policy is applied by default, with its default timeout period of 300 seconds.

  13. Add further add elements as needed, to specify further handlers. For example, you could create different kind of handlers of the type DefaultMemCacheHandler, which differ in their expiration period, and call then shortLivedCache and longLivedCache.
  14. If you want to configure specific cache handling for specific kinds of data on your website, add a regions section, which is a sibling to the handlers section.
  15. Within the regions section, create one or more add elements to specify the type of data you want to handle separately. Each add element has the following attributes:
    cacheName

    The name of the cache handler to use for this type of data. The value must be that of a name attribute of one of the add elements inside the handlers section (and should be different from the value in the defaultName attribute of the caching element).

    name
    A string that identifies the type of data (the cache region) that you want this handler to cache. Possible values include:
    ValueDescription
    CIL-BROKERCache region that is used whenever the CIL makes a Content Broker API request
    CIL-DYNAMICCache region that is used whenever the CIL uses the Dynamic Content Delivery API
    CIL-LINKINGCache region that is used whenever the CIL makes a Linking API request to dynamically resolve links
    CIL-INTERNALCache region for anything else the CIL may go that uses a cache for performance reasons
  16. If you want the caching policy for this type of data to be different from the default policy, specify a region-specific caching policy to determine cache eviction, just like you did in step 10.
  17. Add further add elements as needed, to specify further regions.
  18. Save and close Web.config.
  19. Restart the website to apply your changes.