How to: Receive Notifications from an Azure In-Role Cache

This topic describes how to add a cache notification callback that will enable your application to receive cache notifications.

Adding a cache notification callback requires two steps. First, create a method that should be invoked when a cache notification is triggered by one or more cache operations. The method you invoke with the cache notifications must accept the same parameters as the DataCacheNotificationCallback delegate. Second, add a callback by using one of the three available methods from the DataCache object:

• AddCacheLevelCallback

• AddRegionLevelCallback

• AddItemLevelCallback

Use the filter parameter to define the types of cache operations you want to trigger cache notifications. Use the name of the method you created in the first step for the clientDelegate parameter.

To add a callback for one or more cache operations

1. Create the method you want to be triggered by the cache notification. Make sure the method accepts the same parameters as the DataCacheNotificationCallback delegate.

2. Add a callback. Use one of the three available methods from the DataCache object to define the notification scope: AddCacheLevelCallback, AddRegionLevelCallback, or AddItemLevelCallback.

   1. Use the DataCacheOperations enumeration in the filter parameter to specify what type of cache operations you want to trigger notifications. Select more than one enumeration by separating the enumerations with the binary OR operator to perform a bitwise OR. To do this, use the | character in C#, and the Or operator in Visual Basic.

   2. Use the name of the method you want to invoke when these notifications occur in the clientDelegate parameter.

   3. Set the add callback method equal to a DataCacheNotificationDescriptor object that you can use elsewhere in your program to remove the cache notification callback.

Example

The first step when registering for cache notifications is to create a method that you want to be invoked by the notification. The method called by the notification must accept the same parameters as the DataCacheNotificationCallback delegate. This example shows one example of a method that can be invoked by a cache notification.

'method invoked by notification "ndCacheLvlAllOps" 
Public Sub myCacheLvlDelegate(ByVal myCacheName As String, _
    ByVal myRegion As String, _
    ByVal myKey As String, _
    ByVal itemVersion As DataCacheItemVersion, _
    ByVal OperationId As DataCacheOperations, _
    ByVal nd As DataCacheNotificationDescriptor)

    'display some of the delegate parameters
    Console.WriteLine("A cache-level notification was triggered!")
    Console.WriteLine("    Cache: " + myCacheName)
    Console.WriteLine("    Region: " + myRegion)
    Console.WriteLine("    Key: " + myKey)
    Console.WriteLine("    Operation: " + OperationId.ToString())
    Console.WriteLine()
End Sub

//method invoked by notification "ndCacheLvlAllOps" 
public void myCacheLvlDelegate(string myCacheName,
    string myRegion, 
    string myKey, 
    DataCacheItemVersion itemVersion,
    DataCacheOperations OperationId, 
    DataCacheNotificationDescriptor nd)
{
    //display some of the delegate parameters
    Console.WriteLine("A cache-level notification was triggered!");
    Console.WriteLine("    Cache: " + myCacheName);
    Console.WriteLine("    Region: " + myRegion);
    Console.WriteLine("    Key: " + myKey);
    Console.WriteLine("    Operation: " + OperationId.ToString());
    Console.WriteLine();
}

The second step is to add a callback for one or more cache operations. In this example, a notification is created to invoke the method from the previous example. For demonstration only, this notification has been configured for all possible cache operations with a cache-level notification scope.

To define more than one cache operation, you can use the binary OR operator to assign more than one DataCacheOperations enumeration to a DataCacheOperations variable that can be used for the filter parameter. To add a callback for cache operations with a cache-level notification scope, use the AddCacheLevelCallback method.

'specify all possible item and region operations
Dim allCacheOperations As DataCacheOperations
allCacheOperations = DataCacheOperations.AddItem Or _
    DataCacheOperations.ReplaceItem Or _
    DataCacheOperations.RemoveItem Or _
    DataCacheOperations.CreateRegion Or _
    DataCacheOperations.ClearRegion Or _
    DataCacheOperations.RemoveRegion

'add cache-level notification callback 
'all cache operations from a notifications-enabled cache
Dim ndCacheLvlAllOps as DataCacheNotificationDescriptor = _
    myTestCache.AddCacheLevelCallback(allCacheOperations, AddressOf myCacheLvlDelegate)

