• Documentation
  Kentico development modelsInstallationUsing the Kentico interfaceDeveloping websitesConfiguring KenticoManaging usersSecuring websitesDeploying websitesManaging website contentMultilingual websitesMacro expressionsExternal utilitiesIntegrating 3rd party systemsCustom developmentE-commerce featuresOn-line marketing featuresCommunity featuresRelease notes - Kentico 12
• Tutorial
  Getting started with KenticoUsing the Kentico interfaceSelecting your tutorial pathSite development overviewPortal Engine developmentMVC developmentMVC business tutorialResource hub for marketers
• API Examples
  Content managementOn-line marketingE-commerceSocial and CommunityDevelopmentConfiguration

By default, the system allows you to construct the cache key using the following request variables (extension methods for IOutputCacheKeyOptions objects):

Example – Configuring output caching

The following steps describe how to cache multiple versions of personalized output using custom strings:

1. Edit your project's Global.asax.cs file and override the GetVaryByCustomString⁠ (opens in a new tab) method.

   • The method's custom parameter contains the string that you set in the VaryByCustom property of OutputCache attributes in your controllers.

   • For each custom string, you need to define the caching requirements – use VaryBy methods on an IOutputCacheKeyOptions object to create a set of request variables according to which the output cache needs to vary.

     C#

     Copy

     using System;
     using System.Web;
     
     using Kentico.Web.Mvc;
     using Kentico.OnlineMarketing.Web.Mvc;

     C#Example

     Copy

     public override string GetVaryByCustomString(HttpContext context, string custom)
     {
         // Creates the options object used to store individual cache key parts
         IOutputCacheKeyOptions options = OutputCacheKeyHelper.CreateOptions();
     
         // Selects a caching configuration according to the current custom string
         switch (custom)
         {
             case "Default":
                 // Sets the variables that compose the cache key for the 'Default' VaryByCustom string
                 options
                     .VaryByHost()
                     .VaryByBrowser()
                     .VaryByUser();
                 break;
     
             case "OnlineMarketing":
                 // Sets the variables that compose the cache key for the 'OnlineMarketing' VaryByCustom string
                 options
                     .VaryByCookieLevel()
                     .VaryByPersona()
                     .VaryByABTestVariant();
                 break;
         }
     
         // Combines individual 'VaryBy' key parts into a cache key under which the output is cached
         string cacheKey = OutputCacheKeyHelper.GetVaryByCustomString(context, custom, options);
     
         // Returns the constructed cache key
         if (!String.IsNullOrEmpty(cacheKey))
         {
             return cacheKey;
         }
     
         // Calls the base implementation if the provided custom string does not match any predefined configurations
         return base.GetVaryByCustomString(context, custom);
     }

     Important

     The cache keys created in the example above ensure caching for a broad range of variables contained within each request. This may be unnecessary for your website. For optimal caching, you need to prepare output cache variables tailored according to personalization conditions that you use on the site or individual pages.

     For example, pages that check for contact personas in their personalization condition only require the persona identifier in the cache variables, and you can share the cached content for other variables, such as contact groups to which the contacts belong. On the other hand, strongly personalized pages with dynamic content may require separate cache versions for every contact.

     You always need to balance website performance, memory usage on the server, and the risk of displaying incorrect cached content.

2. Edit the controller classes that serve personalized content on your MVC site.

3. Set the VaryByCustom property of OutputCache attributes to one of the specified configurations according to the action's caching requirements.

   C#Example

   Copy

   using System.Web.Mvc;
   
   using CMS.ContactManagement;
   
   using LearningKit.Models.Personalization;
   
   namespace LearningKit.Controllers
   {
       public class PersonalizationController : Controller
       {
           /// <summary>
           /// Gets the current contact, if contact tracking is enabled for the connected Kentico instance.
           /// </summary>
           private ContactInfo CurrentContact => ContactManagementContext.GetCurrentContact();
   
           /// <summary>
           /// Displays a page with a personalized greeting.
           /// The content depends on whether the current contact belongs to the "YoungCustomers" persona.
           /// Caches the output for 10 minutes, with different cache versions defined by the "OnlineMarketing" custom string.
           /// The "OnlineMarketing" configuration separately caches each combination of persona and AB test variant variables.
           /// </summary>
           [OutputCache(Duration = 600, VaryByCustom = "OnlineMarketing")]
           public ActionResult PersonalizedGreeting()
           {
               CurrentContactViewModel model;
   
               // If on-line marketing is disabled, CurrentContact is null
               if (CurrentContact != null)
               {
                   model = new CurrentContactViewModel(CurrentContact);
               }
               else
               {
                   model = null;
               }
   
               return View(model);
           }
       }
   }

The application now caches separate versions of action output based on your custom variables. This ensures that visitors do not receive incorrect cached content when viewing personalized pages.

Varying the output cache using additional variables

In addition to the cache variables provided by the system, you can vary the cache key based on any accessible request variable.

There are two ways to extend the general support provided by Kentico:

• Implement additional extension methods for IOutputCacheKeyOptions
• Modify the constructed cache key by appending additional request variables

Implementing additional cache key parts

You can extend the provided support by implementing additional cache key parts for IOutputCacheKeyOptions. This approach allows for easy reusability of the implemented methods across multiple projects.

Cache key parts consist of:

• A class implementing the IOutputCacheKey interface. The interface defines members necessary to implement additional cache key parts.
• An extension method for IOutputCacheKeyOptions. The method needs to add an instance of the IOutputCacheKeyobject to the cache key part collection of the options object by calling IOutputCacheKeyOptions.AddCacheKey.

The following sample demonstrates the implementation of a cache key that varies cached content based on a contact's gender.

Create a corresponding extension method for IOutputCacheKeyOptions. The method adds an instance of the class to an IOutputCacheKeyOptions object using the AddCacheKeymethod.

You can now use the ContactGender variable when building cache keys in the site's GetVaryByCustomString implementation.

Modifying the constructed cache key

An alternative approach to implementing reusable extension methods is constructing the cache key using OutputCacheKeyHelper.GetVaryByCustomString and further customizing it by directly appending additional request variables.

The following example implements a custom GetContactGroupsCacheKey method that returns a semicolon-separated list of all contact groups to which the current contact belongs. The string is appended to the cache key constructed by the GetVaryByCustomString helper method, adding another level of variance to the output cache.