Is this really the version you are looking for? Kentico 8 documentation is no longer updated. Use the switch in the header to choose your Kentico version.

Caching page output

Output caching is the most effective way to increase page performance. The output cache stores the full source code of pages, i.e. the HTML and client script that the server sends to browsers for rendering. When a visitor views a page, the server caches the output code in the application's memory. Until the cache expires, the system displays the page using the cached output. As a result, the application can quickly serve requests without running the page code or communicating with SQL servers.

We recommend using output caching for all possible pages. The drawback is that cached output can become outdated on dynamic pages, or if the website's content is updated. Output caching is not suitable for pages that need to refresh frequently (for example pages that update based on user input, or have randomly generated content). You cannot disable output caching for parts of pages.

However, the system provides several solutions that allow you to cache output even for pages with dynamic content:

Caching page output on the IIS level

You can also configure IIS Output caching for your web application. IIS Output caching is completely separate from the caching mechanisms in Kentico. When clients request a page whose valid output is cached on the IIS level, the server returns the response without requiring any processing from Kentico.

Note: Kentico only supports the User-mode policy for IIS output caching. You cannot use Kernel-mode caching.

Configuring full page output caching

To use output caching for your website's pages:

Allow output caching globally:

  1. Open the Settings application.
  2. Select the System -> Performance category.
  3. Check Enable output caching.
  4. Save the settings.

Enable output caching for individual pages:

  1. Open the Pages application.
  2. Select the page in the content tree.

  3. Open the Properties -> General tab.

  4. Set the Use output cache property to Yes (in the Output cache section).
  5. Specify the number of Cache minutes. The value must be greater than 0, and determines the expiration time of the page's output cache.
  6. Save the document.

To enable output caching for all documents on your site, edit the properties of the root document. The underlying documents need to have the Use output cache property set to Inherit (this is the default state).

When a visitor requests the page, the system saves the full output code into the cache. Until the cache expires, the system displays the cached output without processing the page.

Setting output cache dependencies

The output cache of pages can become outdated when users update the website's documents and objects. Dependencies allow the system to automatically delete cached content whenever related objects are modified. The output cache provides default dependencies that clear the cache for pages:

  • When a user modifies the given document's content, properties or page template
  • Whenever a postback occurs on the page

By default, pages do NOT delete their output cache when you modify other documents or objects whose data is displayed on the page. For example, if a page contains a list of news articles and you update one of the news documents, the page displays the old content until the output cache expires.

To ensure that pages are always up-to-date, you need to set your own output cache dependencies:

  1. Edit the page in the Pages application.
  2. Switch to the Design tab.
  3. Add the Output cache dependencies web part anywhere on the page.
  4. Define the dependencies in the web part's Cache dependencies property. For more information and examples, refer to Setting cache dependencies.
  5. Click OK.

The system clears the page's output cache whenever an object specified by the dependencies is modified. With the cache cleared, the system fully processes the page on the next request, and caches the new output.

Note: If the document uses a shared page template, the dependencies apply to all pages with the given template.

Using persistent storage for the output cache

By default, the application stores the output cache of pages in the memory. Websites lose all cached content if the application restarts. You can configure the system to save the output cache in the server's file system, which provides more persistent storage.

To allow storage of output cache in the file system:

  1. Go to Settings -> System -> Performance.
  2. Type a number of minutes into the Cache output in file system (minutes) setting. The value must be greater than 0, and determines the expiration time of the output cache files.
  3. Save the settings.

To enable persistent output caching for documents:

  1. Open the Pages application.
  2. Edit individual pages on the Properties -> General tab.
  3. Set the Allow file system cache property to Yes (in the Output cache section).
  4. Save the document.

To enable file system output caching for all documents on your site, edit the properties of the root document. The underlying documents need to have the Allow file system cache property set to Inherit (this is the default state).

The output cache stores the content of the selected pages in both the application's memory and file system. When processing page requests, the system checks both types of output cache.

Deleting the output cache of pages

To manually clear the output cache of a page:

  1. Open the Pages application.
  2. Select the page in the content tree.

  3. Open the Properties -> General tab.
  4. Click Clear output cache in the Output cache section.

