Understanding NCache Configuration Architecture
In NCache Enterprise, a rich set of configuration and management tools makes life easier when creating of a multi-server cache or management of clients. In NCache Open Source, however, configuration and management operations require manual editing of various configuration files. Therefore, understanding cache configuration and its process architecture is very important for a successful NCache usage.
NCache supports different cache deployment models starting from in-process (In-Proc 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
Note
At a time, your cache can only connect to 1 client, it can be local or remote.
NCache installs the 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 (Mirrored) caches. When you define a new cache, you must put its XML-based configuration in this file. Every cache specified in the configuration uses a unique name. These configuration changes are ineffective until you restart the NCache Service, so if you have added a new cache definition to config.ncconf, you must restart the NCache Service. Otherwise, the start-cache tool will throw an error about the absence of this new cache. Similarly, any configuration changes on a running cache are ineffective unless you restart the cache. Runtime cache configuration changes through the Hot Apply feature are only supported in Enterprise.
Note
Whenever you edit the config.ncconf file, ensure that it has valid XML syntax. Otherwise, the cache service will not start. If this happens, refer to the Application Log in the Windows Event Log for details about the resulting error against the event source NCache.
Note
For clustered caches, the configuration on all server nodes MUST be identical, so if you want to upgrade the cache size from 1GB to 2GB, reflect this change in all server node configurations. If the cache configuration is not identical, your cache may behave unpredictably.
NCache Service (NCacheSvc)
The NCache Service is a core component of the configuration and management of caches. It manages all the caches on that server and listens on the related management port (default 8250) for PowerShell tools (and UI tools in 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 the NCache Service. The NCache Service is also responsible for starting and stopping the 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 PowerShell, the NCache Service starts a new cache host process on this server. Running every cache in its separate process provides a high isolation level between different cache instances running on the same server. 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 starts, the NCache Service process must communicate with it for different operations. Therefore, the NCache Service assigns a unique management port for every cache started. This cache port mapping is in the CacheHostPorts.xml file at %NCHOME%\bin\service. This file is auto-generated and only managed by the NCache Service. You should not manually edit this file.
The 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. The NCache Service accepts client connections and forwards them to the corresponding cache process. After this point, all further communication occurs directly between the cache client and process, and it does not involve the NCache Service. However, the NCache Service must run continuously for all new client connections.
Client configuration file (Client.ncconf)
When your application calls GetCache and passes the cache name to it, your application gets a cache handle that connects to the cache using the client configuration (%NCHOME%\config\client.ncconf) file.
This 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 client.ncconf file. The 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.
Note
Client configuration should be updated whenever a new cache server is added or removed from a cluster. First, the cache cluster notifies each client about server additions or exits. Second, if a client disconnects from a server and tries to re-establish a connection after you have modified the configuration file, it again refers to the configuration file.
The CacheConnectionOptions passed in GetCache() can also serve as an extension/replacement of 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 ill-advised 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 to access that caching tier. Instead, you can deploy the NCache Client libraries along with your application to this client machine and the client configuration file, and your application can connect to the caching tier.
For example, when you install NCache Open Source SDK NuGet package in your application, 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 with your application, and the second 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 deployed with the application. But, if it doesn't find that file or doesn't have a cache connection specified in that local client configuration file, the application looks for it in the main client.ncconf installed with NCache Remote Client.
Note
Remove the local client.ncconf and config.ncconf from your project if your application runs on a server where NCache resides.
For more details about the client configuration file, please refer to the Cache Client Settings section.
PowerShell Tools
NCache Open Source installs PowerShell tools (cmdlets). The NCache installer installs a PowerShell module named ncacheps located at %NCHOME%\bin\tools\ncacheps. These PowerShell tools can talk to the NCache Service 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 the PowerShell console:
Get-Command -Module ncacheps
To get help related to individual cmdlets, type the following command in PowerShell console:
Get-Help -Detailed [NCache-Cmdlet-Name]
The following command gets the detailed help for Start-Cache cmdlet.
Get-Help -Detailed Start-Cache