Get Started with a Simple Client (XML)

Article
11/12/2009

Microsoft project code named "Velocity" offers the option to configure a cache client programmatically or by using an application configuration file. The following procedures describe how to configure a simple client for your application by using an XML-based application configuration file. For information about how to do this programmatically, see Get Started with a Simple Client.

The cache client type is defined by the deployment attribute in the dataCacheClient element. For a simple client, the deployment attribute is equal to simple. For more information about the application configuration settings, see Application Configuration Settings.

These procedures assume that you have already prepared your development environment, set references to the "Velocity" assemblies, and so on. For more information, see Prepare the Development Environment.

Data in the cache is not encrypted and is available to any cache client with the appropriate configuration settings. We highly recommend that you secure the XML-based application configuration files used to specify the cache client.

To configure a simple client using an application configuration file

From the Project menu in Visual Studio, select Add New Item.
Select Application Configuration File, name the file app.config, and then click Add.
Paste the XML example in the following section inside the <configuration> tags of your app.config file. Your application may use the application configuration file for other purposes, but make sure that the configSections element remains the first element under configuration tag.
Update or add host elements for the cache hosts as appropriate for your environment. For each:
1. Use the name attribute to specify the computer name of the cache host.
2. Use the cachePort attribute to specify the cache port number of the host.
3. Use the cacheHostName attribute to specify the name of the cache host service.
In your code, create a DataCacheFactory object using the default construct. By not passing configuration parameters to the DataCacheFactory object, your application will use the configuration settings in the app.config file.
To begin using the cache client, use the GetCache method to create a DataCache object.

Example

This example application configuration file has local cache disabled and is configured to point to a cache server named CacheServer1. Replace the server name in this example with that of your cache server's name. Add additional host tags for other cache hosts in the cluster.

Ideally, specify those cache hosts that have been designated as lead hosts. Lead hosts are usually the first cache servers installed in the cluster. For more information about lead hosts, see Velocity Physical Architecture Diagram.

You can determine which hosts are lead hosts by using the PowerShell administration tool. For more information about PowerShell, see Cache Administration with Windows PowerShell.

Note

Visual Basic may at first automatically add elements to your application configuration file. Those additional elements are not required by "Velocity" and may be deleted if you do not otherwise need them for your application.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  
  <!--configSections must be the FIRST element -->
  <configSections>
    
    <!-- required to read the <dataCacheClient> element -->
    <section name="dataCacheClient"
       type="Microsoft.Data.Caching.DataCacheClientSection,
       CacheBaseLibrary"
       allowLocation="true"
       allowDefinition="Everywhere"/>
    
    <!-- required to read the <fabric> element, when present -->
    <section name="fabric"
       type="System.Data.Fabric.Common.ConfigFile,
       FabricCommon"
       allowLocation="true"
       allowDefinition="Everywhere"/>
    
  </configSections>

  <!-- simple client -->
  <dataCacheClient deployment="simple">
    
    <!-- (optional) specify local cache 
    <localCache
      isEnabled="true"
      sync="TTLBased"
      objectCount="100000"
      ttlValue="300" />
    -->

    <!-- note: cache notifications are
         not supported with simple client -->
    
    <!-- cache host(s) -->  
    <hosts>
      <host
         name="CacheServer1"
         cachePort="22233"
         cacheHostName="DistributedCacheService"/>
    </hosts>
  </dataCacheClient>
</configuration>

After you have specified the cache client configuration settings in the application configuration file, begin programming your cache-enabled application. This example creates a DataCacheFactory object named CacheFactory1 using the default construct. Because the cache client configuration settings are not passed to the parameters of the DataCacheFactory constructor, the cache client will be configured based on the settings specified in the application configuration file.

Note

For performance reasons, we recommend that you minimize the number of DataCacheFactory objects created in a cache-enabled application. Store the DataCacheFactory object in a variable available to all parts of the application that use cache clients.

Next, the GetCache method is used to create a DataCache object, named myCache1. Then the Add method is called to add an object to cache.

'configure cache client with application configuration file
Dim CacheFactory1 As DataCacheFactory = New DataCacheFactory()

'get cache client for cache "Cache1"
Dim myCache1 As DataCache = CacheFactory1.GetCache("Cache1")

'add an object to cache
myCache1.Add("helloKey", "hello world")

//configure cache client with application configuration file
DataCacheFactory CacheFactory1 = new DataCacheFactory();

//get cache client for cache "Cache1"
DataCache myCache1 = CacheFactory1.GetCache("Cache1");

//add an object to cache
myCache1.Add("helloKey", "hello world");

Get Started with a Simple Client (XML)

Example

See Also

Concepts

Additional resources