I’ve been spending a lot of time on Dynamics 365 Portal performance recently, and I was able to dig a bit into a topic that I thought was worth sharing: the output caching of the header and footer templates. If that doesn’t catch your attention, how about the fact that it involves donuts?

Various Levels of Caching

If you know the Dynamics 365 Portal product, you know that it uses caching. In fact, the internet as a whole heavily relies on caching to reduce the amount of traffic and to improve speed, whether that is browser cache, caching within content delivery networks, or caching at the server level.

The caching that gets most of the press in the Dynamics 365 Portal product is at the CRM SDK level – that is, when the Portal application uses the CRM SDK to make a query to Dynamics, it remembers the results of those queries so that it does not need to perform them again (unless the cache timeout expires, or it has been informed by Dynamics that the data has changed). This is the cache that was so troublesome in the first versions of the product, and required the use of the Clear Cache button.

However, in general the Portal application still executes any non-CRM SDK-related code each time it loads a page. There is a major exception to that (if you’ve got it configured), and that is the output caching of the Header and Footer web templates.

Output Caching

Output caching refers to the caching of the actual HTML that server-side code generates. When output caching is enabled for the header and footer, the Portal application isn’t required to rerun the code used to generate it – it simply stores the resulting HTML in memory and returns that value without having to recalculate it.

Output caching for the header and footer is optional – it is controlled via the Header/OutputCache/Enabled and Footer/OutputCache/Enabled Site Settings. If not set to true, the Portal code will evaluate all of the Liquid code in the header and footer each time a page is requested. When enabled, it will “remember” the output and simply return it, thus reducing the overall time it take to generate the page.

For most of the header and footer, this would work great. And the output caching provided by ASP.NET already includes capabilities to ensure that the output cache is user-specific (so that, for example, you see your own name in the top right corner of a Portal). Unfortunately, there are still parts where output caching causes complications.

For example, consider the Sign In button. Included in the link is the URL of the page you are on (called the Return URL), so that once you log in, you can be redirected back to that page. If that part of the page was output cached, everyone would see the same return URL, regardless of what page you are on.

Thankfully, there is a solution to this problem, and it’s one of the most deliciously-named techniques you’ll ever run into.

Donut Caching

Donut caching is the idea that you may want to cache a large portion of a page, but there might be a small section within the page that you do not want to cache (in our example, this would be the link for signing in). Caching everything except a small “hole” in the middle leads to the delicious name. This is the technique that the Portal code uses for caching the header and footer web templates.

For a more detailed explanation on donut caching check out this link.

In order for this to work, you have to identify in your templates which areas can be cached, and which ones need to be generated each time. To do this, there are a couple of options:

1. Use the substitution Liquid tag to wrap any code that should be executed each time the page is reloaded.
2. Several “special” Liquid attributes support donut caching, including:
   • website.sign_in_url_substitution
   • website.sign_in_link_substitution
   • website.sign_out_url_substitution
   • language.url_substitution (where language is one of the elements of the page.languages array)

It should be noted that none of these attributes are officially documented, nor is the substitution tag documented, so use at your own risk. The closest we have to documentation is this page, which explains how to enable output caching for Portal instances that were created before it was a feature. This documentation references those tags in its instructions, but provides no explanation.

To prove the use of the substitution Liquid tag, try adding the following to your Header web template:

{{ now }} 
{% substitution %}
{{ now }} 
{% endsubstitution %}

The now Liquid tag displays the current time. As expected, the now within the substitution tag is updated each time the page is refreshed, whereas the first one remains the same (it displays the time when the page was first requested after the cache expired or was invalidated).