NCache Configuration Architecture

In NCache Enterprise, a rich set of configuration and management tools makes life easier whether it is the creation of a multi-server cache or management of clients. In NCache Professional/OpenSource, however, configuration and management operations require manual editing of various configuration files. Therefore, understanding cache configuration and process architecture is very important for a successful configuration of NCache.

NCache supports different cache deployment models starting from InProc local cache to multi-server distributed caches. The scalability of the cache depends on the topology of the cache. Similarly, hardware requirements from development to production vary. Due to the distributed nature, cache configuration management becomes more difficult.

Deployment Components

NCache Professional provides "Cache Server" and "Remote Client" installation options. For both of these, NCache installs the following components on the target machine.

  • Cache Configuration file (config.ncconf)
  • NCache Service (NCacheSvc)
  • Client configuration file (client.ncconf)
  • Command Line Tools

Each of these is explained below in more detail.

Cache Configuration File (config.ncconf)

This file (%NCHOME%\config\config.ncconf) contains the definition of all (local and clustered) caches. Clustered caches for NCache Professional/OpenSource either mean Replicated or Partitioned Cache, when you need to define a new cache, you need to put its .xml based configuration in this file. Every cache defined in the configuration is identified by its unique name. Configuration changes are not effective until you restart the NCache Service process. So if you have added a new cache definition to config.ncconf, you must restart NCache Service. Otherwise, the Start-Cache tool will throw an error about non existence of this new cache.

Similarly, configuration changes of a running cache are not effective unless you restart the cache instance. Runtime cache configuration changes through the "Hot Apply" feature are only supported in NCache Enterprise.

Note

Whenever you edit config.nnconf, make sure that it has valid XML syntax. Otherwise, the cache service does not start. If that happens, go to the Application Log in Windows Event Log for details about the error against the event source of 'NCache'.

Note

For clustered caches, the cache configuration on all server nodes MUST be identical. So if you want to upgrade the cache size from 1GB to 2GB, then this change should be reflected in the cache configuration on all server nodes. If the cache configuration is not identical, your cache may behave unpredictably.

To get more detail on this file, please refer to config.ncconf.

NCache Service (NCacheSvc)

NCache Service is the core component in the configuration and management of caches. It manages all the caches on that server and listens on the management port (default 8250) for Command Line tools (and UI tools in NCache Enterprise). Upon startup, the NCache Service reads the configuration of all configured caches from config.ncconf file. To apply the configuration changes, you must restart NCache Service. The NCache service is also responsible for starting and stopping of the actual cache process that hosts the cache on that server.

Every cache server has a cache manager process called Alachisoft.NCache.CacheHost.exe. Your cache management tools talk to this process for starting and stopping a cache on this server. When you start a cache using Command Line tools, NCache Service starts a new cache host process on this server. Running every cache in its separate process provides a high level of isolation between different cache instances running on the same server. Having a separate cache process also helps reduce Garbage Collector (GC) work. The Get-Caches cmdlet shows the process-id of the running cache process.

Once the cache is started NCache Service process also needs to talk to it for different operations. Therefore, NCache Service assigns a unique management port for every cache started. This cache port mapping is defined in CacheHostPorts.xml located in %NCHOME%\bin\service. This file is auto-generated and only managed by NCache Service. You should not manually edit this file.

NCache Service also listens for cache client connection requests for a specific cache on this server. The default listening port for the cache client is 9800. NCache Service accepts client connections and forwards them to the corresponding cache process. After this point, all further communication takes place directly between the cache client and the cache process and it does not involve NCache Service. However, for all new client connections, NCache Service needs to be running all the time.

Client configuration file (Client.ncconf)

When your application calls GetCache and passes the cache name to it, your application gets a cache handle that is connected to the cache. To achieve this, the client configuration (%NCHOME%\config\client.ncconf) plays its role.

The client configuration file contains the connection information on which the cache server is running. For each cache your client application needs to talk to, there must be a configuration entry in the client.ncconf file. NCache client reads the configuration file and searches for the cache name specified in GetCache. From this, the client finds out about all the cache servers where this cache is running and tries to connect to them one by one. If this is a replicated or partitioned cache spanning multiple servers, then IP-addresses of all cache servers should be present in the client.ncconf file.

Note

Client configuration should be updated whenever a new cache server is added or removed from a cache cluster. On one hand, each client is automatically notified by the cache cluster about any new server additions or a server leaving the cluster. Secondly, if you modify the client configuration file, the next time this client loses connection to any server and tries to reestablish it, it reads the client configuration file again.

CacheConnectionOptions passed in GetCache can also serve as an extension/replacement of the client.ncconf file. You can pass a list of cache server IP-addresses through CacheConnectionOptions and your client application tries to connect with them. However, this is not the recommended approach as it requires code changes whenever a new cache server is added/removed or moving an application from the testing to the production environment.

If you have a separate caching tier, then you do not have to install NCache Remote Client in order to access that caching tier. Instead, you can deploy NCache client libraries along with your application to this client machine and also the client configuration file and your application can connect to the caching tier.

For example, when you install the NCache Professional SDK NuGet package in your application, the client.ncconf file is automatically added to your project and copied to your application build directory (e.g., bin\debug|release).

Now, you have potentially two client.ncconf files. One is deployed with your application and the second one is installed with NCache Remote Client if you have installed it there. In this case, when your application runs, it always gives preference to the local client.ncconf that is deployed with the application. But, if it doesn't find that file or if your cache connection is not specified in that local client configuration file, then the application looks for it in the main client.ncconf that was installed with NCache Remote Client.

Note

It is recommended to remove local client.ncconf and config.ncconf from your project if your application runs on a server where NCache is already installed.

For more details about the client configuration file please refer to the Cache Client Settings section.

Command Line Tools

NCache Professional installs Command Line tools. NCache installer installs a Command Line module named ncacheps located at %NCHOME%\bin\tools\ncacheps. These Command Line tools can talk to NCache Service running on local or remote cache servers.

To view the list of Command Line provided with NCache through the ncacheps module, type the following command:

Get-Command -Module ncacheps

To get help related to individual tools type the following command:

Get-Help -Detailed [NCache-Cmdlet-Name]

The following command gets detailed help for the Start-Cache cmdlet.

Get-Help -Detailed Start-Cache

See Also

NCache Architecture
Configure Caches
Configure Clients
Management Operations