Share via

Extend the DataCacheStoreProvider Class (AppFabric 1.1 Caching)

  • Article

This topic describes how to create a read-through / write-behind provider for Windows Server AppFabric Caching. You create a provider by implementing the abstract base class DataCacheStoreProvider.

Create the provider project

  1. In Visual Studio 2010, create a new Class Library project.

  2. Add a reference to the Microsoft.ApplicationServer.Core.dll assembly. By default this assembly is located in .\Program Files\Windows Server AppFabric.

  3. Open the source file for this project, which is Class1.cs or Class1.vb depending on the project language.

  4. At the top of the source file, add a using statement (Imports in Visual Basic) to the Microsoft.ApplicationServer.Caching namespace.

    using Microsoft.ApplicationServer.Caching;

    Imports Microsoft.ApplicationServer.Caching

  5. Modify the class to inherit from DataCacheStoreProvider. Note that the Visual Studio 2010 code editor provides a feature for automatically creating empty functions from this class. In Visual C#, right-click the DataCacheStoreProvider class and select Implement Abstract Class. In Visual Basic, press enter after the Inherits line.

    namespace RTProvider
{
    public class Provider : DataCacheStoreProvider

    Public Class Provider
    Inherits DataCacheStoreProvider

  6. Sign the assembly in order to install it into the Global Assembly Cache with a strong name. In Solution Explorer, right-click the project and select Properties. In the Signing section of the project properties, check the Sign the assembly checkbox. In the Choose a strong name key file drop-down list, select an existing key file or select <New...> to create a new one.

Add a public constructor

Each provider should implement a public constructor with the following signature:

public ProviderClass(string cacheName, Dictionary<string,string> config)

Replace ProviderClass in the example above with the name of your class that implements the methods of the DataCacheStoreProvider. This constructor is called when a cache first enables read-through or write-behind on a running cache host. It is also called each time the cache host is restarted. The constructor takes the following two parameters:

Parameter Description

cacheName

This string is the name of the cache that is being associated with this provider. This name can be stored for future use. For example, it is necessary to know the cache name when creating new DataCacheItem objects in response to read requests.

config

This Dictionary<string,string> object contains configuration settings for the provider. These settings are custom to the provider and its configuration needs at runtime. They are passed using the ProviderSettings parameter of the New-Cache or Set-CacheConfig Windows Powershell command.

Implement the provider methods

The methods of the DataCacheStoreProvider class must be implemented by the provider. Note that if you are creating only a read-through provider, you are not required to implement the "Write" methods. Similarly, if you are creating only a write-behind provider, you are not required to implement the "Read" methods.

The method names generally describe their purpose. The following table describes the methods without including the overloads.

Method Description

Read

Called when a cache client requests a cached item that does not currently exist in the associated cache.

Write

Called for items that cache clients have recently added or changed in the cache.

Delete

Called when a cache client removes an item from the associated cache.

Dispose

Disposes provider.

There are two methods for reading. The first Read method is passed a DataCacheItemKey parameter that identifies the single item to return. The other Read overload is passed a collection of DataCacheItemKey objects to retrieve and pass back in a Dictionary of DataCacheItemKey and DataCacheItem objects. This dictionary object is initially empty and read items must be added before returning from the Read method. Note that you use the DataCacheItemFactory class to create the requested items as in the following example.

DataCacheItem dataCacheItem = DataCacheItemFactory.GetCacheItem(key, CACHE_NAME, objectValue, null);

In the previous example, the CACHE_NAME string should be set to the name of the cache that was previously passed to the overloaded constructor. The key is the DataCacheItemKey that is requested. The objectValue is the object that should be returned to the clients for this cache key.

In the same way, there are two methods for writing. The first Write method is passed a DataCacheItem object. Note that the Key property of this object contains the associated DataCacheItemKey and the Value property contains the value. The other Write method is passed a Dictionary of DataCacheItemKey and DataCacheItem objects.

Important

It is important to remove the items from the Dictionary<DataCacheItemKey, DataCacheItem> object as you write them to the backend store. If the items are not removed, the cache considers this to be a failed write and retries the operation later.

Error Handling

If there are any errors, you can throw a DataCacheStoreException exception object. The result of this exception will vary depending on whether the exception happens during the Read or Write methods. The following table describes these differences.

Method Result of thrown exception

Read

The cache client performing the read receives a DataCacheException exception with the ErrorCode property equal to DataCacheErrorCode.ReadThroughProviderFailure (The text of the exception includes the code "<ERRCA0025>").

Write

The write is assumed to have failed and will be retried based on the cache's retry policy for write-behind operations. The cache client does not get informed of this error.

There are three possible DataCacheErrorCode values that a cache client can receive during DataCache.Get calls that access the read-through provider.

  1. DataCacheErrorCode.ReadThroughProviderFailure

  2. DataCacheErrorCode.ReadThroughProviderDidNotReturnResult

  3. DataCacheErrorCode.ReadThroughProviderNotFound

Also note that the time spent in the Read methods of the provider adds to the total request time for the DataCache.Get method. Because of this, you may need to increase the request timeout to account for any delay introduced by your provider. For more information, see Configuring Cache Client Timeouts (Windows Server AppFabric Caching).

Testing and debugging the provider

For development and testing, it might be preferable to setup a single-node cache cluster on the development machine. This allows you to quickly rebuild, re-add the assembly to the local Global Assembly Cache, and restart the local cache cluster. The following steps show how to debug the provider.

  1. Open the provider project on Visual Studio 2010.

  2. On the Debug menu, click Attach to Process.

  3. Check Show processes from all users and Show processes in all sessions.

  4. Select the DistributedCacheService.exe process.

  5. Click the Attach button.

  6. Set breakpoints in your provider code and perform operations on the cache from another application that results in calling the provider methods.

Warning

Stopping the debugging session without detaching the debugger will stop the caching service on the machine. This results in a loss of all cached data on that machine.

See Also

Concepts

Deploy a Read-Through / Write-Behind Provider (AppFabric 1.1 Caching)
Enable Read-Through and Write-Behind on a Cache (AppFabric 1.1 Caching)

  2012-09-12