Configuring .NET client-side caching
Configure client-side caching on your .NET website by modifying the Web.config file.
Procedure
- In your .NET web application, open Web.config for editing.
- Ensure that the
configSectionssection contains asectionGroupsection with itsnameattribute set tosdl.web.delivery. - Ensure that this
sectionGroupsection contains the followingsectionsection:<section name="caching" type="Sdl.Web.Delivery.Caching.CacheConfigurationSection, Sdl.Web.Delivery.Caching" allowLocation="true" allowDefinition="Everywhere" /> - Ensure the presence of a root-level section called
sdl.web.delivery, containing acachingsection inside it. Set thedefaultHandlerattribute of thiscachingelement to the name of one of your cache handlers (see below). By default, unless configured otherwise, this cache handler will be caching the content. - 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
cacheRetriesattribute to thecachingelement 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
cacheDisableTimeattribute to thecachingelement and set it to the amount of time (in seconds) you want it to wait.
- To change the number of retries, add a
- Create a
handlerssection inside thecachingsection. Thishandlerssection must contain one or moreaddelements, specifying the various cache handlers. - For each
addsubelement you create, set thenameattribute to a unique string. One of youraddelements must have anameattribute equal to that of thedefaultHandlerattribute of thecachingelement. - For each
addsubelement you create, set thetypeattribute 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.
- If you set
typetoRedisCacheHandler, you can also specify the following further attributes:Attribute Value instanceThe name of a specific Redis instance for isolating caching data compressionA Boolean; set to falseto disable compression when writing cache data. Defaults totrue.compression_limitIf compressionis set totrueor omitted, set to the size, in number of bytes, of data before it should be compressed. Defaults to the value 256. - If you set
typetoRedisCacheHandler, also specify anendpointchild element within theaddelement, with ahostattribute set to the Redis host IP address, and aportattribute set to the Redis port. - If you set
typetoMultiLevelCacheHandler, specify the following subsections:level1-
This child element, if it has its
enabledattribute set totrue, is an in-memory, first-level cache in which items are cached for fast access. (You can setenabledtofalseto make use of threading support.) You can give thelevel1element apolicychild 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
selectionPolicyattribute to thecacheselement and set it to the valueSequential(the default value, used when the attribute is omitted, isResponseTime.)The
cachessection contains a simple list ofaddelements, representing the second-level caches. Theseaddelements have only anameattribute, which must be set to the name of one of the other caches defined in thishandlerssection. 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
cachessection contains only oneaddchild element, there is nothing to synchronize, and theselectionPolicyattribute is ignored. This setup does still improve performance, however, because there are still two levels of caching.
- To specify a global caching policy to determine cache eviction, specify a
policychild element within theaddelement (or in the case of a multi-level cache handler, within thelevel1element), and give it one of the following attributes:- Use the
slidingExpirationattribute 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
absoluteExpirationattribute 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.
- Use the
- Add further
addelements as needed, to specify further handlers. For example, you could create different kind of handlers of the typeDefaultMemCacheHandler, which differ in their expiration period, and call thenshortLivedCacheandlongLivedCache. - If you want to configure specific cache handling for specific kinds of data on your website, add a
regionssection, which is a sibling to thehandlerssection. - Within the
regionssection, create one or moreaddelements to specify the type of data you want to handle separately. Eachaddelement 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
nameattribute of one of theaddelements inside thehandlerssection (and should be different from the value in thedefaultNameattribute of thecachingelement). name-
A string that identifies the type of data (the cache region) that you want this handler to cache. Possible values include:
Value Description 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
- 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.
- Add further
addelements as needed, to specify further regions. - Save and close Web.config.
- Restart the website to apply your changes.