Notifications for Azure Managed Cache Service
Important
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?
Microsoft Azure Cache offers cache notifications that allow your applications to receive asynchronous notifications when a variety of cache operations occur on a named cache. 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.
Note
Notifications are available in the Standard and Premium cache offerings, and are not available in the Basic cache offering. For more information, see Cache Offerings for Azure Managed Cache Service.
Triggering Cache Notifications
These cache operations are defined by members of the DataCacheOperations class.
Region Operations
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.
Item Operations
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.
Note
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.
Notification Scope
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.
Notification Order
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 RegionA.
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.
Note
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.
Polling Interval
When you use cache notifications, your application checks with the cache 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
Microsoft Azure Cache 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 notification queues. Cache clients may also miss notifications when data is lost due to a cache failure. 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 is Lost
There is an important distinction between loss of notifications and loss of the cache. 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 is deleted, cache client will throw exceptions the next time you attempt to use the cache since it will be unable to connect with the cache endpoint. Cache events such as named cache creation or deletion are not reported by notifications. If a named cache is deleted after registering notifications, one simply stops receiving notifications. It is not possible to differentiate between a named cache not existing and operations not being performed on a named cache.
Note
Cache notifications only report data-related changes to regions and cache items in the; they do not report events of the cache itself.
Enabling Cache Notifications
Notifications are configured at the named cache level in the Management Portal on the Configure tab for Cache. The default setting for notifications is Disabled.
.jpg "Cache Notifications for Windows Azure Cache Servic")
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.