Getting Started with NCache Open Source

NCache Open Source provides in-memory caching for .NET applications. The examples in this guide use the Open Source 5.3.603 release and its matching client package. This guide walks you through obtaining a free key, choosing a deployment option, configuring a cache, and using it to store and retrieve application data.

Get a Free Key for NCache Open Source

NCache Open Source is free, but you must register it before starting a cache. Visit Get NCache Open Source Key (Free) and complete the registration process to obtain your key. Keep the key available for the Windows installation or container registration steps below.

Choose one of the following deployment options. After completing it, continue to Create a Cache and Connect.

Option 1: Install on Windows

Install NCache Open Source on each Windows machine that will host a cache server.

  • Download the Open Source Windows installer from NCache Downloads.
  • Run the downloaded .msi file and follow the installation wizard. Select Cache Server as the installation type and provide your free Open Source key when prompted.
  • After installation, ensure that the NCache Service is running. Open PowerShell as an administrator and check its status:
Get-Service -Name NCacheSvc
  • If the service is stopped, start it:
Start-Service -Name NCacheSvc

For detailed instructions, see Windows Installation.

Option 2: Run as a Docker Container

The official Open Source image runs NCache on Linux. Install Docker with support for Linux containers before continuing.

  • Pull the Open Source image, then create and start a container exposing port 9800 for client connections:
docker pull alachisoft/ncache:latest-oss
docker run -d --name ncache-oss -p 9800:9800 alachisoft/ncache:latest-oss
  • Register the running container using your free key. Replace YOUR_OSS_KEY with the key you obtained earlier:
docker exec -it ncache-oss /opt/ncache/bin/tools/register-ncacheopensource -Key YOUR_OSS_KEY
  • List the configured caches:
docker exec -it ncache-oss /opt/ncache/bin/tools/get-caches
Note

This example exposes the client port for a single-container setup. A Replicated cache spanning containers also requires connectivity between its cache servers on the configured cluster port. For image tags and networking settings, see the Open Source Docker instructions.

Option 3: Run with Kubernetes

Use the Open Source YAML manifests to deploy NCache on a Kubernetes cluster with Linux worker nodes. Ensure that kubectl is configured to access your cluster before continuing.

  • Download ncache.yaml, discoveryservice.yaml, and client-gatewayservice.yaml from the Open Source Kubernetes folder.
  • In ncache.yaml, set spec.serviceName to cacheserver to match the headless Service in discoveryservice.yaml. Select the Open Source image tag you intend to deploy. Remove the imagePullSecrets entry when using the public image without registry credentials.
  • Create a namespace and apply the manifests from the directory where you saved them:
kubectl create namespace ncache
kubectl apply --namespace ncache -f discoveryservice.yaml
kubectl apply --namespace ncache -f ncache.yaml
kubectl apply --namespace ncache -f client-gatewayservice.yaml
  • Check the pods and their IP addresses. The supplied StatefulSet creates two pods named ncache-0 and ncache-1:
kubectl get pods --namespace ncache -l app=ncache -o wide
  • Once the containers are running, register each server with your free key:
kubectl exec -it ncache-0 --namespace ncache -- /opt/ncache/bin/tools/register-ncacheopensource -Key YOUR_OSS_KEY
kubectl exec -it ncache-1 --namespace ncache -- /opt/ncache/bin/tools/register-ncacheopensource -Key YOUR_OSS_KEY

The pods are now available for cache configuration. Use their reported IP addresses in the Replicated cache configuration below. For platform prerequisites, gateway access, and configuration updates, see Deploy NCache Open Source with Kubernetes.

Important

Keep the cache configuration outside the containers as well. After a pod is replaced, verify its IP address and restore or update the configuration on the affected servers before using the cache.

Create a Cache and Connect

After installing or deploying NCache, configure a cache on the server and provide its connection details to your application. The following examples use a Local cache on one server or a Replicated cache on two servers.

Configure a Local or Replicated Cache

  • Open the server's config.ncconf file in a text editor. On Windows, it is located in %NCHOME%\config; in the Linux container, it is located in /opt/ncache/config.
  • Check whether the cache already exists. The Docker image includes defaultCache and defaultLocalCache, so edit the existing entry when using these names. To create another cache, add a complete <cache-config> entry inside <configuration> and give it a unique name.

For a standalone cache on one server, use the following Local cache configuration:

<cache-config cache-name="defaultLocalCache" alias="" config-id="e097c2c0-88af-4aa2-8a8a-c6432eeaa3fe" config-version="0" store-type="distributed-cache">
  <cache-settings inproc="False" data-format="Serialized" serialization="Json">
    <logging enable-logs="True" trace-errors="True" trace-debug="False" log-path=""/>
    <performance-counters enable-counters="True"/>
    <cleanup interval="15sec"/>
    <storage type="heap" cache-size="1024mb"/>
    <eviction-policy enabled-eviction="True" 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 a two-server cluster, use the following Replicated cache configuration. Replace 20.200.20.11 and 20.200.20.12 with your cache server or pod IP addresses:

