The Caching Handler

The Caching Handler provides the capability to cache the value or object instance returned from the selected method or the value of the selected property. This handler is different from the other built-in handlers because it does not use the features of Enterprise Library. Instead of using the Caching Application Block, this handler takes advantage of the features provided by the ASP.NET Cache object and the associated mechanism within the .NET Framework.

The Caching Handler applies both before and after invocation of the selected method or setting of the selected property of the target object. When called in the pre-processing stage before invocation of the target method or property accessor, the handler determines whether the return value from a call to this method with the same parameter values already exists in the cache. If the value does exist, the handler aborts execution of the pre-processing handler pipeline, does not invoke the target method or set the target property, and returns the cached value instead.

If the value does not exist in the cache, the handler does nothing in the pre-processing stage and allows the handler pipeline to continue execution. Then, after the Policy Injection Application Block invokes the target method or reads the target property, the post-processing stage of the Caching Handler captures the return value of the method, or the property value, and inserts it into the cache.

Users accessing methods through the handler pipeline on different threads, and in different security contexts, will receive the same result from the cache if the input parameters are the same. This may result in security concerns if the data is user-specific or of a sensitive nature.
The Caching Handler uses the <STRONG>GetHashCode</STRONG> method of each input parameter to generate a unique cache key. As such, the handler will only work as expected if each input parameter type implements this method correctly to guarantee that the same objects generate the same hash codes and different objects generate different hash codes. The default implementation of <STRONG>GetHashCode</STRONG> (inherited from the <STRONG>Object</STRONG> class) is not guaranteed to be correct in all cases for derived types. If you are using any of your own types as input parameters for methods using the Caching Handler, you can override the <STRONG>GetHashCode</STRONG> method yourself to ensure it functions as expected.

Behavior of the Caching Handler

In more detail, the Caching Handler does the following:

• It reads the cache expiration time span from the Policy Injection Application Block configuration.
• It creates a cache key based on the method signature and input parameter values when the handler is invoked.
• It checks whether the cache contains a value for this cache key.
• If a value does exist, the Caching Handler extracts this from the cache, prevents subsequent handlers and the target method from executing, and returns the cached value to the caller instead.
• If a value does not exist, the Caching Handler allows the next handler in the pipeline to execute. Then, after the method executes, the Caching Handler stores the returned value in the cache using the cache key and the configured expiration policy.

Configuration Settings of the Caching Handler

The following configuration setting is available for the Caching Handler:

• ExpirationTime (TimeSpan). This is the length of time from the point when the handler first adds the data to the cache until it expires.

The next procedure describes how to configure the Caching Handler using the Configuration Console or the Visual Studio 2005 Configuration Editor.

To configure the Caching Handler

1. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Caching Call Handler.
2. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
3. If you want to change the cache expiration time from the default duration used by the ASP.NET caching mechanism, select the ExpirationTime property, and then enter an expiration duration in the format hh:mm:ss—for example, 00:02:00 for two minutes. The default cache duration is five minutes.

Attribute-based Targeting with the Caching Handler

The following code shows the use of the [CachingCallHandler] attribute on two simple methods. This attribute can also be applied to the class declaration, in which case it applies to all members of that class. The cache duration (in hours, minutes, and seconds) is optional. If omitted, as in the second example, the Caching Handler uses the default cache duration of five minutes.

[CachingCallHandler(0, 0, 30)]
public decimal GetSavingsBalance(int accountNumber)
{
  // Code here to extract balance from database.
  return balance;
}

[CachingCallHandler]
public decimal GetMortgageBalance(int accountNumber)
{
  // Code here to extract balance from database. 
  return balance;
}

<CachingCallHandler(0, 0, 30)> _
Public Function GetSavingsBalance(int accountNumber) As Decimal
  ' Code here to extract balance from database.
  Return balance
End Function

<CachingCallHandler> _
Public Function GetMortgageBalance(int accountNumber) As Decimal
  ' Code here to extract balance from database. 
  Return balance
End Function

The CachingCallHandlerAttributeclass does not expose any properties.