Kentico 12: Design Patterns Part 15 - Output Caching and User Context
Tags: kentico, mvc, aspnet, caching
Published: 2019-10-14 13:32:09

---
title: Kentico 12: Design Patterns Part 15 - Output Caching and User Context
published: true
description: Learn how to leverage output caching in our Kentico 12 MVC applications, specifically scenarios with User Context rendered in the response HTML.
tags: kentico, mvc, aspnet, caching
series: Kentico 12 - Design Patterns
---

![Mugs with first names](https://thepracticaldev.s3.amazonaws.com/i/eogjlsquhic010xoira1.jpg)

<figcaption>Photo by <a href="https://unsplash.com/@waldemarbrandt67w">Waldemar Brandt</a> on <a href="https://unsplash.com">Unsplash</a></figcaption>

If you are building a [Kentico 12 MVC application](https://docs.kentico.com/k12sp/developing-websites/mvc-development-overview) and you want to increase your page response performance, you might be looking for a solution that has been within arms reach on all Kentico Portal Engine sites - Output Caching ⚡.

In Portal Engine, output caching was simple as [checking a box to enable output caching](https://docs.kentico.com/k12sp/configuring-kentico/configuring-caching/caching-on-portal-engine-sites/caching-page-output).

While it's not that simple in an MVC application, Kentico does provide [clear solutions](https://docs.kentico.com/k12sp/configuring-kentico/configuring-caching/caching-the-output-of-personalized-content) for enabling and configuring output cache for your site.

Let's quickly review what output caching is and then discuss a common scenario that complicates things - output caching and user context 😊.

---

## Output Caching

[Microsoft's documentation](https://docs.microsoft.com/en-us/aspnet/mvc/overview/older-versions-1/controllers-and-routing/improving-performance-with-output-caching-cs) explains output caching through a simple real-world scenario:

> Imagine, for example, that your ASP.NET MVC application displays a list of database records in a view named `Index`. Normally, each and every time that a user [loads a page that] invokes the Controller action that returns the `Index` view, the set of database records must be retrieved from the database by executing a database query.

> If, on the other hand, you take advantage of the output cache then you can avoid executing a database query every time any user invokes the same controller action. The view can be retrieved from the cache instead of being regenerated from the controller action. Caching enables you to avoid performing redundant work on the server.

So, output caching allows us to cache the rendered HTML output of our Controller actions. When the next request arrives for the same content, a little work is performed on the server to analyze the request, but no Controller actions are executed - the HTML is served from memory 😀.

---

### Benefits

The benefits here are massive 💪!

Imagine we have a Controller `Index()` action that is called when a user visits our home page:

```csharp
public class HomeController : Controller
{
    public ActionResult Index()
    {
        var topProducts = SKUInfoProvider.GetSKUs()...;

        var topBlogPosts = BlogPostPageProvider.GetBlogPostPages()...;

        var featuredSales = partnerService.GetSalesViaHTTPRequest("...");

        var viewModel = new IndexViewModel(
            topProducts,
            topBlogPosts,
            featuredSales);

        return View(viewModel);
    }

    [ChildActionOnly]
    public ActionResult UserProfileIcon()
    {
        // ...
    }
}
```

> This code is for explanation purposes only. I definitely don't recommend putting a bunch of data-access in our Controllers.

> Instead, we should keep our Controller classes thin and declarative 👍. Check out the section titled "Thin Controllers" in my blog post _Kentico 12: Design Patterns Part 3 - Tips and Tricks, Application Structure_:

> {% link seangwright/kentico-12-design-patterns-part-3-tips-and-tricks-application-structure-1l2o %}

Every time the home page is loaded, we have 2 calls to the database (for `topProducts` and `topBlogPosts`), 1 call to an external web service (for `featuredSales`), and finally a call to the `UserProfileIcon()` child action to get the user specific information.

> You can read more about "child actions" [on Phil Haack's blog post](https://haacked.com/archive/2009/11/18/aspnetmvc2-render-action.aspx/).

What are the problems here?

- ❌ That's a lot of work, and it will slow down the response time of a request for the home page.
- ❌ It won't scale well as the number of visitors to the site increases.
- ❌ It opens up opportunities for failures to load the page at all if there is and issue connecting to the database or the web service.

I've previously written about query caching patterns, and we could definitely use those here to cache the results of our database and web service calls in-memory:

{% link seangwright/kentico-12-design-patterns-part-12-database-query-caching-patterns-43hc %}

In fact, we can get pretty far by performing query caching only.

However, if we want super-fast page load speeds for SEO, increased goal-conversions, and improved user-experience for users located far from where our application is hosted, we want to use output caching too.

There is no need to run the Controller code if we already have the resulting HTML, right 😃?

We can apply output caching to our Controller by adding an attribute to our Controller or action method:

```csharp
// We can add an [OutputCache] attribute here
//  to cache the output of all actions...

[OutputCache(Duration=60)]
public class HomeController : Controller
{
    // or here to only cache the output of specific actions

    [OutputCache(Duration=60)]
    public ActionResult Index()
    {
        // ...
    }

    [ChildActionOnly]
    public ActionResult UserProfileIcon()
    {
        // ...
    }
}
```

Pretty simple 🎉!

> You can read more about how to configure output caching in [Kentico's documentation](https://docs.kentico.com/k12sp/configuring-kentico/configuring-caching/caching-on-mvc-sites) for caching in MVC applications, or [Microsoft's documentation](https://docs.microsoft.com/en-us/aspnet/mvc/overview/older-versions-1/controllers-and-routing/improving-performance-with-output-caching-cs) on enabling output caching.

---

Output Caching seems great! Let's add those attributes, sit back, and profit!

Not so fast 🤨!

If our application allows for users to interact with the site, and those interactions change how the site looks and feels to each specific user, then we will run into a problem with output caching 🤔.

Here's a simple, concrete scenario:

1. Our site allows users to log in to view information not available to unauthenticated users.
1. When a user is anonymous (has not yet logged in), the site content is not personalized for them.
1. When the user logs in they see a small Profile icon in the top right of the screen with their name next it.

If we apply output caching to our home page (or any page on the site) and that page is first visited by an unauthenticated users, then the resulting HTML will be cached and served to all users.

This means, even if a user logs in, they won't see the profile icon in the top right and they won't see their name 😑.

If the first user to visit a page after the cache has expired is an authenticated user, then the resulting HTML will be cached and served to all users - except this HTML will include the profile icon and the name of the user that requested the page 😣!

So, while a simple application of output caching is great for performance, it's bad for personalization.

Fortunately, there are several ways to resolve this problem, each requiring a bit of coding on our part (you, know, the fun stuff 😋!)

## Server-side Solutions

All of the solutions below occur server-side, by changing what HTML is cached, or how it is cached.

---

### VaryByCustom

The `[OutputCache]` attribute provides a `VaryByParam` property that allows us to create a unique cache item for every variation of a ["form parameter or query string parameter"](https://docs.microsoft.com/en-us/aspnet/mvc/overview/older-versions-1/controllers-and-routing/improving-performance-with-output-caching-cs#varying-the-output-cache).

Since the information about whether or not an authenticated user is making the request for a page (and who that user might be) is not included in form or query string parameter, we can't use `VaryByParam`, but there is another similar property that we can use called `VaryByCustom`.

`VaryByCustom` is a string value that is used to designate what kind of variation the output caching for a given Controller or action method should perform.

This string value is passed to a method in our `Global.asax.cs` class called `GetVaryByCustomString(HttpContext context, string arg)`.

> Kentico's documentation [gives an example](https://docs.kentico.com/k12sp/configuring-kentico/configuring-caching/caching-the-output-of-personalized-content) of how we can use this method to create unique cache entries, personalized per request as defined by our business requirements 🧐.

If two requests would result in the same returned value from this method, then the two requests can share the same cached content 😮.

A simple implementation of this method that demonstrates how two users would have their own cache entry for a page would look as follows:

```csharp
public override string GetVaryByCustomString(
    HttpContext context, string custom)
{
    bool varyByUser = User.Identity.IsAuthenticated
        && string.Equals(custom, "user", StringComparison.OrdinalIgnoreCase);

    if (varyByUser)
    {
        return User.Identity.Name;
    }

    return base.GetVaryByCustomString(context, custom);
}
```

In this example, since each request by an unauthenticated user will result in the same returned value, those requests will all share the same cache entry.

Also, since each authenticated user will result in a unique value being returned (the user's `Name`), each user's request will create their own distinct cache entry.

Therefore, each authenticated user will see the page rendered with the profile icon in the top right and their username beside it 👍.

We'd take advantage of this implementation by updating our `[OutputCache]` attribute as follows:

```csharp
[OutputCache(Duration=60, VaryByCustom="user")]
public class HomeController : Controller
{
    // or here to only cache the output of specific actions

    [OutputCache(Duration=60)]
    public ActionResult Index()
    {
        // ...
    }

    [ChildActionOnly]
    public ActionResult UserProfileIcon()
    {
        // ...
    }
}
```
---

`VaryByCustom` definitely works, and can be tailored to any use case by making the `GetVaryByCustomString` generate unique strings for all the variations we require.

That said, there are some downsides 😒:

- We create a cache entry per-user, so lot's of users = lots of cache entries = lots of memory usage.
- Users only get the caching benefits __after__ their first visit of a page because they can't rely on cache entries from previous visitors.
- Determining the validity of an output cache entry and the cached state of a page can be tricky as our cache variations grow in complexity.
- We have to remember to assign the right values to `VaryByCustom` everywhere we use `[OutputCache]`.

---

### Donut Hole Caching

If we only want to output cache certain parts of the page and leave others un-cached (and dynamic), we can try Donut Hole Caching.

This pattern treats the page as a Donut 🍩 (gotta love these delicious analogies!)

![A chocolate covered donut with sprinkles](https://thepracticaldev.s3.amazonaws.com/i/qurs4hl4odw6delcj23k.jpg)
<figcaption>Photo by <a href="https://unsplash.com/@kcatimmer">Kenny Timmer</a> on <a href="https://unsplash.com">Unsplash</a></figcaption>

We can implement this approach by using MVC Child Actions and applying our `[OutputCache]` attribute along with a `[ChildActionOnly]` attribute (to indicate the action shouldn't be used as a route-able action):

```csharp
public class HomeController : Controller
{
    public ActionResult Index()
    {
        // ...

        return View(viewModel);
    }

    [OutputCache(Duration=60)]
    [ChildActionOnly]
    public ActionResult UserProfileIcon()
    {
        // ...
    }
}
```

We can call a child action from our Razor layout or View by using `Html.RenderAction()`:

```html
<!-- Index.cshtml -->

<div>
    <h1>@Model.Title</h1>

    @{ Html.RenderAction(nameof(HomeController.UserProfileIcon)); }
</div>
```

```html
<!-- UserProfileIcon.cshtml -->
@if (Model.IsAuthenticated)
{
    <div class="user-icon">@Model.Username</div>
}
```

Here we are caching only the "hole" of the donut, which in our case is HTML produced by the `UserProfileIcon()` method of our Controller.

So, `Index()` will be called for every request, but `UserProfileIcon()` will only be called, at most, every 60 seconds, based on our cache duration.

> You can read the full details of an example on [Tugberk Ugurlu's blog](http://www.tugberkugurlu.com/archive/donut-hole-caching-in-asp-net-mvc-by-using-child-actions-and-outputcacheattribute) or [DotNetTutorials](https://dotnettutorials.net/lesson/outputcache-attribute-mvc/).

This approach is helpful for many scenarios, but not for ours 😕, since we really want to cache everything __but__ the hole (user context specific HTML, like the profile icon and user name).

---

### Donut Caching

If we want to invert the way that Donut Hole Caching works, we end up with Donut Caching, where everything is cached __but__ the hole that we punch through the cache.

MVC doesn't support this out of the box, but there is a popular library called [MvcDonutCaching](https://github.com/moonpyk/mvcdonutcaching) that allows us to add this functionality to our application in a similar pattern to using the `[OutputCache]` attribute 🤓.

Instead of using `[OutputCache]` on a Controller or action method, we use `[DonutOutputCaching]`:

```csharp
public class HomeController : Controller
{
    [DonutOutputCache(Duration=60)]
    public ActionResult Index()
    {
        // ...

        return View(viewModel);
    }

    [ChildActionOnly]
    public ActionResult UserProfileIcon()
    {
        // ...
    }
}
```

Then, in our `Index` view, we use an overload of `Html.RenderAction()` passing a value of `true` to exclude that child action from output caching

```html
<!-- Index.cshtml -->

<div>
    <h1>@Model.Title</h1>

    <!-- Notice how `true` is passed as the last param here -->

    @{ Html.RenderAction(nameof(HomeController.UserProfileIcon), true); }
</div>
```

> You can see an example of using MvcDonutCaching on [Denis Huvelle's blog](http://www.dhuvelle.com/2012/10/donut-caching-with-aspnet-mvc-4.html).

Although this library helps us solve our issue of wanting to exclude this user specific data from the output cache, it has some caveats:

- ❌ We have to remember to use the overload of `RenderAction()` that takes a `bool` value of `true` as the last parameter, otherwise we end up with users seeing each other's cached data!
- ❌ It can be hard to tell what will and won't be cached when looking at a Controller class file since it's the call to `Html.RenderAction()` that punches a "donut hole" in the output cache.
- ❌ The response for a page request still requires some MVC Controller code execution and HTML rendering, so the time for the first HTML will always be a little delayed.
- ❌ Rendering will be slightly delayed even for unauthenticated users, who should be able to share the same cache.

---

## Client-side Solutions

We've come up with some server-side solutions for output caching that give us the HTML result we want, but both `VaryByCustom` and `[DonutOutputCache]` result in missing some performance optimizations.

If we are using output caching, we are probably performance sensitive, so let's look at one last option that deals with all the above requirements and caveats 😉.

---

### Output Caching + Client-side Rendering

My favorite approach is to keep the user context specific HTML out of the MVC rendering pipeline.

That's right - don't even deal with the requesting user on the server side.

Instead, we use full output caching for all MVC rendered views 😲!

Instead, we make a JavaScript client-side request to a Web API endpoint in our MVC application for any user specific data, and render the HTML client-side.

What benefits does this bring?

- ✅ The caching model is simple - full output caching for all MVC Controllers.
- ✅ We separate user context decision making from server-side markup rendering, thus making our MVC business logic simpler.
- ✅ No visitor, authenticated or unauthenticated (or even web crawlers) to our site has to wait for a page to render (after the first request) - the time to ["first meaningful paint"](https://developers.google.com/web/tools/lighthouse/audits/first-meaningful-paint) is as short as possible.
- ✅ The site ends up being "progressive", giving all users a standard view and then enhancing it as the client-side processing executes.
- ✅ We can still perform data/query caching behind our Web API endpoints.

---

### UserProfileIcon Example

So, let's take a look at what the MVC + client-side rendering solution looks like!

We start out with our `HomeController`, leveraging `[OutputCache]`, but without the `UserProfileIcon()` action since that method will be moved to an API endpoint.

> If you need help setting up Web API 2 in your Kentico 12 MVC code base, check out my blog post _Kentico 12: Design Patterns Part 7 - Integrating Web API 2_:

> {% link seangwright/kentico-12-design-patterns-part-7-integrating-web-api-2-4ldg %}

```csharp
public class HomeController : Controller
{
    [DonutOutputCache(Duration=60)]
    public ActionResult Index()
    {
        // ...

        return View(viewModel);
    }

    // No more UserProfileIcon()
}
```

`HomeController` is now completely user context independent, so the same cached HTML can be served to all visitors!

Our `Index.cshtml` is updated to make our client-side XHR request and perform the client-side rendering:

> Using the `<script type="module">` and `<script nomodule>` elements means both script blocks can be be in the page and each browser type (legacy and modern) will only execute the appropriate version 😎.

```html
<!-- Index.cshtml -->

<div>
    <h1>@Model.Title</h1>

    <div class="" data-app="user-profile-icon"></div>

    <!-- For Modern Browsers -->

    <script type="module">
        (async () => {
            const response = await fetch('/api/home/user-profile-icon');

            const result = await response.json();

            const appElem = document
                .querySelector('[data-app="user-profile-icon"]');

            if (!result.isAuthenticated) {
                return;
            }

            appElem.classList.Add('user-icon');
            appElem.innerText = result.username;
        }());
    </script>

    <!-- For Legacy Browsers ex) IE11 -->

    <script nomodule>
        (function () {
            'use strict';

             var request = new XMLHttpRequest();

             request.onload = function(e) {
                 var result = JSON.parse(request.responseText);

                 var appElem = document
                     .querySelector('[data-app="user-profile-icon"]');

                 if (!result.isAuthenticated) {
                    return;
                 }

                 appElem.classList.Add('user-icon');
                 appElem.innerText = result.username;
             }

             request.overrideMimeType("application/json");
             request.open("GET", '/api/home/user-profile-icon');
             request.send();
        }());
    </script>
</div>
```

Now we create a Web API Controller, `HomeApiController`, and add the `UserProfileIcon` action method we removed from `HomeController`:

```csharp
[RoutePrefix("home")]
public class HomeApiController : ApiController
{
    [Route("user-profile-icon")]
    public HttpActionResult UserProfileIcon()
    {
        var response = new
        {
            isAuthenticated = User.Identity.IsAuthenticated,
            username = User.Identity.Name
        };

        return Ok(response);
    }
}
```

That's all the pieces we need!

Our Razor rendered HTML is suitable for every visitor as it excludes all user context, so that means we can use simple output caching and respond to all requests as fast as possible 😄.

Once the page loads in the browser, our JavaScript will make a request to the API endpoint, which will return the user context specific data (`isAuthenticated` and `username`).

The JavaScript then renders this user context into the `<div>` acting as the hook point for our client-side rendering.

The more we branch out into rich client-side experiences, the more appealing this pattern gets 👍.

### Caveats

So there are some issues with this approach that might cause you to use one of the others mentioned above.

By pushing user context specific rendering to the client, we push rendering to the client. If we need to support localization we'll need to figure out a way to either do translations server side and send them down the client, or do localization client-side 🤔.

Many EMS features in Kentico 12 MVC depend on A/B testing and advanced personalization.

These features are meant to be handled server-side, so they won't simply translate to this client-side rendering approach 😞.

To leverage the EMS marketing features for personalization, we'll probably want to use `VaryByCustom` combined with `[DonutOuputCaching]` to keep the cache variations low but also personalized.

Also, if you don't feel confident working with JavaScript or doing client-side rendering of HTML, you might want to stick with the above server-side options...

However, I do recommend brushing up on your JavaScript skills as it's a great tool to put in your toolbox and opens up many new solutions to common problems 🤗.

## Summary

To improve the performance of our Kentico 12 MVC application and ensure scalibility as traffic increases, we want to leverage caching ⚡.

We can cache data within the application and also cache the HTML output of our MVC layer.

Out of the box, output caching doesn't handle user context specific HTML, so we need to customize the output caching process to ensure each user sees the correct data.

`VaryByCustom`, Donut Hole Caching, and Donut Caching are all server-side options for cutomizing how output cache entries are created and which entries are served to each visitor 🧐.

However, there are some caveats to the server-side approaches.

If we want a simple server-side MVC request pipeline that doesn't need to consider user context data, then moving the rendering of this user-specific HTML to the client-side lets us use out-of-the-box output caching and super fast page response times.

Client-side user context HTML rendering requires setting up Web API endpoints in our app to get the user-specific data, and then rendering the HTML in the browser using standard DOM APIs 🙂.

This approach works well, but has some caveats of its own, like relying on JavaScript skills which some teams might not feel comfortable relying on.

It also isn't a scenario supported by the built-in personalization features in Kentico EMS, so developers will need to build custom solution integrations if these features are being used with the client-side rendering approach 🤔.

I hope you found this post interesting. In the future I'd like to delve a bit more into patterns for effective integration of client-side solutions, with traditional server-rendered HTML applications, to get the best of both worlds!

Thanks for reading 🙏!

---

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

{% tag kentico %}

Or my Kentico blog series:

- [Kentico 12: Design Patterns](https://dev.to/search?q=Kentico%2012%3A%20Design%20Patterns)
- [Kentico CMS Quick Tips](https://dev.to/search?q=Kentico%20CMS%20Quick%20Tip)