Share via


Add a Cache Notification Callback (Windows Server AppFabric Caching)

Windows Server AppFabric allows your cache-enabled application to receive cache notifications. This topic describes how to add a cache notification callback that will enable your application to receive cache notifications. For more information about cache notifications, see Cache Notifications (Windows Server AppFabric Caching).

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:

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.

Note

For your application to use notifications, you need to enable them on a named cache. Use the notificationsEnabled parameter with the New-Cache or Set-CacheConfig commands. For more information, see Using Windows PowerShell to Manage Windows Server AppFabric Caching Features.

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.

Note

We do not recommend you do this in a production application. This example is for demonstration only.

'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.

Note

Only item operations AddItem, ReplaceItem, and RemoveItem can trigger cache notifications with item-level callbacks. Specifying region operations in the filter parameter, when adding an item-level callback, will cause an exception.

'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);

See Also

Concepts

Add a Failure Notification Callback (Windows Server AppFabric Caching)
Remove a Cache Notification Callback (Windows Server AppFabric Caching)
Cache Notifications Methods (Windows Server AppFabric Caching)
Using Windows PowerShell to Manage Windows Server AppFabric Caching Features