The page's output is removed from the cache. The next time a visitor opens the page, the system runs the page's code and saves the output into the cache again.

Caching portions of the page output

If you cannot use full output caching on a page, consider enabling Partial caching for sections of the page. The partial cache stores the HTML output of individual web parts (components that make up the content of pages). Partial caching allows the system to refresh pages on every request, but still improves performance by caching at least portions of the page output. You can set up partial caching for any number of web parts on a single page.

Note: Partial caching is not available on precompiled websites.

Web parts do not use partial caching by default. You need to allow partial caching globally for your website, and then enable it for individual web part instances.

To allow partial caching:

  1. Open the Settings application.
  2. Select the System -> Performance category.
  3. Check the Enable partial caching setting.
  4. Save the settings.

To enable partial caching for web part instances:

  1. Open the Pages application.
  2. Edit the page containing the web part on the Design tab.
  3. Configure the web part instance (double-click).
  4. Expand the Performance category, and type a number of minutes into the Partial cache minutes property. The value must be greater than 0, and determines the expiration time of the web part's partial cache.
  5. Click OK.

When a visitor opens the page, the system saves the HTML output generated by the web part into the cache. Until the cache expires, the system renders the page without processing the web part, and displays the cached output instead.

Automatic clearing of partial cache

By default, the system deletes the partial cache of web part instances:

  • When you modify the property configuration of the given web part instance. 
  • Whenever a postback occurs on the page containing the web part. 
  • Editable web parts (Editable text, Editable image) automatically clear their partial cache when the content of the parent document is updated.

You can set additional cache dependencies for web parts through the Partial cache dependencies property (in the Performance category). The system uses the dependencies to automatically clear the partial cache when the related objects are modified.

To disable the default dependencies listed above, uncheck Use default cache dependencies and enable the Preserve partial cache on postback property.

Tip: If you wish to use partial caching on pages that are not based on the portal engine, you can leverage standard ASP.NET output caching for controls.

Caching multiple output versions of pages

Web pages often display different content based on variable parameters, such as user permissions, language preferences, or the device and browser used to view the page. To compensate, the output cache stores multiple versions of pages. The system then automatically serves the appropriate cache version to visitors.

The output cache always creates separate cache items for pages according to the following variables:

  • The page path (including the virtual directory and extension)
  • The protocol in the request URL

You can configure the conditions that determine when the system uses separate or shared output cache:

  1. Open the Settings application.
  2. Select the System -> Performance category.
  3. Click Edit next to the Output cache variables setting.
  4. Enable or disable the following output cache variables:

    Cache key variable Ensures separate output cache for
    username Every logged in user. Public users share the same output cache.
    sitename
    _____________________

    Every site in the system.

    Important: Leave the sitename variable checked unless your sites all have identical content on pages with the same path.

    lang Each language version of documents.
    browser Different types of web browsers.
    cookielevel Different cookie level preferences of visitors.
    deviceprofile Different device profiles detected for visitors.
    domain Website domain names. Check to disable output cache sharing between domain aliases of sites.
    viewmode The page view modes used by Kentico, such as design, edit, preview or live site. Currently, the system only uses caching for the live site view mode.



  5. Click Save.

The system adds the selected variables and their values into the names of output cache keys. As a result, the cache keys are unique for all combinations of the required conditions.

For example, the username variable ensures that the system stores a separate version of each page's output cache for every logged in user. If you disable the username option, the output cache does not distinguish between users — if a page's output is cached for one user, the system may load the same content for all other users (depending on the remaining output cache variables).

Tip: You can configure how the system shares partial output cache through the Partial cache variables setting. The variables apply globally to the partial cache of all web parts.

Caching of personalized content

Personalized content (for example content contained in web part zones or personalized web parts) is cached per personalization variant.

For example, when a page containing a web part zone with multiple personalization variants is served, the system caches only the personalization variant fitting the current request. When another request, meeting different personalization criteria, is made, the system reuses cached data for the static segments of the page (if still available) and caches only the different personalization variant of the web part zone. This way, the system avoids storing the static segments of the page multiple times.