//specify all possible item and region operations
DataCacheOperations allCacheOperations = DataCacheOperations.AddItem |
    DataCacheOperations.ReplaceItem |
    DataCacheOperations.RemoveItem |
    DataCacheOperations.CreateRegion |
    DataCacheOperations.ClearRegion |
    DataCacheOperations.RemoveRegion;

//add cache-level notification callback 
//all cache operations from a notifications-enabled cache
DataCacheNotificationDescriptor ndCacheLvlAllOps
    = myTestCache.AddCacheLevelCallback(allCacheOperations, myCacheLvlDelegate);

The next example shows what it looks like to add a callback for a cache operation with a region-level notification scope, that is only triggered when a region named TestRegion is added to the cache.

'add region-level notification callback for region "TestRegion"
'trigger notification with CreateRegion operation
Dim ndRegionCreateRegOp As DataCacheNotificationDescriptor
ndRegionCreateRegOp = _
    myTestCache.AddRegionLevelCallback("TestRegion", _
    DataCacheOperations.CreateRegion, AddressOf myRegionLvlAddDelegate)

//add region-level notification callback for region "TestRegion"
//trigger notification with CreateRegion operation
DataCacheNotificationDescriptor ndRegionCreateRegOp
    = myTestCache.AddRegionLevelCallback("TestRegion",
    DataCacheOperations.CreateRegion, myRegionLvlAddDelegate);

The next example shows what it looks like to add a callback for cache operations with an item-level notification scope, that is only triggered when an object is added or replaced in the cache using the key TestKey.

'add item-level notification callback for item "TestKey"
'trigger notification with AddItem and ReplaceItem operations
Dim ndItemUpdateOps As DataCacheNotificationDescriptor
ndItemUpdateOps = _
    myTestCache.AddItemLevelCallback("TestKey", _
    (DataCacheOperations.AddItem Or DataCacheOperations.ReplaceItem), _
    AddressOf myItemLvlUpdateDelegate)

//add item-level notification callback for item "TestKey"
//trigger notification with AddItem and ReplaceItem operations
DataCacheNotificationDescriptor ndItemUpdateOps
    = myTestCache.AddItemLevelCallback("TestKey",
        (DataCacheOperations.AddItem | DataCacheOperations.ReplaceItem),
        myItemLvlUpdateDelegate);

To remove a callback cache notification

1. Use the RemoveCallback method to remove the cache notification callback. Use the appropriate DataCacheNotificationDescriptor object for the nd parameter. Use the NotificationDescriptor that you received when registering for notification to stop receiving notifications.

Example

In this example, the cache client and three DataCacheNotificationDescriptor objects are declared at the class level so that they can be accessed by methods that add and remove callbacks

'define variables for class
Dim myTestCache As DataCache
Dim ndCacheLvlAllOps As DataCacheNotificationDescriptor
Dim ndRegionLvlAllOps As DataCacheNotificationDescriptor
Dim ndItemLvlAllOps As DataCacheNotificationDescriptor

//define variables for class
DataCache myTestCache;
DataCacheNotificationDescriptor ndCacheLvlAllOps;
DataCacheNotificationDescriptor ndRegionLvlAllOps;
DataCacheNotificationDescriptor ndItemLvlAllOps;

This example shows a method that uses the RemoveCallback method to remove the callbacks corresponding to all three DataCacheNotificationDescriptor objects from the previous example.

'remove cache notification callbacks
Public Sub RemoveNotificationCallbacks()
    myTestCache.RemoveCallback(ndCacheLvlAllOps)
    myTestCache.RemoveCallback(ndRegionLvlAllOps)
    myTestCache.RemoveCallback(ndItemLvlAllOps)
End Sub

//remove cache notification callbacks
public void RemoveNotificationCallbacks()
{
    myTestCache.RemoveCallback(ndCacheLvlAllOps);
    myTestCache.RemoveCallback(ndRegionLvlAllOps);
    myTestCache.RemoveCallback(ndItemLvlAllOps);
}