Getting Started with NCache Open Source

This guide provides the basic steps you should follow to get started with NCache Open Source.

Step 1: Create Cache

Add configurations for creating necessary cache in the config.ncconf file in the cache server.

Warning

NCache Open Source only supports Local and Mirrored Caches.

  1. Open %NCHOME%\config\config.ncconf file on your local machine.

  2. Copy and paste the entire <cache-config> section from the examples below to the <configuration> section of config.ncconf file.

  3. You can modify this configuration to change the cache name, as required.

Note

You can read more about config.ncconf in the NCache Administrators Guide.

Important

Each cache should have a unique name.

For Local Cache

NCache Open Source supports a standalone (non-clustered) cache residing on a single node.

Warning

NCache Open Source can only connect to a single client at a time.

<cache-config cache-name="myCache" alias="" config-id="e097c2c0-88af-4aa2-8a8a-c6432eeaa3fe" config-version="0">
    <cache-settings inproc="False">
      <logging enable-logs="True" trace-errors="True" trace-debug="False" log-path=""/>
      <performance-counters enable-counters="True" snmp-port="0"/>
      <cleanup interval="15sec"/>
      <storage type="heap" cache-size="1024mb"/>
      <eviction-policy enabled-eviction="False" default-priority="normal" policy="priority" eviction-ratio="5%"/>
      <cache-topology topology="local-cache"/>
      <client-death-detection enable="False" grace-interval="60sec"/>
    </cache-settings>
</cache-config>

For Mirrored Cache

A cache cluster is a set of interconnected server nodes forming a cluster of servers that behave as a single cache unit from the outside. To create a mirrored cache, you can use a copy of the same configuration as for the local cache with the change that under the <cache-settings> tag, you need to add the <cache-topology> tag as "mirrored" and a new <cache-deployment> tag which contains the cache server information. This sample config adds a server, 20.200.20.40:

<cache-config cache-name="demoCache" alias="" config-id="44fb997a-f6a7-433b-9439-7ef9de9f47c7" config-version="0">
    <cache-settings inproc="False">
      <logging enable-logs="True" trace-errors="True" trace-debug="False" log-path=""/>
      <performance-counters enable-counters="True" snmp-port="0"/>
      <cleanup interval="15sec"/>
      <storage type="heap" cache-size="1024mb"/>
      <eviction-policy default-priority="normal" eviction-ratio="5%"/>
      <cache-topology topology="mirrored">
        <cluster-settings operation-timeout="60sec" stats-repl-interval="60sec" use-heart-beat="False">
          <cluster-connection-settings port-range="1" connection-retries="2" connection-retry-interval="2secs" cluster-port="7801"/>
        </cluster-settings>
      </cache-topology>
      <client-death-detection enable="False" grace-interval="60sec"/>
    </cache-settings>
    <cache-deployment>
      <servers>
        <server-node ip="20.200.20.29"/>
      </servers>
    </cache-deployment>
</cache-config

Please note the following:

  • Replace the IP Addresses given in the <cache-deployment> section with the IP Addresses of your cache servers. The node to join first will be the active node, and the other will act as the passive node.
  • For clustered caches, you can have a single server if you want to test on your machine.
  • Every cache cluster should have a unique cluster-port. Otherwise, the port conflict will cause the cache to start to fail. However, all nodes of the same cluster must have the SAME <cluster-port>, or cache nodes may fail to join and form a cluster.
  • You need to copy this configuration on all of your cache servers.

Step 2: Add Local/Remote Client

Important

At a time, your cache can only connect to 1 client, it can be local or remote.

  1. Copy and paste the entire <cache> section from the example below to the <configuration> section in the client.ncconf file.

    <cache id="demoCache" load-balance="True" enable-client-logs="False" log-level="error">
   <server name="20.200.20.40"/>
</cache>

  2. Make sure your cache id is unique within the client.ncconf file.

  3. Replace the ip address specified in the name property of <server> tag to your server's ip address. Mention all the cache server ip addresses here as separate <server> tags.

  4. Please perform this step for all cache clients.

Step 3: Restart NCache Service

For the configuration changes made to take effect, you will need to restart the NCache Service. Therefore, you need to make sure you have enough privileges to restart the service. If the user is not an Administrator, run PowerShell as an administrator. Otherwise, you might get an error message, "Cannot open NCacheSvc service on computer."

Execute the following command in PowerShell to restart the NCache Service:

Restart-Service -Name NCacheSvc
Warning

The NCache Service fails to start if the configuration file has a missing tag or incorrect tag syntax.

