NCache Client

NCache Client represents the application-side components that connect applications to NCache servers. A client may be an application using the NCache SDK, or a machine where the full NCache Client installation is performed for remote client management, client-side monitoring, and OutProc client cache support.

The NCache client architecture includes client SDKs, optional client-side services, configuration files, log files, and client-server communication mechanisms. These components work together to help applications discover cache servers, perform cache operations, handle topology changes, and optionally use a client cache closer to the application.

Client SDK

The NCache Client SDK provides application APIs that allow applications to connect to NCache and perform cache operations such as add, insert, get, remove, bulk operations, queries, events, locking, and other supported features.

NCache provides SDK support for the following platforms:

The client application uses the relevant SDK to communicate with NCache servers. In an SDK-only deployment, the application does not require any NCache client service to be running on the client machine. The application loads the NCache client libraries and connects to the configured cache servers by using either client-side configuration files or connection options provided in application code.

SDK-Based Client Connection

In an SDK-based deployment, the client application connects to the cache by using:

  • Cache name
  • Server information
  • Client connection settings
  • Security settings, if enabled
  • TLS settings, if secure communication is enabled

The initial connection information is usually read from client.ncconf, but it can also be provided programmatically through client connection options. When both configuration file settings and programmatic connection options are used, programmatic options take priority.

Client Communication

NCache clients communicate with cache servers over persistent TCP connections. The client-server communication model is designed to support high-throughput cache operations, parallel requests, topology-aware routing, and automatic recovery from temporary network interruptions.

Communication Methods

  • Google Protobuf as a Data Exchange Format: NCache clients use Google Protocol Buffers over TCP for client-server communication. This provides an efficient binary format and helps support compatibility between older client versions and newer cache server versions.

  • Request-response Based Parallel Request Execution: NCache uses a RequestId-based request-response protocol. Each client request is assigned a unique RequestId, allowing multiple requests to be sent over the same TCP connection without waiting for earlier responses. This enables parallel request execution from client applications.

  • Cache Topology Awareness: NCache clients are aware of the cache topology. For Partitioned and Partition-Replica topologies, the client retrieves distribution maps and connects directly to the server nodes that own the required data partitions. For Replicated topology, the client can connect to a suitable server because each server contains the same data.

  • Connection Failure Handling: NCache clients maintain persistent connections with cache servers. If a connection breaks due to a network glitch, the client attempts to re-establish connectivity in the background when the server becomes reachable again.

  • Data Serialization: Application data is serialized before it is sent to the cache server. NCache supports JSON and Binary serialization, and the client uses the serialization format configured for the cache.

  • Data Encryption: If encryption is configured, the client encrypts application data after serialization before sending it to the cache server.

  • Data Compression: If compression is configured, the client compresses data before sending it to the cache. This can help reduce network usage and cache storage size for large objects.

Connecting with the Cache

The cache client needs server information to connect with the cache. This information can be provided through client.ncconf or programmatically through connection options. The client uses this information to locate the cache servers and initialize a connection with the target cache.

Client connection usually follows this flow:

  • The client establishes a TCP connection with NCache Service over the configured client-server port.
  • The client requests the list of configured cache servers so it can discover the available cache nodes.
  • The client sends an initialization request that includes the cache name and security credentials if cache security is enabled.
  • If the cache is running in a separate process, the service directs the client to the correct cache process or cache port.
  • If the client is connecting to a Replicated cache and client load balancing is enabled, the client connects to a suitable server based on client load.
  • If the client is connecting to a Partitioned or Partition-Replica cache, the client retrieves distribution maps and establishes connections with the required cache servers.
  • The client also retrieves cache configuration details such as serialization format, compression settings, encryption settings, query indexes, and registered types where applicable.
Note

NCache automatically configures the firewall to open the required ports on Windows. On Linux, you need to open the required NCache ports manually according to your environment.

Client Installer

The NCache Client Installer installs the client-side components required for client management, OutProc client cache, client-side monitoring, and local configuration management.

A full client installation is useful when the client machine needs to be managed from the NCache Management Center or PowerShell tools, or when the application requires an OutProc client cache.

The Client Installer is commonly used for:

  • Remote client management
  • OutProc client cache
  • Client-side monitoring and counters
  • Local client configuration files
  • Client-side service and process support
Note

If an application only needs to use the NCache SDK and does not require remote management or OutProc client cache, an SDK-only deployment may be sufficient.

Processes

When NCache Client is installed on a machine, it may run client-side services and processes depending on the installed components and enabled features. These processes support client management, client cache hosting, and background runtime operations.

The main client-side processes are:

Alachisoft.NCache.Service

The NCache Service is the main client-side management service when the NCache Client Installer is used. On a client machine, it is responsible for managing client-side configuration, enabling remote client management, and supporting client cache operations where applicable.

