Cache Tag Helper in ASP.NET Core MVC

By Peter Kellner

The Cache Tag Helper provides the ability to improve the performance of your ASP.NET Core app by caching its content to the internal ASP.NET Core cache provider.

For an overview of Tag Helpers, see Tag Helpers in ASP.NET Core.

The following Razor markup caches the current date:

<cache>@DateTime.Now</cache>

The first request to the page that contains the Tag Helper displays the current date. Additional requests show the cached value until the cache expires (default 20 minutes) or until the cached date is evicted from the cache.

Cache Tag Helper Attributes

expires-after

Attribute type	Example	Default
TimeSpan	@TimeSpan.FromSeconds(120)	—

expires-after sets the length of time from the first request time to cache the contents.

Example:

<cache expires-after="@TimeSpan.FromSeconds(120)">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

enabled

Attribute type	Examples	Default
Boolean	true, false	true

enabled determines if the content enclosed by the Cache Tag Helper is cached. The default is true. If set to false, the rendered output is not cached.

Example:

<cache enabled="true">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

expires-on

Attribute type	Example
DateTimeOffset	@new DateTime(2025,1,29,17,02,0)

expires-on sets an absolute expiration date for the cached item.

The following example caches the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025:

<cache expires-on="@new DateTime(2025,1,29,17,02,0)">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

expires-sliding

Attribute type	Example
TimeSpan	@TimeSpan.FromSeconds(60)

Sets the time that a cache entry should be evicted if its value hasn't been accessed.

Example:

<cache expires-sliding="@TimeSpan.FromSeconds(60)">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

Defaults to 30 seconds if expires-after and expires-on aren't defined.

priority

Attribute type	Examples	Default
CacheItemPriority	High, Low, NeverRemove, Normal	Normal

priority provides cache eviction guidance to the built-in cache provider. The web server evicts Low cache entries first when it's under memory pressure.

Example:

<cache priority="High">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

The priority attribute doesn't guarantee a specific level of cache retention. CacheItemPriority is only a suggestion. Setting this attribute to NeverRemove doesn't guarantee that cached items are always retained. See the topics in the Additional Resources section for more information.

The Cache Tag Helper is dependent on the memory cache service. The Cache Tag Helper adds the service if it hasn't been added.

vary-by

Attribute type	Example
String	@Model

vary-by allows for customization of what data is cached. When the object referenced by the attribute's string value changes, the content of the Cache Tag Helper is updated. Often, a string-concatenation of model values are assigned to this attribute. Effectively, this results in a scenario where an update to any of the concatenated values invalidates the cache.

The following example assumes the controller method rendering the view sums the integer value of the two route parameters, myParam1 and myParam2, and returns the sum as the single model property. When this sum changes, the content of the Cache Tag Helper is rendered and cached again.

Action:

public IActionResult Index(string myParam1, string myParam2, string myParam3)
{
    int num1;
    int num2;
    int.TryParse(myParam1, out num1);
    int.TryParse(myParam2, out num2);
    return View(viewName, num1 + num2);
}

Index.cshtml:

<cache vary-by="@Model">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-cookie

Attribute type	Examples
String	.AspNetCore.Identity.Application, .AspNetCore.Identity.Application,HairColor

vary-by-cookie accepts a comma-delimited list of cookie names that trigger a cache refresh when the cookie values change.

The following example monitors the cookie associated with ASP.NET Core Identity. When a user is authenticated, a change in the Identity cookie triggers a cache refresh:

<cache vary-by-cookie=".AspNetCore.Identity.Application">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-culture

Attribute type	Examples	Default
Boolean	true, false	false

vary-by-culture varys the cached result by request culture. Setting the attribute to true means the result is varied by CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture.

Example:

<cache vary-by-culture="true">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-header

Attribute type	Examples
String	User-Agent, User-Agent,content-encoding

vary-by-header accepts a comma-delimited list of header values that trigger a cache refresh when they change.

The following example monitors the header value User-Agent. The example caches the content for every different User-Agent presented to the web server:

<cache vary-by-header="User-Agent">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-query

Attribute type	Examples
String	Make, Make,Model

vary-by-query accepts a comma-delimited list of Keys in a query string (Query) that trigger a cache refresh when the value of any listed key changes.

The following example monitors the values of Make and Model. The example caches the content for every different Make and Model presented to the web server:

<cache vary-by-query="Make,Model">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-route

Attribute type	Examples
String	Make, Make,Model

vary-by-route accepts a comma-delimited list of route parameter names that trigger a cache refresh when the route data parameter value changes.

Example:

Startup.cs:

routes.MapRoute(
    name: "default",
    template: "{controller=Home}/{action=Index}/{Make?}/{Model?}");

Index.cshtml:

<cache vary-by-route="Make,Model">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

vary-by-user

Attribute type	Examples	Default
Boolean	true, false	false

vary-by-user specifies whether or not the cache resets when the signed-in user (or Context Principal) changes. The current user is also known as the Request Context Principal and can be viewed in a Razor view by referencing @User.Identity.Name.

The following example monitors the current logged in user to trigger a cache refresh:

<cache vary-by-user="true">
    Current Time Inside Cache Tag Helper: @DateTime.Now
</cache>

Using this attribute maintains the contents in cache through a sign-in and sign-out cycle. When the value is true, an authentication cycle invalidates the cache for the authenticated user. The cache is invalidated because a new unique cookie value is generated when a user is authenticated. Cache is maintained for the anonymous state when no cookie is present or the cookie has expired. If the user is not authenticated, the cache is maintained.

Additional resources

• Cache in-memory in ASP.NET Core
• Introduction to Identity on ASP.NET Core