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, no NCache client service is required on the client machine. The application provides the cache name and server information required to establish the initial connection. After connecting, applicable client runtime settings are received from the cache server.

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 application provides the information required to locate and connect to the cache. After the connection is established, client behavior settings are provided by the cache server.

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 requires the cache name and server information to establish the initial connection. After connecting, the client receives its applicable configuration settings from the cache server.

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.
  • After the connection is established, the client retrieves applicable cache and client configuration from the cache server, including supported runtime settings such as client logging, connection behavior, and performance-counter settings.
  • 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 remote client management, client-side monitoring, and supported client-side services.

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
  • 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 supports remote management, monitoring, and client-side services 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:

  • 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, the NCache Service enables supported remote management and monitoring operations on that client machine.

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 uses configuration files for cache configuration, security, TLS, monitoring, and other installed features. Cache-specific client runtime settings are not maintained in a local client configuration file. Instead, these settings are maintained on the cache server and provided to clients after they connect.

Application connection configuration and NCache installation configuration are handled separately, as described below.

SDK-Based Application Configuration

In an SDK-only deployment, the application provides only the information required to establish the initial connection with the cache. This connection information is maintained in the application configuration. The application configuration typically includes:

  • Cache name
  • Cache server endpoints
  • Security credentials, if required

After the client connects to the cache, applicable client runtime settings are received from the cache server. These settings include client logging, connection behavior, performance counters, and other supported client configuration.

Therefore, SDK-only applications do not require the full NCache Client installation to maintain cache-specific client runtime configuration, because these settings are managed by the cache server.

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.

Relevant Configuration Files

The following configuration files can be relevant to NCache client operation and management:

  • 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 configuration, including TLS enablement, mutual TLS settings, certificate configuration, and protocol version.

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

  • otel.ncconf: Stores OpenTelemetry configuration for logs and metrics, including client OpenTelemetry enablement.

Log Files

NCache client logs help diagnose application connection issues, client-server communication problems, and client-side runtime errors. Client logging configuration is maintained on the cache server and is provided to clients after they connect.

In SDK-only deployments, client logs are generated with the application. When the NCache Client Installer is used, NCache component logs are available under the NCache log directory:

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

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

Enabling Client Logs

Client logging is maintained on the cache server and is provided to clients after they connect to the cache. Client logging is enabled by default and can be configured through the NCache Management Center or the Set-Logging PowerShell cmdlet.

For information about Error and Detailed logging, client logging behavior before the server-side configuration is received, and log locations, see Error Logging.

See Also

Client Management
Cache Topologies
Client Cache