How to: Get Started with a Routing Client (XML) (Velocity)

Article
06/24/2009

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Microsoft project code named "Velocity" offers the option to configure the cache client programmatically or with an application configuration file. The procedures in this topic describe how to configure a routing client for your application by using an XML-based application configuration file. For information about how to do this programmatically, see How to: Get Started with a Routing Client (Code) (Velocity).

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

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

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 two servers, CacheServer1 and CacheServer2. Replace the server names in this example with those of your cache server's name. Add or remove host tags as necessary to suit your environment.

Ideally, specify those cache hosts that have been designated lead hosts. Lead hosts are usually the first cache servers installed in the cluster. For more information about lead hosts, see the Physical Model section in General Concept Models (Velocity).

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

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>
  
  <!-- routing client-->
  <dataCacheClient deployment="routing">

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

    <!--(optional) specify cache notifications poll interval 
    <clientNotification pollInterval="300" />
    -->
    
    <!-- cache host(s) -->    
    <hosts>
      <host
         name="CacheServer1"
         cachePort="22233"
         cacheHostName="DistributedCacheService"/>
      <host
         name="CacheServer2"
         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");

How to: Get Started with a Routing Client (XML) (Velocity)

To configure a simple client using an application configuration file

Example

See Also

Tasks

Concepts

Other Resources

Additional resources