Understanding NCache Configuration Architecture
In NCache Enterprise, a rich set of configuration and management tools makes the life easier whether it is the creation of a multi-server cache or management of clients. In NCache Professional/Open Source 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 in-process (Inproc mode) local cache to multi server distributed caches. Scalability of cache depends on topology of the cache. Similarly, hardware requirements from development to production varies. Due to 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 following components on the target machine.
- Cache Configuration file (config.ncconf)
- NCache Service (NCacheSvc)
- Client configuration file (Client.ncconf)
- PowerShell 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 cache for NCache Professional/OpenSource means either 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, 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 "Hot Apply" feature are only supported in Enterprise edition.
Note
Whenever you edit config.nnconf, make sure that it has valid Xml syntax. Otherwise cache service does not start. If that happens, go to the Application Log in Windows Event Log for detail about the error against the event source of 'NCache'.
Note
For clustered caches, cache configuration on all server nodes MUST be identical. So if you want to upgrade cache size from 1GB to 2GB, then this change should be reflected in cache configuration on all server nodes. If 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 configuration and management of caches. manages all the caches on that server and listens on the management port (default 8250) for PowerShell tools (and UI tools in Enterprise edition). Upon startup, NCache Service reads configuration of all configured caches from config.ncconf file. That is why, in order to apply the configuration changes, you must restart NCache Service. 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 Windows PowerShell, NCache Service starts a new cache host process on this server. Running every cache in its separate process provides 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. Get-Caches cmdlet shows 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 request for a specific cache on this server. Default listening port for 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 cache client and 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 NCache.InitializeCache("cache-name") 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.
Client configuration file contains the connection information on which cache is running. For each cache your client application needs to talks to, there must be a configuration entry in client.ncconf file.
NCache client reads the configuration file and searches for the cache name specified in NCache.InitializeCache("cache-name"). 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 server 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. Client application does not require restart to reflect changes in client configuration. 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.
CacheInitParams passed in InitializeCache() can also serve as an extension/replacement of client.ncconf file. You can pass a list of cache server IP-addresses through
CacheInitParams 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 application from testing to 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 NCache Professional SDK NuGet package in your application, client.ncconf file is automatically added to your project and copied to your application build directory (for 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 had 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 client configuration file please refer to the Cache Client Settings section.
PowerShell Tools
NCache Professional/Open Source editions install PowerShell tools (cmdlets). NCache installer installs a PowerShell module named ncacheps located at %NCHOME%\bin\tools\ncacheps. These PowerShell tools can talk to NCache Service running on local or remote cache servers.
To view the list of PowerShell cmdlets provided with NCache through the ncacheps module, type the following command in PowerShell console:
Get-Command -Module ncacheps
To get help related to individual cmdlets type following command in Windows PowerShell console:
Get-Help -Detailed [NCache-Cmdlet-Name]
Following command gets the detailed help for Start-Cache cmdlet.
Get-Help -Detailed Start-Cache