Client Configuration

NCache uses a thin-client configuration model in which client applications do not require a local NCache configuration file. Instead, the application provides only the information required to establish a connection with the cache. You can copy this information from the NCache Management Center or a PowerShell console as demonstrated below.

Using the NCache Management Center

You can view the application-side connection configuration for a cache through the NCache Management Center.

• Launch the NCache Management Center by browsing to http://localhost:9801 or <server-ip>:9801.

• In the left navigation bar, click on Local Caches or Clustered Caches based on the cache you want to configure. This opens a new page. It shows any existing local or clustered caches and additional details like Server and Server Platform.

  
  

• In the Server Nodes section, navigate to the Client Configuration tab. Choose the type of configuration file your application uses.

  

• Add the provided configuration to the root object of the appsettings.json file in your application's folder. Alternatively, add the following inside <configuration> of the app.config/web.config of your application.

  

Essentially, the Client Configuration tab provides the minimum configuration that a client application requires to connect to the selected cache. This includes the cache name, server endpoint information, port, and applicable security settings.

After the application establishes its initial connection, NCache retrieves the remaining client behavior settings from the cache server. These settings are maintained centrally with the cache configuration rather than on individual client machines. When these settings are changed on the server, client applications obtain the applicable configuration from the server.

Note

For configuration syntax, supported settings, and defaults, see Client Application Configuration Reference.

Note

Learn how to connect to cache using the NCache API in the Developer's Guide.

Configuration Examples

The following examples show how to configure common application connection scenarios. Add the JSON section to the root object of appsettings.json, or place the XML section inside <configuration> in app.config/web.config. For XML, register the ncache section as shown in the Client Application Configuration Syntax. For the purpose, supported values, and defaults of each setting, see Understanding the Client Application Configuration Tags.

Connect Through a Load Balancer

Set endpointType to load-balancer and provide the address and exposed port of your load balancer. The following JSON and XML entries describe the same connection.

• appsettings.json
• app.config / web.config

{
  "ncache": {
    "defaultCache": {
      "endpointType": "load-balancer",
      "server": "20.200.20.13",
      "port": 9800
    }
  }
}

Use LDAP Authentication and a Client Certificate

The following entries configure a DNS endpoint, LDAP credentials, and a client certificate for a deployment that requires mutual TLS. Replace the sample identity, passwords, and certificate path with values for your application. For XML, retain the section registration shown in the configuration syntax.

• appsettings.json
• app.config / web.config

{
  "ncache": {
    "defaultCache": {
      "server": "ncache.corp.local",
      "security": "ldap",
      "userId": "john_smith",
      "password": "<user-password>",
      "tlsCertPath": "C:\\certs\\client.pem",
      "tlsCertPassword": "<certificate-password>"
    }
  }
}

Use the Application's gMSA Identity

Run the application under the authorized gMSA identity and select gmsa-ldap. Omit user credentials because authentication uses the process identity.

• appsettings.json
• app.config / web.config

{
  "ncache": {
    "defaultCache": {
      "server": "20.200.20.11,20.200.20.12",
      "security": "gmsa-ldap"
    }
  }
}

Configure an In-Process Local Cache

The following entries configure a standalone local cache with 1024 MB of storage. No server endpoints or remote authentication settings are required.

• appsettings.json
• app.config / web.config

{
  "ncache": {
    "defaultCache": {
      "inproc": true,
      "size": 1024
    }
  }
}

Additional Application Settings

The dedicated <ncache> section contains the cache connection settings described in the Client Application Configuration Reference. The application-wide settings PreferredServerReconnectDelay and UseSyncMessageDeliveryMode continue to be read from <appSettings> in app.config/web.config. Keep this section alongside <ncache> inside <configuration>.

<appSettings>
  <add key="PreferredServerReconnectDelay" value="10" />
  <add key="UseSyncMessageDeliveryMode" value="true" />
</appSettings>

• PreferredServerReconnectDelay specifies the delay, in seconds, before the client attempts to rebalance to its preferred server. The default is 60 seconds. Configured values are limited to the range 10 to 300 seconds; a value of 3 therefore takes effect as 10 seconds.
• UseSyncMessageDeliveryMode selects synchronous message notification delivery when set to true. When omitted or set to false, message notifications use asynchronous delivery unless UseThreadPoolForMessageInvocation is enabled, which also selects the synchronous notification path.

Important

These settings are not supported as attributes on a cache entry under <ncache><caches> or as properties of a cache entry in the JSON ncache section. Adding them there causes an unknown-setting configuration error. Retain them in <appSettings> when using these options.

See Also

Connect to Cache
NCache Client
Client Application Configuration Reference
Client Management