Configure HTML caching

Current version: 10.1

The HTML cache is an output cache that caches renderings, not whole pages. You use the HTML cache to improve the performance of websites.

To enable the HTML output cache:

Patch the site specification of predefined sites in the sites node of the \App_Config\Sitecore\CMS.Core\Sitecore.Sites.config file and set the cacheHtml property of sites to true to enable the HTML output cache for that site.

Note

The website default site set up during installation is already there. You must specify this setting for any site you create yourself and that you want HTML caching for.

Note

You can specify the size of each cache in the htmlCacheSize property of a site node.
Add caching options to the renderings Sitecore caches output for. You can do this in two ways:
- Locally by specifying the options every time you use a rendering. To do this, open the item in the Content Editor, and on the Presentation tab, click Details, and then click the rendering you want to set options for.
- Globally by specifying the options in the definition item of the rendering. This is then the default setting for all uses of this rendering. To do this, open the rendering definition item in the sitecore/Layout/Renderings part of the content tree, and navigate to the options in the Caching section.
The options are:
- Cacheable
  
  Specifies if Sitecore caches the rendering or not.
- Clear on Index Update
  
  Sitecore clears the cache when it updates the content search index.
  
  This is important if your Sitecore instance uses HTML caching for renderings, controls, or sublayouts that contain code, and this code depends on an index. For more information, see Index-dependent HTML caching .
- Vary by Data
  
  Sitecore caches output based on the item accessed. This is useful when content is highly consistent, for example: headers and footers.
- Vary by Device
  
  Sitecore caches output for each device separately.
- Vary by Login
  
  Sitecore caches two copies of the output: one for authenticated users, and one for unauthenticated users.
- Vary by Parameters
  
  Sitecore caches output for each parameter the rendering accepts.
- Vary by Query String
  
  Sitecore caches output for each unique combination of query string parameters.
- Vary by User
  
  Sitecore caches output for each authenticated user.
- Cache Cleaning Behavior
  
  This setting specifies the cache clearing behavior of Sitecore and the relation to publishing operations. The possible values and the impact are described in the the next section.

The Cache Cleaning Behavior setting

This setting specifies how Sitecore clears the cache when you update and publish content. There are three values you can set:

Clear On Publish

Sitecore clears the cache for the rendering every time you publish. This is the case for all sites you configure with the value of the cacheHtml property set to true. The publish:end event handler is configured like this in a standard installation:
RequestResponse
```
<event name="publish:end">
<handler type="Sitecore.Publishing.SmartHtmlCacheClearer, Sitecore.Kernel" method="ClearCache" resolve="true" />
...
</event>
```
If you do not want Sitecore to clear the cache for a site when you publish, you can add the preventHtmlCacheClear attribute to the site definition like this:
RequestResponse
```
<site name="custom_website" cacheHtml="true" preventHtmlCacheClear="true" … />
```
Clear On Content Update

This is the most complicated scenario, and it is described in a separate section.
Do Not Clear

Sitecore does not clear the output cache on publishing.

Using the Clear On Content Update option

When you specify this as the value of the Cache Cleaning Behavior setting, Sitecore only clears the output cache for this rendering when the associated content changes. This is the case for all sites you configure with both the cacheHtml property and the enablePartialHtmlCacheClear property set to true.

If you configure your site with enablePartialHtmlCacheClear set to false, this option is ignored, and Sitecore clears the rendering cache on every publish. The option uses the value of the Content Dependencies field of the rendering. Based on the value of this field, Sitecore maintains a map in memory that correlates all the content dependencies with the rendering cache key. When content changes (either locally or in a remote database), Sitecore looks at the map and clears all related cache entries.

The following handler is configured for the item:saved,item:saved:remote, item:deleted, and item:deleted:remote events in a standard installation:

RequestResponse

<handler type="Sitecore.Publishing.PartialHtmlCacheClearer, Sitecore.Kernel" method="OnItemEvent" resolve="true" />

Configure content dependencies for an MVC rendering has more information.

Example scenario

This example shows the behavior when you have an item structure like this:

You also have a page with a single rendering that uses the Content Item as the data source.

The following table shows which items cause output cache clearing for this rendering when they are published, and how this depends on the value you specify in the Content Dependencies field:

Context Dependencies specification	Items that cause cache clearing when they are published	Notes
	Content Item	If you do not specify anything, the data source item is used.
	Sitecore Content Home	The Content Item item does not trigger cache clearing.
	Home
	Sibling Item
	Home Sibling Item
	Content Item All items referenced by Content Item	Sitecore uses the Link database for the references.
	Sibling Item All items referenced by Content Item	Sitecore uses the Link database for the references. The related items are calculated for the datasource item only - not for the sibling items.
	Content Item All items referenced by Content Item	Sitecore uses the Link database for the references. When used on its own, Recursive Related Items have the same result as Related Items.
	Sibling Item All items references by Sibling Item	Sitecore uses the Link database for the references. Unlike Related Items, the Recursive Related Items when used with other options (such as Siblings, Sitecore calculates the references against the items produced by that other option instead of the data source itself.
	Child Item
	Child Item Descendant Item

The cache is cleared automatically when the Rendering definition item is published. This is to ensure that the cache is always up to date with its settings and options, and the value of the Content Dependencies field has no influence on this.

If the data source is a query that returns multiple data source items, Sitecore applies the above for all the data source items.

Do you have some feedback for us?

If you have suggestions for improving this article,