Views: 18367
Number of votes: 1
Average rating:

The Output Cache - When and Why

This article applies to EPiServer CMS 4.61 and later.

EPiServer provides the ability to cache output data depending on settings in the web.config file of the site. Correctly used this can greatly speed up page requests since the page requested is stored as static html, thereby liberating the server cpu from the tiresome work of putting together a dynamic page from all the bits and pieces that are usually required to compose a composite page. At a deeper level, there is another cache, the data cache, which affects communication with the database, this document does not describe the data cache.


Using Cache: When and Why

An EPiServer page is constructed using the Masterpage design, meaning every page viewable to the visitor consists of several other pages with specific content for their corresponding region. When a user logs in to a site, most pages contain personalized information to some extent. Caching in a personalized environment would be bad since we would cache a page with user specific content. The next user that sends the same request to the cached page would then retrieve the previous users information. Due to this fact (as well as performance considerations), EPiServer only caches pages accessed by anonymous users.

To effectively cache your site, you need to plan:

  • How much time should pass before a page is automatically invalidated and removed from the cache?
  • What particular requests need to be unique, thus accessing the database instead of the cache?
  • Do my site need a custom cache function?

Cache Settings in Web.config

Invalidation and caching works on a parameter value level. This means that the settings you enter in your web.config are global for the whole site and some planning is in order.  There are currently four settings that need to be considered and appropriately configured in order for your site to gain the most from output caching.

  • EPnCachePolicyTimeout

Change this value to set the number of seconds a page should be cached. This value will be set in the HTTP request policy. It will activate both client side caching and server caching (output cache).

The policy only applies to anonymous users and when the HTTP request method is GET. Apart from the timeout value, the cache will automatically be updated when changes are made to a page in EPiServer.

Recommended setting is 3600 which equals 1 hour.

Note: Not setting this value means that output caching in EPiServer will be disabled.

  • EPsCacheVaryByParams

The parameters to the page (i.e. the querystring) that the cache should be sensitive to. A parameter is one of the values that make a version of a page unique. Consider for example the EPiServer structure. In EPiServer every page with a page type of “Ordinary web page” would be considered the same page if we did not distinguish between them by using an id for each page. Therefore every page call in EPiServer includes the parameter “id” - hence “id” is an excellent candidate to use as an EpsCacheVaryByParam in web.config.

If you use the Quick Search feature from the demosite, or have added something similar on you own site, remember to add  “quicksearchquery” to the EPsCacheVaryByParams value. E.g.:

<add key=" EPsCacheVaryByParams" value="id, quicksearchquery" />
  • EPsCacheVaryByCustom

A custom value that the cache should vary by. It is only possible to set one custom value. The custom value allows you to write your own vary functions and connect them to the cache policy. See the code sample "Vary the Output cache on custom string" for more information on this topic.

When is the Cache Invalidated?

Any published change to a page means that the cache will be flushed and that the next request will need to contact the data layer. If this wasn’t the case, visitors would be able to read material that is out of date. The cache is also flushed depending on the EpnCachePolicyTimeout setting in web.config. If, for instance, this is set to 3600, the cache will be invalidated every hour, or earlier if a page has expired (since this is considered a change to the page). 


While turning on output cache can dramatically speed up your site, you need to be aware that the output cache can consume large amounts of memory. The pages in the cache will be varied by the different query string parameters. The browser version and type (also called User Agent) will also generate cached pages. Your IE6/7 and Firefox 1/2 visitors will actually generate 4 versions of the page in the cache if you keep the default EpsCacheVaryByCustom value of “browser”. The custom “browser” setting will vary on browser name and major version. If your design implementation is the same for all browsers (type and version), you can remove the “browser” value.

If your pages have large amounts of viewstate you might waste precious memory, as this will also be cached. Out of Memory exceptions can often be solved by minimizing view state and/or making sure you do not have to cache pages varied on browser types.

Only cache anonymous pages. Enabling caching on pages that require login might produce security leaks. If, for instance, an administrator with certain privileges accesses a page and this page is cached, a user with lower access rights might enter the same parameter values and read this page from the cache instead of allowing EPiServer to dynamically build the page, thereby sidestepping the access rights mechanism.

Suggested Reading

›› Technical note: Web.config 

›› FAQ: Performance issues and OutOfMemoryException

Please login to comment.