Create Full-Data Client Cache

A Full-Data Client Cache maintains complete datasets for configured reference data types at the client, providing local access to the data required by the application. The Client Cache configuration is maintained with the clustered cache, and connecting client applications use the configured Client Cache.

You can create a Full-Data Client Cache using the NCache Management Center or the appropriate PowerShell cmdlets, as described below. A Full-Data Client Cache can run as InProc or OutProc.

Note

An OutProc Client Cache requires NCache Client to be installed on the client node.

Important

The Full-Data Client Cache cannot be created and reference data types cannot be added while the clustered cache is running.

Using the NCache Management Center

To create a Full-Data Client Cache, follow the steps mentioned below.

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

  • In the left navigation bar, click on Clustered Caches. Against the Cache Name, click on View Details.

NCache Management Center showing the Clustered Caches list with the "View Details" option highlighted for a selected cache.

  • This opens the detailed configuration page for the cache.

  • In the Client Cache tab, click on the New button.

Client Cache tab in the cache details page with the "New" button selected to create a new Client Cache.

  • The New Client Cache page opens. The Client Cache name is automatically derived from the clustered cache name and cannot be modified. For example, the Client Cache for defaultCache is named defaultCache_cc.

  • Select Full-Data as the Client Cache type and configure the following settings:

    • Maximum Size: Specifies the maximum size of the Client Cache in MB. Allocate sufficient space to accommodate the data for the configured reference data types.

    • Isolation Level: Select InProc or OutProc. An InProc Client Cache runs within the application process, whereas an OutProc Client Cache runs in a separate host process.

    • Enable Eviction: Eviction is always enabled for a Full-Data Client Cache. The eviction policy, eviction percentage, and default priority are inherited from the clustered cache.

Full-Data Client Cache configuration screen with fields for maximum size and isolation level.

  • Click Next to configure reference data types.

  • On the Add Reference Data Types page, click Browse and select the assembly containing the data types you want to configure. You cannot create a Full-Data Client Cache without configuring at least one reference data type.

  • Select the required data types from the browsed assembly and click Add Selected Datatypes. The selected data types appear in the Select Datatypes section in the same order you add them.

Reference Data Types selection dialog for Full-Data Client Cache, showing available data types and ordering controls.

  • You can use Move Up and Move Down to change the order of the selected reference data types. This order determines the Eviction Priority for them, i.e., the data type added last is evicted first.

  • You can also remove the selected reference data types through the Remove Selected Datatypes button.

Important

Strict Local Reads and Strict Query Enforcement only apply to reference data types that are configured in the Full-Data Client Cache.

  • You can also configure the following Full-Data Client Cache behaviors:

    • Strict Local Reads: By default, all read operations check the Client Cache (L1) first, and if the data isn't found, they fallback to the clustered cache (L2). However, if you want to avoid this fallback and ensure reads are served strictly from the local cache, you can use the Strict Local Reads feature. With this enabled, any key not found in the Client Cache (L1) results in a cache miss, and no request is made to the clustered cache (L2). For this behavior, select the "Return a cache miss for any key not found in the client cache, with no fallback to the clustered cache" checkbox.

    • Strict Query Enforcement: Queries are executed on the Client Cache first, and will fallback to the clustered cache only if the data is partially loaded in the Client Cache for configured reference data types. However, if you want queries to not fallback to the clustered cache, enable the checkbox "Throw an exception when querying a partially loaded dataset in the client cache, with no fallback to the clustered cache." With this option enabled, the query will not fallback to the clustered cache and will instead fail, throwing the exception: "Unable to execute query on client cache as the type '{queryFQN}' is partially loaded.", thus allowing for Strict Query Enforcement.

Important

If neither checkbox is selected and the data is only partially loaded, the search will fallback to the clustered cache.

Full-Data Client Cache options screen showing Strict Query Enforcement and Strict Local Reads settings.

  • Click Finish to create the Full-Data Client Cache.
Note

Creating a Client Cache does not initialize it in application processes that are already connected without Client Cache. Restart those application processes to use the newly configured Client Cache.

Once created, the Client Cache tab displays the Full-Data Client Cache configuration. The Full-Data Cache Settings tab displays its reference data types and Full-Data-specific settings.

Using PowerShell

You can also configure a Full-Data Client Cache using the New-ClientCache PowerShell cmdlet.

  • The following command configures a Full-Data Client Cache for defaultCache on server 20.200.20.11 with a maximum size of 1024 MB. The Client Cache name is automatically derived from the clustered cache name.
New-ClientCache -CacheName defaultCache -Server 20.200.20.11 `
                -Type FullData -Size 1024

The following command configures a Full-Data Client Cache with Strict Query Enforcement and Strict Local Reads enabled. This command uses the FailQueryOnPartialDataset switch parameter to enforce Strict Query Enforcement and throws an exception if a query is executed on a partially loaded dataset, with no fallback to the clustered cache. The DisableL2FallbackOnMiss switch parameter enforces Strict Local Reads and returns a cache miss for any key not found in the Client Cache, without attempting to retrieve it from the clustered cache.

New-ClientCache -CacheName defaultCache -Server 20.200.20.11 `
                -Type FullData -Size 1024 `
                -FailQueryOnPartialDataset -DisableL2FallbackOnMiss

To add the required Reference Data Types for the Full-Data Client Cache, use the Add-ClientCacheRefDataType PowerShell cmdlet.

  • The following command adds the class ClassLibrary1.Customer as a reference data type for the Full-Data Client Cache configured for defaultCache.
Add-ClientCacheRefDataType -CacheName defaultCache -AssemblyPath C:\ClassLibrary1.dll `
                           -Datatype ClassLibrary1.Customer
  • The following command adds the classes ClassLibrary1.Customer and ClassLibrary1.Product as reference data types for the Full-Data Client Cache configured for defaultCache on server 20.200.20.11.
Add-ClientCacheRefDataType -CacheName defaultCache -AssemblyPath C:\ClassLibrary1.dll `
                           -Datatype ClassLibrary1.Customer'$'ClassLibrary1.Product `
                           -Server 20.200.20.11
  • The following command adds the same reference data types using a JSON file as the AssemblyPath.
Add-ClientCacheRefDataType -CacheName defaultCache -AssemblyPath C:\ClassLibrary1.json `
                           -Datatype ClassLibrary1.Customer'$'ClassLibrary1.Product `
                           -Server 20.200.20.11
  • This command adds the class ClassLibrary1.Customer as reference data type for the Full-Data Client Cache using security credentials.
Add-ClientCacheRefDataType -CacheName defaultCache -AssemblyPath C:\ClassLibrary1.dll `
                           -Datatype ClassLibrary1.Customer -Credentials(Get-Credential john_smith)
  • This command adds the classes ClassLibrary1.Customer and ClassLibrary1.Product as reference data types for the Full-Data Client Cache configured for defaultCache on server 20.200.20.11 using a client PEM certificate and password for mutual TLS (mTLS) authentication.
Add-ClientCacheRefDataType -CacheName defaultCache -AssemblyPath C:\ClassLibrary1.dll `
                           -Datatype ClassLibrary1.Customer'$'ClassLibrary1.Product `
                           -Server 20.200.20.11 -TlsCertPath "C:\certs\client.pem" `
                           -TlsCertPassword "clientKeyPassword"

See Also

Client Cache Architecture
Regular Client Cache
Caching Topologies