What are NCache Custom Hooks in ASP.NET Output Caching?

Custom Hooks are intermediate execution points that allow developers to categorize or group page and control output segments before they are inserted into the distributed cache.

How do I group cached output using Custom Hooks?

By implementing the OnCachingOutput method, you can return a CacheMetadata object containing specific GroupName, Tags, or Dependencies to be associated with the cached item.

What is the role of the OnCachingOutput method?

The OnCachingOutput method acts as a hook between the provider and user code; it is called after output generation but before cache insertion to allow for additional metadata assignment.

ASP.NET Output Cache with Custom Hooks

The NCache Output Cache Provider efficiently manages the storage of page and control outputs in a distributed cache environment. To provide granular control over data organization, NCache utilizes Custom Hooks, which allow developers to group and categorize cached output based on specific business logic before it is committed to the store. These hooks serve as an intermediate execution point, enabling the assignment of Groups, Tags, and Key Dependencies to cached page segments to enhance searchability and management within the cluster.

To implement ASP.NET Output Cache with Custom Hooks the following configuration changes are required:

Prerequisites to Use ASP.NET Output Cache with Custom Hooks

.NET

To use ASP.NET Output Cache with Custom Hooks install the following NuGet packages in your application:
- Enterprise: AspNet.OutputCache.NCache
To utilize the extension, include the following namespaces in your application in Startup.cs:
- Alachisoft.NCache.OutputCacheProvider
The cache must be running.
For API details, refer to: NOutputCacheProvider.
Make sure that the data being added is serializable.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Modify Web.Config

Modify the Web.config to implement ASP.NET Output Cache with Custom Hooks.

<!-- caching section group -->

<caching>
    <outputCache defaultProvider="NOutputCacheProvider">
        <providers>
            <add name="NOutputCacheProvider"
            type="Alachisoft.NCache.OutputCacheProvider.NOutputCacheProvider, Alachisoft.NCache.OutputCacheProvider, Version=x.x.x.x, Culture=neutral, PublicKeyToken=cff5926ed6a5376"
            exceptionsEnabled="false"
            enableLogs="true"
            cacheName="demoClusteredCache"
            writeExceptionsToEventLog="false"
            hookAssemblyName="OutputCache, Version=x.x.x.x, Culture=neutral, PublicKeyToken=null" hookClassName="Sample.OutputCacheProvider.OutputCacheHook.OutputCacheHookSample"/>
        </providers>
    </outputCache>

</caching>

Note

Replace Version=x.x.x.x with the actual NCache version that you have installed.

Sample Implementation of IOutputCacheHook

The following code demonstrates the implementation of IOutputCacheHook.

class OutputCache : IOutputCacheHook
{
    public void Initialize()
    {
        // initialize required elements here, according to business logic.
    }

    public CacheMetadata OnCachingOutput(HttpContext context, string key, object value, CacheOperation operation, ref DateTime utcExpiry)
    {
        CacheMetadata cacheMetaData = null;

        if (context != null)
        {
            cacheMetaData = new CacheMetadata();
            // Put required business logic to categorize input parameter key in desired group

            // Groups, sub groups, tags, named tags and dependencies can be assigned
            // to object of cacheMetaData which is returned to be inserted into cache

            cacheMetaData.GroupName = "vendorState";
            cacheMetaData.Dependency = new KeyDependency(key);
            utcExpiry = DateTime.Now.AddMinutes(5);
        }

        return cacheMetaData;
    }

    public void Dispose()
    {
        // Dispose the initialized elements here
    }
}

Configuration Members

Output Cache with custom hooks allows grouping of data before storing it into the cache. To implement IOutputCacheHook, create a class that extends IOutputCacheHook. The following table lists the properties and methods that must be implemented:

Methods	Description
`Initialize`	Initializes required elements of `OutputCacheHook`.
`OnCachingOutput`	Takes as input the `HttpContext` instance for the current request, `String` key and `object` value generated by the framework for output is passed as is an input parameter. Input parameter `CacheOperation` type can be added or set, concerning the `OutputCache Provider` operations of `Add` and `Set`. `DateTime` `utcExpiry` is passed as a reference parameter which allows end-user code to reset expiration for a particular key-value pair. If the value for expiration is not set, the default value provided by the framework is used. This method returns `CacheMetadata` that can have additional information about the group, subgroup, tag, named tag, and dependency settings. This method functions as a hook between the `OutputCache` Provider and user code. It is called when output is generated by the framework but before insertion into the cache. Thus, allowing an intermediate hook for a user, where additional information can be added with `CacheMetadata`.
`Dispose`	It releases resources that are no longer in use by `OutputCacheHook`.