This package integrates with the popular Hybrid Caching library known as ZiggyCreatures.FusionCache (https://github.com/ZiggyCreatures/FusionCache) providing a true L1 + L2 layered caching solution within Xperience by Kentico.
This package integrates with the popular Hybrid Caching library known as ZiggyCreatures.FusionCache providing a true L1 + L2 layered caching solution within Xperience by Kentico.
It provides some useful utilities such as cache invalidation via Kentico cache dependencies, custom FusionCache backed cache tag helper and support for output caching, with content personalization handled out of the box.
Inject IFusionCache and use the Get/Set methods, providing tags as Kentico cache dependency keys:
var products = await this.fusionCache.GetOrSetAsync<IEnumerable<ProductDTO>?>(
key: "FooWebsite.Products",
factory: async (ctx, _) =>
{
var products = await this.GetproductsAsync();
if (products is null)
{
ctx.Options.Duration = TimeSpan.Zero;
return null;
}
return products;
},
tags: [CacheHelper.BuildCacheItemName(new[] { ProductItem.CONTENT_TYPE_NAME, "all" })]);
And that should be enough to get going! Read on for more info.
Full Instructions
Default Cache options
You can choose to configure some default FusionCacheEntryOptions via appsettings.json config. These will be used as the default for all cache entries, although they can be overridden on a per-call basis when using IFusionCache. See: https://github.com/ZiggyCreatures/FusionCache/blob/main/docs/Options.md
NewtonsoftJson is configured as the default serializer for maximum compatibility and ease of use, however it's possible to configure any of the following serializers:
FusionCache will now use the configured serializer instead of the default. Each serializer has its pros, cons and individual quirks you should familiarize yourself with before using.
Development Mode
The library has a development mode setting which will skip read/writes to the L2 cache for ease of local development.
To enable development mode, add the DevMode property to appsettings.json:
The package provides a custom cache tag helper backed by FusionCache.
To use it, include the tag helper in your view:
<xperience-fusion-cache
name="home-page-cache"
cache-dependencies="@(new string[] { "webpageitem|byid|1", "contentitem|bycontenttype|Medio.Clinic" })"
duration="@TimeSpan.FromMinutes(5)"
vary-by-option-types="@(new[] { typeof(ContactGroupVaryByOption) })">
@* Cached HTML goes here *@
</xperience-fusion-cache>
See below, for a full list of options:
Option
Description
Example
Default
name
Required. A unique name for the tag instance.
"product-listing"
null
enabled
A value indicating whether caching is enabled for the tag.
true
true
cache-dependencies
Collection of cache dependencies for the cache entry. The associated cache item will be cleared when one of the dependencies is touched by the system.
new string[] { "webpageitem|byid|3" }
null
cacheability-rules
Collection of custom rules that determine whether the tag inner content can be cached based on whether the IReadOnlyMemory<char> pattern was found within the tags HTML.
Vary the cache by the provided query parameter(s).
"page,filter"
null
vary-by-route
Vary the cache by the provided route parameter(s).
"lang,id"
null
vary-by-cookie
Vary the cache by the provided cookie name(s).
"cookie1,cookie2"
null
vary-by-user
Vary the cache by the current user.
true
false
vary-by-culture
Vary the cache by the current request culture.
true
false
vary-by-option-types
ICacheVaryByOption implementations to vary the cache by. Useful for content personalization.
new[] { typeof(ContactGroupVaryByOption) }
null
Output cache
This package integrates with the NET Core Output Caching middleware via a custom IOutputCacheStore and IOutputCachePolicy which has been integrated with FusionCache.
Just reference XperienceFusionCache as the policy name when using the [OutputCache] attribute and optionally specify cache dependencies via the Tags attribute.
Example usage:
public class HomePageController : Controller
{
[OutputCache(PolicyName = "XperienceFusionCache", Tags = ["webpageitem|all"])]
public async Task<IActionResult> Index()
{
// Perform some expensive logic...
// Associate cache dependencies with the current request
this.HttpContext.AddCacheDependencies(
new HashSet<string>() {
CacheHelper.BuildCacheItemName(new[] { "webpageitem", "bychannel", "MyWebsite", "bycontenttype", "website.homepage" }),
});
return new TemplateResult();
}
}
You can also specify cache dependencies via the AddCacheDependencies extension method (see example above) if they aren't known at runtime.
Policy defaults can be customized via appsettings.json:
public class ContactGroupVaryByOption : ICacheVaryByOption
{
public string GetKey()
{
var contact = ContactManagementContext.GetCurrentContact();
if (contact?.ContactGroups is null || !contact.ContactGroups.Any())
{
return string.Empty;
}
var contactGroups = contact.ContactGroups
.OrderBy(x => x.ContactGroupName)
.Select(y => y.ContactGroupName);
return string.Join("||", ["VaryByContactGroup", .. contactGroups]);
}
}
Then pass these types to the vary-by-option-types attribute, if using the <xperience-fusion-cache /> tag helper, e.g:
<xperience-fusion-cache
name="my-widget-cache"
duration="@TimeSpan.FromMinutes(5)"
vary-by-option-types="@(new[] { typeof(ContactGroupVaryByOption) })">
@* Cached HTML which should vary by contact group goes here *@
</xperience-fusion-cache>
Or alternatively, if using controller level [OutputCache], decorate the action result with [XperienceFusionCacheVaryByOptionTypes] and specify your custom ICacheVaryByOption types in the constructor, e.g:
[OutputCache(PolicyName = "XperienceFusionCache", Tags = ["webpageitem|all"])]
[XperienceFusionCacheVaryByOptionTypes(VaryByOptionTypes = [typeof(ContactGroupVaryByOption)])]
public async Task<IActionResult> Index()
{
// Some expensive logic...
return new TemplateResult();
}
This ensures that your custom vary by option implementations are considered when constructing a unique cache key for the cache item.
Extending cache invalidation for custom object types
Cache invalidation of standard Kentico objects (pages, content items, media etc...) is handled out of the box but if you want invalidation for general object types (those that inherit from BaseInfo) then you should implement the IGeneralObjectCacheItemsProvider type and place it somewhere within your application root.
Example:
public class GeneralObjectsCacheItemsProvider : IGeneralObjectCacheItemsProvider
{
public IEnumerable<ObjectTypeInfo> GeneralObjectInfos => new List<ObjectTypeInfo>()
{
SomeCustomTypeInfo.TYPEINFO,
UserInfo.TYPEINFO,
//...
};
}
