How to Connect to Cache
After successfully configuring NCache, you can start developing applications utilizing NCache by embedding NCache API calls. In order to do that, you need to connect to the cache. Single as well as multiple caches can be connected in a single application. Moreover, the cache can be connected with security credentials.
Connect to Single Cache
ICache interface to get an instance of NCache’s cache. Moreover, the
CacheManager class lets you connect to the cache instance via the
The following example connects to a cache named demoCache which is in running state.
// Specify the cache name string cacheName = "demoCache"; // Connect to cache ICache cache = CacheManager.GetCache(cacheName);
To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Connect to Multiple Caches
GetCache method, you can connect to multiple caches within a single application. This will help you manage the data of multiple caches using one application.
The following example connects to two caches, demoCache and demoClusteredCache from the same client.
// Specify cache names string cacheName1 = "demoCache"; string cacheName2 = "demoClusteredCache"; // Connect to the caches ICache cache1 = CacheManager.GetCache(cacheName1); ICache cache2 = CacheManager.GetCache(cacheName2);
Connect to Cache Using CacheConnectionOptions
CacheConnectionOptions allows specifying values of cache properties while establishing a connection to the cache. These values are the same which can be configured through client.ncconf file.
Any configuration specified through
CacheConnectionOptions will override the value in client.ncconf for that particular client.
In this example, the values of the
KeepAliveInterval properties can be changed. For this application, these values will be used instead of the ones specified in the client configuration file.
// Create new CacheConnectionOptions instance var options = new CacheConnectionOptions(); // Specify the cache connection options to be set options.RetryInterval = TimeSpan.FromSeconds(5); options.ConnectionRetries = 2; options.EnableKeepAlive = true; options.KeepAliveInterval = TimeSpan.FromSeconds(30); // Specify the cache name string cacheName = "demoCache"; // Connect to cache with CacheConnectionOptions ICache cache = CacheManager.GetCache(cacheName, options);
Connect to Clustered and Client Cache
GetCache method to connect to clustered and Client Cache in a single call is not a recommended approach.
One can connect to clustered and Client Cache in a single call using the
GetCache method. This will initialize both the caches within a single application, hence helping you manage the data of multiple caches through one application.
If the local cache is connected to the Client Cache, serialization must be the same as that of the clustered cache. Both caches must be configured previously and must be in a running state.
The following example connects to two caches using the
// Specify the cache names string clusteredCache = "demoCache"; string clientCache = "myClientCache"; CacheConnectionOptions cacheConnectionOptions = new CacheConnectionOptions(); cacheConnectionOptions.LoadBalance = true; cacheConnectionOptions.ConnectionRetries = 5; CacheConnectionOptions clientCacheConnectionOptions = new CacheConnectionOptions(); clientCacheConnectionOptions.LoadBalance = true; clientCacheConnectionOptions.ConnectionRetries = 5; clientCacheConnectionOptions.Mode = IsolationLevel.OutProc; // Connect to the caches in a single call // CacheConnectionOptions which can be null if not required ICache cache = CacheManager.GetCache(clusteredCache, cacheConnectionOptions, clientCache, clientCacheConnectionOptions);
Connect to Cache with Security Credentials
If security has been enabled, you need to provide the security credentials while connecting to the caches so that the authorized user can perform the operation. For more details on using security in NCache, see NCache Security.
// Specify cache name and user credentials string cacheName = "demoCache"; string userId = "userid"; string password = "mypassword"; // Initialize the CacheConnectionOptions var options = new CacheConnectionOptions(); // Enter the credentials options.UserCredentials = new Credentials(userId, password); // Connect to the cache using the security credentials ICache cache = CacheManager.GetCache(cacheName, options);
Unable to Find client.ncconf
Sometimes a client may be unable to find the client.ncconf file while connecting to the cache. This happens when NCache directory (
%NCHOME%) is not set.
%NCHOME% is not set, follow the steps below to set the environment variable for it:
- Right-click on the Start button and select System.
- In the right pane, click on Advanced System Settings.
- In the System Properties window, go to the Advanced tab and click on the Environment Variables button.
- In the Environment Variables window, under System Variables, click on New.
- For Variable Name enter
- For Variable Value, enter the path to your JDK installation directory (for example,
- Click OK.
- Now to update the system path in the same Environment Variables window, find the Path variable and click Edit.
- In the Edit Environment Variable window, click New and add
%NCHOME%\binto the list. This makes sure that the tools are available globally.
- Click OK to close each of the windows.
No server available to process request
Sometimes a client may be unable to connect to the cache because the Client/Server Port is blocked by a firewall.
Make sure that the Client/Server port (at which NCache Service starts and accepts different client connections) is not blocked by a firewall. The default value of this port is '9800'. You can change the default value from Alachisoft.NCache.Service.exe.config or Alachisoft.NCache.Service.dll.config file.
Unable to communicate with server node
Cluster nodes can also be unable to communicate with each other because of Cluster Ports being blocked by a firewall.
Error: "Unable to communicate with server node"
See if your firewall is allowing the Client/Server and Cluster port. A cluster port is a port at which nodes in a cluster communicate. You can change the default value of these ports from NCache Management Center. If you have specified a port range in the NCache Management Center, unblock all ports in the range.
Client Socket Deadlock
You may experience a deadlock situation on your client socket because of a long wait for a response from the cache server. This may also result in a lot of waiting threads that may cause performance issues.
Step1: Changes on Server-side
Go to the service configuration file:
- .NET Windows: Alachisoft.NCache.Service.exe.config located in %NCHOME%\bin\service
- .NET Core Windows: Alachisoft.NCache.Service.dll.config located in %NCHOME%\bin\service
- .NET Core Linux: Alachisoft.NCache.Daemon.dll.config located in /opt/ncache/bin/service
Add the following lines in the configuration file:
<add key ="NCacheServer.EnableBadClientDetection" value = "true" />
The value "true" indicates that BadClientDetection is enabled on your client socket. This means that now if a deadlock situation arises on your client socket, the socket will be reset. The default value of this property is "false".
<add key ="NCacheServer.ClientSocketSendTimeout" value = "10" />
When you have enabled
BadClientDetection, you can specify the time interval after which the socket is reset in case of a deadlock. The default value of this property is "10" and this value can not be less than 1.
A few other properties have also been introduced in Alachisoft.NCache.Service.exe.config to help with this issue. Please configure these properties as follows:
<add key ="NCacheServer.EventPriorityRatio" value="30"/>
On the server side, a priority queue is used for events and cache operations. You can configure a ratio of events and cache operations for this queue through the property called
EventPriorityRatio. The default value of this property is 30 which indicates a ratio of 30:70 for events and cache operations. The value of this property can not be less than 1.
<add key ="NCacheServer.EventBulkCount" value="50"/>
The cache server now sends events to clients in bulk. Through this property, you can set the number of items to be sent in bulk. By default, this value is 50 and the value can not be less than 1. This is available in client version 4124 and above.
<add key ="NCacheServer.EventBulkCollectionInterval" value="2"/>
This property is used to set the time interval, in seconds, after which the bulk of events is fired even in case the bulk count does not reach the
EventBulkCount that the user has specified. The default value for this property is 2 seconds and the value can not be less than 1.
Restart the NCache service for these changes to take effect.
Step2: Changes on Client Side
Please make the following changes in your App.config/Web.config file:
<configuration> <appSettings> <add key ="NCacheClient.AsynchronousEventNotification" value="true"/> <add key ="NCacheClient.NumberofEventProccesingThreads" value="2"/> </appSettings> </configuration>
AsynchronousEventNotification: Specifies whether events will be fired asynchronously or synchronously on the client side. The default value is "true" which indicates that events will be fired asynchronously. The value "false" means that events will be fired synchronously on the client side.
NumberofEventProcessingThreads: When the user has configured events to be fired synchronously, this flag is used to specify the number of threads that will process these events on the client side. A very large value can cause performance issues.