Notifications in Azure In-Role Cache
Microsoft recommends all new developments use Azure Redis Cache. For current documentation and guidance on choosing an Azure Cache offering, see Which Azure Cache offering is right for me?
Azure offers cache notifications that allow your applications to receive asynchronous notifications when a variety of cache operations occur on the cache cluster. Cache notifications also provide automatic invalidation of locally cached objects.
To receive asynchronous cache notifications, add a cache notification callback to your application. When you add the callback, you define the types of cache operations that trigger a cache notification and which method in your application should be called when the specified operations occur. A named cache needs to opt-in and enable cache notifications.
Triggering Cache Notifications
These cache operations are defined by members of the DataCacheOperations class.
Your application can receive cache notifications when the following cache operations occur on a region:
CreateRegion: When a region is created in the cache.
ClearRegion: When a region is cleared in the cache.
RemoveRegion: When a region is removed from the cache.
Your application may receive cache notifications when the following cache operations occur on a cached object (referred to as an item within the cache).
AddItem: When an item is added to the cache.
ReplaceItem: When an item is replaced in the cache.
RemoveItem: When an item is removed from the cache.
By themselves, these item operations do not depend on whether they occurred within a region or not. You can choose to limit the notification scope of your callback to a particular region. This is discussed in the Notification Scope section of this document.
Depending on the activity and needs of your application, you may not want to pay attention to the events from every object and region in the whole cache. You may narrow the scope of your notifications from the cache level down to the region level and item level. The notification scope that you select when you add a callback greatly impacts which cache notifications you will receive.
At the cache level, your application may be notified of all cache operations from all objects and regions in the cache. At the region level, your application will be notified only about cache operations from a single region and the objects in it. At the item level, your application will be notified only about cache operations pertaining to a single object.
To specify the notification scope you want, choose one of these three methods to add a cache notification callback:
AddCacheLevelCallback: When you want to be notified of region- and item-based cache operations occurring on all regions and items.
AddRegionLevelCallback: When you want to be notified of region- and item-based cache operations occurring on one specific region.
AddItemLevelCallback: When you want to be notified of item-based cache operations occurring on one specific item.
The order of notifications received by the cache client is guaranteed within the context of a single region. For example, assume that you have created a region named
RegionA. Because all data put in a cache region is limited to the same region, all cache operations that pertain to
RegionA (region-level notification scope) arrive at the cache client in the appropriate order relative to each other. Region- and item-based cache operations that occurred on other cache hosts are not guaranteed to arrive in the appropriate order relative to the operations that occurred in
In the interest of performance, the order of notifications involving more than one region or objects that are not stored in the same region cannot be guaranteed.
Version information for item events, in the form of the DataCacheItemVersion object, is passed to the method invoked by the cache notification with the
version parameter. This DataCacheItemVersion object corresponds to the version of the object that triggered the item event. By using the CompareTo method, you can compare versions to determine which cache operations came first.
Version comparisons are only meaningful when comparing versions of the same item specified with the same key. It is not possible to deduce order by comparing versions from different keys; the CompareTo method may return a result, but the result is only valid for versions of the same key.
When you use cache notifications, your application checks with the cache cluster at a regular interval to see if any new notifications are available. This interval, called the polling interval, is every 300 seconds by default. Applications that write frequently may want to set it to a smaller value, but for caches that do not change often, a larger interval may be better. The default of 300 seconds is good for most general caches.
The polling interval is specified in units of seconds in the application configuration settings. To specify a specific interval, you can use the
pollInterval attribute of the
clientNotifications element in the application configuration file. You can also specify a specific polling interval programmatically with the
NotificationProperties property of the DataCacheFactoryConfiguration object.
When Notifications Are Lost
Cache hosts can hold only a certain amount of cache operations in memory. It is possible that some cache clients may not receive notifications before they are truncated in the cache host queues. Cache clients may also miss notifications when data is lost due to a cache server failure while the rest of the cluster remains running. In these cases, your cache client can discover that it has missed some cache notifications by using a failure notification. Your application can add a callback to receive failure notifications by using the AddFailureNotificationCallback method. For more information, see How to: Add a Failure Notification Callback
When the Cache Cluster Is Lost
There is an important distinction between loss of notifications and loss of the cache cluster. If your application loses one or more notifications, it can become aware of that loss by means of a failure notification. If the entire cache cluster is stopped, restarted, or otherwise lost, no notifications will be triggered. Instead, your cache client will throw exceptions the next time you attempt to use the cache if it is unable to connect with the cluster. Cache cluster events such as cache creation or deletion are not reported by notifications. If cache is deleted from the server after registering notifications, one simply stops receiving notifications. It is not possible to differentiate between a cache not existing and operations not being performed on a cache.
Cache notifications only report data-related changes to regions and cache items in the cluster; they do not report events of the cluster itself.
Enabling Cache Notifications
The cache notifications feature is configured at the cache level in the cluster configuration settings. As a property of the cache, you can enable it when you first create the cache. By default, the cache notifications feature is disabled when you create a new cache.
No application configuration settings are required to add a callback for receiving cache notifications. You can use the application configuration settings to specify a specific poll interval. By default, the polling interval is 300 seconds. If you want a different duration, use the
clientNotification element in the XML-based application configuration file or specify your desired interval programmatically with the
NotificationsProperties property of the DataCacheFactoryConfiguration object.
Using Cache Notifications
After cache notifications have been enabled, there are three tasks related to using cache notifications: adding cache notification callbacks, adding a failure notification callback, and removing cache notification callbacks. The procedures for each of these tasks are described in the rest of this documentation.