Hide menu Last updated: Apr 12 2016

The IObjectInstanceCache and ISynchronizedObjectInstanceCache interfaces expose the built-in cache system with custom dependency and eviction policies. Episerver CMS and Commerce use this to cache both content and system data, and it can be used to cache custom data. The ISynchronizedObjectInstanceCache interface synchronizes cache removal among servers in a load-balanced environment using the event system.

Note: If you were using the CacheManager class in CMS, you should take a dependency on ISynchronizedObjectInstanceCache instead, because the new interface provides the same functionality. The IObjectInstanceCache supersedes IRuntimeCache (that was previously only used by CMS) because it supports different cache implementations by abstracting the CacheDependency class and other things. The underlying default implementation of IObjectInstanceCache still relies on HttpRuntime.Cache.


Use the CacheEvictionPolicy class for object caching, because it is de-coupled from any specific cache implementation. CacheEvictionPolicy is immutable so you can re-use existing instances of the class. (The CacheDependency class is tightly coupled to the HttpRuntime implementation and if you want to have a custom cache implementation you cannot rely on CacheDependency.) The following example shows how to use CacheEvictionPolicy.

public void AddToCache(string key, object val)
    // If you don't care about specific cache management, use CacheEvictionPolicy.Empty
    _cache.Insert(key, val, CacheEvictionPolicy.Empty);

    // To enable sliding expiration for 10s, depending on "otherKey"
    _cache.Insert(key, val, new CacheEvictionPolicy(
        new string[] { "otherKey" }, // Cache key dependency
        new TimeSpan(0, 0, 10),      // Always a timespan for timeouts

Master keys

When you need to define a common dependency for cached data, create a master dependency (or master key) with CacheEvictionPolicy, which automatically adds a list of key names to the cache as regular cache entries. By doing so, you do not need to add code to conditionally add these entries before you insert specific data into the cache.

In the following example, the difference between the cache key dependency and the master key dependency is that if there is no otherKey in the cache then the data is not inserted. If there is no entry with MasterKey, then it adds a dummy value with the given key, thus allowing the data to be inserted successfully.

public void AddToCacheWithMasterDependency(string key, object val)
    // To enable absolute expiration for 5 minutes, depending on "otherKey" and master key dependency to "MasterKey"
    _cache.Insert(key, val, new CacheEvictionPolicy(
        null,                         // No file dependencies
        new string[] { "otherKey" },  // Cache key dependency
        new string[] { "MasterKey" }, // Master key dependency
        new TimeSpan(0, 5, 0),        // Always a timespan for timeouts

Configuring caching of files

You can add cache information to the response headers at request of static files so the client can cache files and not have the web server serve at each request, significantly reducing the total request time for a client.

You can set the staticFile section of web.config on a location level. For the <staticFile> section to be available, you have to add it to <configSections> first:

<section name="staticFile" type="EPiServer.Framework.Configuration.StaticFileSection, EPiServer.Framework" allowLocation="true" />

This staticFile section controls the Expires and Cache-Control cache header directives. You can set different expiration times depending on the path to the static file. The staticFile configuration is used by both the StaticFileHandler that delivers files from Virtual Path Providers and by the media system in CMS. Files delivered by IIS, such as CSS and other resources on the website, are configured using standard IIS configuration settings.


<!--Configures expiration for files in CMS/VPP-->
<staticFile expirationTime="12:0:0" />

<!--Configures expiration in IIS-->
   <!--Configures client headers for static files from IIS-->
       <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="1.00:00:00"></clientCache>
   <!--Configures output and kernel caching for ALL images (both CMS and IIS)-->
        <add extension=".gif" policy="CacheUntilChange" kernelCachePolicy="CacheUntilChange" duration="0.00:01:00" location="Any" />
        <add extension=".png" policy="CacheUntilChange" kernelCachePolicy="CacheUntilChange" duration="0.00:01:00" location="Any" />
        <add extension=".js" policy="CacheUntilChange" kernelCachePolicy="CacheUntilChange" duration="0.00:01:00" location="Any" />
        <add extension=".css" policy="CacheUntilChange" kernelCachePolicy="CacheUntilChange" duration="0.00:01:00" location="Any" />
        <add extension=".jpg" policy="CacheUntilChange" kernelCachePolicy="CacheUntilChange" duration="0.00:01:00" location="Any" />
        <add extension=".jpeg" policy="CacheUntilChange" kernelCachePolicy="CacheUntilChange" duration="0.00:01:00" location="Any" />


For <staticFile>  section to be available, first you have to add it to <configSections>:

<section name="staticFile" type="EPiServer.Framework.Configuration.StaticFileSection, EPiServer.Framework" allowLocation="true" />

Thanks for your feedback, Maris, I have added that info to the topic.

If you are looking to alter the caching of Media files then check out this post.