On a cache server, the NCache Service manages server-side caches and accepts initial client connections. On a client machine, its role is narrower and focused on client-side management.

The NCache Service on a client machine is used for:

  • Registering and managing client configuration
  • Allowing remote client operations from NCache Management Center or PowerShell
  • Managing OutProc client cache lifecycle, where applicable
  • Supporting client-side monitoring and diagnostics

If the client machine is added as a client node to a cache, management tools can use the NCache Service on the client machine to update client-side configuration.

Note

SDK-only applications do not normally require the NCache Service on the client machine. The service is required when the client machine needs full NCache Client installation features such as remote management or OutProc client cache.

Alachisoft.NCache.CacheHost

The CacheHost process is used to host a cache instance outside the application process. On a client machine, this is mainly relevant for an OutProc client cache.

A client cache can run either in the application process or outside the application process, depending on the selected client cache mode. When an OutProc client cache is used, the cache runs in a separate process instead of inside the application. This provides process isolation between the application and the client cache.

The CacheHost process on a client machine is responsible for:

  • Hosting the OutProc client cache
  • Maintaining cached data close to the application
  • Communicating with the remote clustered cache when required
  • Reducing repeated network trips to the cache cluster for frequently used data

Running an OutProc client cache in a separate process is useful when multiple applications on the same client machine need to share the same client cache, or when cache memory and lifecycle should be isolated from the application process.

Alachisoft.NCache.ExecutionService

The NCache Execution Service is mainly a server-side component used for background execution tasks such as Cache Loader and Refresher. These tasks load or refresh data from a data source into server-side caches.

On a typical client machine, the Execution Service is not part of the normal client application runtime. It is not required for basic SDK-based cache operations or for normal client-server communication.

If the Execution Service is installed with a full NCache setup, it should be understood as a background execution component used by NCache features that require separate task execution. For normal NCache client usage, the key client-side processes are the NCache Service and, when OutProc client cache is used, the CacheHost process.

Note

If a client-side issue is related to normal application cache operations, first check the client logs and application logs. Execution Service logs are usually more relevant to server-side loader and refresher diagnostics.

Configuration Files

NCache client-side configuration files are used by client applications and client-side components to discover cache servers, apply connection settings, configure security, and enable secure communication.

The location of client-side configuration files depends on whether the application uses an SDK-only deployment or a full NCache Client installation.

SDK-Based Configuration Location

In an SDK-only deployment, configuration files should be kept with the application or in the location expected by the SDK package being used. This allows the application to load the required NCache client configuration at runtime without requiring the full NCache Client installation.

This approach is suitable when:

  • The application is deployed with NCache SDK libraries.
  • The client machine does not need remote management.
  • The application provides server information through configuration files or connection options.
  • OutProc client cache is not required.

Client Installer Configuration Location

When the NCache Client Installer is used, configuration files are stored in the NCache installation configuration directory:

  • Windows: Available at %NCHOME%\config.
  • Linux: Available at /opt/ncache/config.

These files are used by NCache client services, management tools, and client applications running on the machine.

Client-Side Configuration Files

The following configuration files are commonly relevant on a client machine:

  • client.ncconf: Contains client-side cache connection information. It is used by the NCache client API to locate cache servers and apply connection settings such as retries, timeouts, ports, and server list.

  • security.ncconf: Stores security-related client information used when cache security is enabled. It allows client applications to connect using the required security credentials and settings.

  • tls.ncconf: Stores TLS settings used for secure client-server communication. This file is required when TLS is enabled between client applications and cache servers.

  • monitoring.ncconf: Stores monitoring-related configuration used by NCache monitoring components.

Log Files

NCache client-side log files help diagnose application connection issues, client-server communication problems, client cache behavior, and client-side runtime errors.

The location of client-side logs depends on whether the application is using SDK-only deployment or a full NCache Client installation.

SDK-Based Log Location

In SDK-only deployments, client logs are usually generated in the application-specific log location or in the path configured through the client SDK or application settings.

This approach is useful when the NCache client libraries are deployed directly with the application and no full NCache Client installation exists on the machine.

Client Installer Log Location

When the NCache Client Installer is used, log files are generated under the NCache log directory:

  • Windows: Available at %NCHOME%\log-files.
  • Linux: Available at /opt/ncache/log-files.

The exact log file or folder depends on the client-side component that generates the log.

Enabling Client Logs

Client-side logging can be enabled through client.ncconf by setting enable-client-logs to True.

<cache id="demoCache"
       enable-client-logs="True"
       log-level="error">
  <server name="20.200.20.40"/>
</cache>

See Also

Client Management
Client Config (client.ncconf)
Cache Topologies
Client Cache