Client Application Configuration Reference

NCache client applications use the ncache section of appsettings.json or app.config/web.config to identify the cache and provide the connection information required to reach it. For a remote cache, this includes the server endpoints, port, and applicable authentication and TLS settings. After connecting, the client obtains the remaining client behavior settings from the cache server, as described in Client Configuration.

This reference explains the application configuration structure and each supported setting for the client configuration model. The JSON properties and XML attributes use the same setting names and values; their parent sections differ as shown below. For practical JSON and XML examples covering load balancers, LDAP and TLS, gMSA, and in-process local caches, see Client Configuration Examples.

Client Application Configuration Syntax

The following examples configure defaultCache with two server endpoints. Optional settings are shown with their default values. Omit credentials and certificate settings when they are not required by your deployment.

Add ncache to the root object of the application's appsettings.json. Each child object is named after the cache to which the application connects.

{
  "ncache": {
    "defaultCache": {
      "endpointType": "server",
      "server": "20.200.20.11,20.200.20.12",
      "port": 9800,
      "tlsCertPath": null,
      "tlsCertPassword": null,
      "security": "ldap",
      "userId": null,
      "password": null
    }
  }
}
Note

If the application already registers ncache through an NCache Session State or Output Cache provider, retain that registration and add <caches> alongside the existing provider settings. Do not register the same section twice.

Understanding the Client Application Configuration Tags

The following sections explain the JSON objects and their corresponding XML tags, followed by the settings available on each cache entry.

ncache / <ncache>

This is the parent section for the application's NCache configuration. In JSON, place cache objects directly under ncache. In XML, place the <caches> collection under <ncache>.

<caches>

This XML tag contains one <add> element for each cache used by the application. The cache-name-keyed JSON format shown above does not require a caches wrapper.

Cache Object / <add>

Each entry specifies one cache and its connection settings. Use the actual cache name, such as defaultCache, as the JSON object key or the XML name attribute. The name must match the cache requested by the application; defaultCache is an example name and does not select a default cache automatically.

<add name="defaultCache" server="20.200.20.11" port="9800" />

  • name / cacheName: Identifies the cache. XML requires a nonempty, unique name on every <add> element. In the recommended JSON format, the object key identifies the cache, so a separate name property is unnecessary. JSON also supports a single flat cache object with cacheName, or a caches array whose entries each contain cacheName. Cache-name matching is case-insensitive.

  • endpointType: Specifies whether the endpoints identify cache servers directly or a load balancer. Supported values are server and load-balancer; the default is server. Use server for IP addresses and DNS names of cache servers. Use load-balancer when server contains the load balancer address. DNS is resolved from the hostname and does not require a separate endpoint type. This setting describes the configured endpoints; it does not configure a load balancer or change the server-managed client load-balancing setting.

  • server: Specifies the cache server IP addresses or DNS names, or the load balancer address, used to establish the initial connection. Provide at least one endpoint for a remote cache unless the application supplies a server list programmatically. There is no configured endpoint by default. Separate multiple endpoints with commas, for example 20.200.20.11,20.200.20.12, and use ncache.corp.local for a DNS endpoint. An endpoint can specify its own port, for example 20.200.20.11:9800; otherwise it uses the effective cache-level port. A vertical bar or a space is not a separator for alternative endpoints.

  • port: Specifies the client connection port used by endpoints that do not specify their own port. The default is 9800. An explicitly configured cache-level port must be a whole number from 1 to 65535. It must match the port exposed by the server or load balancer. An explicit endpoint port takes precedence over the cache-level port for that endpoint.

  • tlsCertPath: Specifies the path to the client certificate and its private key for mutual TLS authentication. The default is unset. Use a PEM file for modern .NET clients; .NET Framework clients also support PFX certificates. The application account must be able to access the certificate and private key. Use a path on the client machine, and escape backslashes in JSON, for example C:\\certs\\client.pem. Configuring this path does not enable TLS on the server; configure TLS and certificate trust as described in the linked TLS setup instructions.

  • tlsCertPassword: Specifies the password used to decrypt the certificate's encrypted private key or password-protected PFX file referenced by tlsCertPath. The default is unset. Omit this setting when the certificate's private key does not require a password. This value is separate from the cache user's password.

  • security: Selects the client authentication mode. Supported values are ldap and gmsa-ldap; the default is ldap. With ldap, the client uses the supplied userId and password when authentication is required. With gmsa-ldap, the client uses the application's process identity and ignores userId and password. Configure the account, application identity, and server authorization as described in Configure Group Managed Service Account (gMSA). Selecting a mode does not enable server-side security or grant access to the cache.

  • userId: Specifies the authorized user's identity for LDAP authentication. The default is unset. Supply the identity accepted by the configured directory and NCache security settings. This setting is ignored when security is gmsa-ldap.

  • password: Specifies the LDAP user's password. The default is unset. Supply the user's actual password when LDAP authentication is required; this setting is ignored when security is gmsa-ldap. Do not use a certificate password in this field.

  • inproc: Specifies whether the entry describes a standalone in-process local cache hosted by the application. Supported values are true and false; the default is false. When true, omit all remote connection settings, including server, port, endpointType, certificate settings, security, and credentials. This setting describes a local cache, rather than an in-process Client Cache in front of a remote cache.

  • size: Specifies the storage size of an in-process local cache in megabytes. It accepts a positive whole number, for example 1024; the default is 1024 MB when omitted. Use this setting only with inproc set to true. A remote cache's storage size is configured on the server.

Note

Use the canonical camelCase names shown in this reference. Setting-name matching ignores case, hyphens, and underscores, but unknown settings and duplicate normalized settings on a cache entry cause configuration errors. Empty or null scalar values are treated as unset. For an in-process cache, remove remote connection properties entirely, even if their values are empty.

Note

Application-wide settings such as PreferredServerReconnectDelay and UseSyncMessageDeliveryMode remain in the XML <appSettings> section. They are not supported cache-entry settings in ncache. See Additional Application Settings for their usage and effective values.

Configuration File Selection and Precedence

NCache reads appsettings.json from the application's base directory, falling back to the current working directory if the base directory does not contain that file. Ensure the file is included in the deployed application.

If DOTNET_ENVIRONMENT is set, NCache also reads appsettings.{environment}.json from the same directory. If it is not set, NCache uses ASPNETCORE_ENVIRONMENT instead. Settings in the environment-specific entry override matching properties of the base entry. Keep the base appsettings.json file present so NCache can locate this directory.

For a requested cache, the merged JSON entry takes precedence over the XML entry. NCache consults the application's XML configuration only when no matching JSON entry exists; it does not fill missing JSON properties from XML. Explicitly supplied connection options take precedence over the corresponding application configuration settings. For programmatic configuration, see Connect to Cache.

Note

Connection retries, request timeouts, client logging, and Client Cache behavior are supplied by the cache server. Do not copy these server-managed settings into the cache entry in the application configuration. Refer to Cache Config (config.ncconf) for the server-side configuration reference.

See Also

Client Configuration
Cache Config (config.ncconf)
Test Client-Server Connectivity
Configure TLS Security