Cache dependencies
Cache dependencies inform the system whenever the source data of a cached entity changes and prompt it to revoke the corresponding cache entry.
To create dependencies between cached data and their source representation, the system uses dummy cache keys. Dummy keys are cache items without any data that target objects or groups of objects. Each time an object is modified, the system touches all dummy keys that correspond to the object, which clears all cache items targeting at least one of the touched keys.
For example, assume an Articles page with the /Articles path in the content tree of a website channel named News. On this page, there are short snippets of various articles, placed as the page’s children (/Articles/Best cities to live in, /Articles/New theme park in Georgia, etc.). As a good practice to prevent excessive database load and increase overall performance, all article snippets displayed on the page are cached.
Whenever any of the child pages changes, the cache needs to be notified and revoke the cached article snippets. Otherwise it will continue displaying outdated content. To notify the cache, we introduce a dummy cache key dependency on the key webpageitem|bychannel|News|childrenofpath|/Articles when caching the data. With this dependency set any change to child pages on the tree path /Articles under the channel News removes the cached article snippet from the cache.
Dummy cache key types
The following sections list available dummy cache keys for objects in the system.
Avoid setting dependencies on all objects of a particular type via |all. Clearing the cache every time any object of a given type changes has a high chance of significantly reducing the effectivness of your caching solution. Always prefer targeting specific objects either via code name or GUID.
Reusable content items
The following cache keys are touched when the Published version of the target reusable content item changes.
If you need to set cache dependencies for other workflow states, use the contentitem|allstates|* prefix. Where * can be substituted for any expression from the table that begins with contentitem.
Dependency on | Cache key format | Description |
All items | contentitem|all Example:
| Targets all items in the system. |
ID | contentitem|byid|<ID> Example:
| Targets an item by its database ID and optionally language variant.
|
ID and language variant | contentitem|byid|<ID>|<languageName> Example:
| |
Code name | contentitem|byname|<codeName> Example:
| Targets an item by its code name and optionally language variant. Code names of content items can be found on the Properties tab when editing items in the Content hub application.
|
Code name and language variant | contentitem|byname|<codeName>|<languageName> Example:
| |
GUID | contentitem|byguid|<GUID> Example:
| Targets an item by its GUID and optionally language variant.
|
GUID and language variant | contentitem|<GUID>|<languageName> Example:
| |
Content type | contentitem|bycontenttype|<contentType> Example:
| Targets all items of the given content type and optionally language variant.
|
Content type and language variant | contentitem|bycontenttype|<contentType>|<languageName> Example:
|
Pages
The following cache keys are touched when the Published version of the target page changes.
If you need to set cache dependencies for other workflow states, use the webpageitem|allstates|* prefix. Where * can be substituted for any expression from the table, omitting the webpageitem prefix. For example: webpageitem|allstates|all.
Dependency on | Cache key format | Description |
All | webpageitem|all Example:
| Targets all pages in the system. |
All in website channel | webpageitem|bychannel|<channelName>|all Example:
| Targets all pages under the specified website channel. |
ID | webpageitem|byid|<ID> Example:
| Targets a page by it’s database ID and optionally language variant.
|
ID and language variant | webpageitem|byid|<ID>|<languageName> Example:
| |
Code name | webpageitem|byname|<codeName> Example:
| Targets a page by its code name and optionally language variant. The code name of a page can be found on the Properties tab when viewing pages under website channels.
|
Code name and language variant | webpageitem|byname|<codeName>|<languageName> Example:
| |
GUID | webpageitem|byguid|<GUID> Example:
| Targets an item by its GUID and optionally language variant.
|
GUID and language variant | webpageitem|byguid|<GUID>|<languageName> Example:
| |
Content type in website channel | webpageitem|bychannel|<channelName>|bycontenttype|<contentType> Example:
| Targets all pages of the specified content type and optionally language variant in the given channel.
|
Content type in website channel and language variant | webpageitem|bychannel|<channelName>|bycontenttype|<contentType>|<languageName> Example:
| |
Page path in website channel | webpageitem|bychannel|<channelName>|bypath|<pagePath> Example:
| Targets a page with the specified page path, channel, and optionally language variant.
Changing a page’s path touches both the old and the new |
Page path and language variant in website channel | webpageitem|bychannel|<channelName>|bypath|<pagePath>|<languageName> Example:
| |
Page path children in website channel | webpageitem|bychannel|<channelName>|childrenofpath|<pagePath> Example:
| Targets all children on all sublevels of the specified page path. Optionally targets only specified language variants.
|
Page path children of language variant in website channel | webpageitem|bychannel|<channelName>|childrenofpath|<pagePath>|<languageName> Example:
|
Media files
Dependency on | Cache key format | Example | Description |
GUID | mediafile|<guid> | mediafile|1ced44f3-f2fc- … | Cache dependencies can only target media library files using their GUID. |
Settings
Dependency on | Cache key format | Description |
Code name | cms.settingskey|<settingCodeName> | Targets the settings specified by the given code name. |
General objects
Dependency on | Cache key format | Example | Description |
All | <object type>|all | cms.user|all | Targets all administration users in the system. |
ID | <object type>|byid|<id> | cms.user|byid|53 | Targets the administration user with the specific ID. |
Code name | <object type>|byname|<code name> | cms.user|byname|administrator | Targets the administration user with the specific code name. |
GUID | <object type>|byguid|<guid> | cms.user|byguid|1ced44f3-f2fc- … | Targets the administration user with the specific GUID. |
Form data records
The system currently does not touch any dummy cache keys when changes occur for data submitted via forms.
As a workaround, developers can prepare custom event handlers for BizFormItemEvents. Use the handler method to touch a custom cache key, and then enter the key into your cache dependencies. For example:
private void FormItem_InsertAfterHandler(object sender, BizFormItemEventArgs e)
{
// Touches a custom cache key, for example: "customformdata|bizform.contactus"
CacheHelper.TouchKey("customformdata|" + e.Item.BizFormClassName);
}