Make sure that the NCache Service has successfully started.

Step 4: Verify Cache Creation

To verify successful creation of the cache, open PowerShell and use the Get-Caches cmdlet (shipped with NCache) with the -Detail parameter which displays all registered caches on the server and respective nodes of the cache cluster along with additional information.

Get-Caches -Detail -Server 20.200.20.40

For example, if a demoCache has been created, the list will contain demoCache with the nodes and the status "Stopped." If the list does not display the cache, there might have been some mistake while changing the configuration, or the NCache Service may not have been restarted.

Step 5: Start Cache

Once cache creation is verified, start the cache on each server through PowerShell using the Start-Cache cmdlet.

Start-Cache -Name demoCache
Important

Repeat this step on all cache server nodes.

Step 6: Monitor Cluster Health

Both local and clustered caches publish performance statistics using Windows Performance Counters. NCache also publishes performance statistics of the cache from the client's perspective. In this step, you will verify that the Stress Test Tool that you ran in the previous step is making cache calls successfully.

To view the statistics of a running cache, type PerfMon in the Windows search bar.

  1. Performance Monitor appears in the search result. Open Performance Monitor.

  2. Click on the Performance Monitor in the Monitoring tool in the left pane. The Performance Monitor window opens up in the right pane.

  3. Click on the Add (+) button. This opens the Add Counters pop-up window.

  4. By default, it shows the Performance Counter categories on the local system. If the cache is running on a different computer, type the computer name or IP prepended by “\\” e.g., \\20.200.20.220 or \\TEST.

  5. Scroll up in the Performance Categories window to find and select NCache.

  6. Although, NCache publishes a lot of statistics, you can select the following basic counters to monitor the cache:

    • Additions/sec: This shows the number of new cache items being added per second.

    • Count: This shows the number of items present in the cache

    • Expirations/sec: This shows the number of items expired per second.

    • Fetches/sec: This shows the number of cache items read by your application from the cache.

    • Request/sec: This shows the number of requests received (meaning cache commands like add, get, insert, remove, etc.) from all clients to this cache server.

    • Updates/sec: This shows the number of the existing cache items updated per second.

  7. Every cache publishes its statistics under its cache name. Select the cache you want to monitor and click the Add button at the bottom.

  8. Click OK.

  9. Change graph type from Line to Report.

Monitor Caches PerfMon Monitor

Step 7: Install NuGet Packages

To create an application to connect with your cache, follow the steps below:

  1. Create a new .NET Console Application.

  2. To install NuGet packages, open Visual Studio and go to Tools -> NuGet Package Manager -> Package Manager Console.

  3. Install the NCache NuGet package through the Package Manager Console as follows:

Install-Package Alachisoft.NCache.OpenSource.SDK

Step 8: Import Namespaces

Add the following namespaces to your Program.cs file or similar:

using Alachisoft.NCache.Client;
using Alachisoft.NCache.Runtime.Exceptions;

Step 9: Serialize Objects

Go to Solutions and select Add->Class to create a new class Product as follows:

[Serializable]
public class Product
{
    // Properties being defined below
    public int ProductID {...}
    public string ProductName {...}
    public string Category {...}
    public string UnitsInStock {...}
}

Step 10: Connect to a Single Cache

Intialize and Connect using the GetCache API, as demonstrated below:

// Specify the cache name
string cacheName = "demoCache";

// Connect to cache
ICache cache = CacheManager.GetCache(cacheName);

Step 11: Begin Data or Session Caching

Once the cache is connected, you can utilize the NCache features available to you as part of NCache Open Source. First, include the following namespaces:

  • Alachisoft.NCache.Client
  • Alachisoft.NCache.Runtime.Exceptions

The following example adds a basic CacheItem containing the Product object into the cache.

// Precondition: Cache is already connected

// Get product from database against given product ID
Product product = FetchProductFromDB(1001);

// Generate a unique cache key for this product
string key = $"Product:{product.ProductID}";

// Create a new CacheItem for this product
// You can OPTIONALLY specify multiple properties e.g. Priority, Expiration
// These properties are explained in successive chapters

var cacheItem = new CacheItem(product);
// cacheItem.AbsoluteExpiration = DateTime.Now.AddMinutes(5);

// Add CacheItem to cache
CacheItemVersion version = cache.Add(key, cacheItem);

You can see what features are available as part of NCache Open Source using the Edition Comparison.

See Also

NCache Installation
NCache Programmer's Guide
NCache Command Line Interface