<cache-config cache-name="defaultCache" alias="" config-id="44fb997a-f6a7-433b-9439-7ef9de9f47c7" config-version="0" store-type="distributed-cache">
  <cache-settings inproc="False" data-format="Serialized" serialization="Json">
    <logging enable-logs="True" trace-errors="True" trace-debug="False" log-path=""/>
    <performance-counters enable-counters="True"/>
    <cleanup interval="15sec"/>
    <storage type="heap" cache-size="1024mb"/>
    <eviction-policy enabled-eviction="True" default-priority="normal" policy="priority" eviction-ratio="5%"/>
    <cache-topology topology="replicated">
      <cluster-settings operation-timeout="60sec" stats-repl-interval="300sec">
        <cluster-connection-settings port-range="1" connection-retries="1" connection-retry-interval="2secs" cluster-port="9851"/>
      </cluster-settings>
    </cache-topology>
    <client-death-detection enable="False" grace-interval="60sec"/>
  </cache-settings>
  <cache-deployment deployment-version="0">
    <servers>
      <server-node ip="20.200.20.11"/>
      <server-node ip="20.200.20.12"/>
    </servers>
  </cache-deployment>
</cache-config>
  • Save the complete Replicated cache configuration on both servers, including the same cache name, cluster port, and server list. Each separate cache cluster must use a different cluster port.
Note

Open Source edition limits and available management features are listed in the Edition Comparison. Use the Open Source command-line tools or supported PowerShell cmdlets to manage the cache.

Start and Verify the Cache

After saving configuration changes, restart the NCache Service so that it loads the updated configuration. On Windows, run the following in an administrator PowerShell session on each affected server:

Restart-Service -Name NCacheSvc

For containers, follow the service restart procedure in Open Source Kubernetes Deployment. Preserve and restore the configuration if a container is recreated.

  • On Windows, start the cache with Start-Cache, then verify it with Get-Caches. Run these commands on each server:
Start-Cache -Name defaultCache
Get-Caches -Detail
  • For Docker, run the equivalent tools inside the container:
docker exec -it ncache-oss /opt/ncache/bin/tools/start-cache -Name defaultCache
docker exec -it ncache-oss /opt/ncache/bin/tools/get-caches
  • For Kubernetes, run the tools in each server pod. For example, on the first pod:
kubectl exec -it ncache-0 --namespace ncache -- /opt/ncache/bin/tools/start-cache -Name defaultCache
kubectl exec -it ncache-0 --namespace ncache -- /opt/ncache/bin/tools/get-caches

Repeat on ncache-1. For a Local cache, use defaultLocalCache instead of defaultCache. Confirm that the intended cache is running before connecting your application.

Configure the Client Connection

Your application needs the cache name and a reachable server endpoint. After installing the client package in the next section, configure the application's client.ncconf file with the cache entry below. Place it inside the file's <configuration> element:

<cache id="defaultCache" client-cache-id="" load-balance="false" enable-client-logs="False" log-level="error">
  <server name="20.200.20.11"/>
  <server name="20.200.20.12"/>
</cache>

Replace the addresses with endpoints reachable from the application. For a Local cache, use defaultLocalCache and one server entry. For the Docker example, use the Docker host's address and published port 9800. Ensure that the client configuration is available to the running application.

For Kubernetes clients outside the cluster, inspect the gateway:

kubectl get service gateway --namespace ncache

The supplied gateway uses NodePort. Use a reachable worker-node address and its assigned node port. For example, if the Service reports 9800:32000/TCP, use port 32000 in the server entry:

<server name="20.200.20.11" port="32000"/>

Ensure that the application can also reach any additional server endpoints required by the cache. See Connect and Verify the Application for networking details.

Use NCache in Your .NET Application

Create a .NET Console Application, install the Open Source client package, and use the configured cache to store and retrieve data.

  • In Visual Studio, open Tools > NuGet Package Manager > Package Manager Console and install the Open Source SDK package:
Install-Package Alachisoft.NCache.OpenSource.SDK -Version 5.3.603
  • Configure client.ncconf as described above, using the cache name and endpoints for your deployment.
  • Replace the console application's code with the following example. It connects to defaultCache, inserts a value, and reads it back. Insert allows you to run the example repeatedly with the same key:
using System;
using Alachisoft.NCache.Client;

class Program
{
    static void Main()
    {
        try
        {
            using (ICache cache = CacheManager.GetCache("defaultCache"))
            {
                string key = "Product:1005";
                cache.Insert(key, "Coffee");
                string product = cache.Get<string>(key);
                Console.WriteLine($"Retrieved from cache: {product}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Cache operation failed: {ex.Message}");
        }
    }
}

Run the application. A successful connection and read prints Retrieved from cache: Coffee. If you configured a Local cache, replace defaultCache with defaultLocalCache in both the client configuration and application code.

Test and Monitor Cache Activity

You can generate additional cache activity with Test-Stress. On Windows, run:

Test-Stress -CacheName defaultCache

For Docker, run the tool inside the container:

docker exec -it ncache-oss /opt/ncache/bin/tools/test-stress -CacheName defaultCache

For Kubernetes, run the same tool through kubectl exec in a server pod. On Windows, open Performance Monitor, add the supported NCache counters, and select your cache instance to observe activity. See Edition Comparison for the counters available in Open Source.

For further development, see Basic Cache Operations and Item-Level Event Notifications. Server logs are available in %NCHOME%\log-files on Windows and /opt/ncache/log-files in the container.

See Also

NCache Installation
Open Source Docker Instructions
Open Source Kubernetes Deployment
NCache Developer's Guide