Client Forward Compatibility Adapter
The NCache Client Forward Compatibility Adapter enables applications built with older NCache client to seamlessly connect to and communicate with newer NCache servers. This adapter bridges the version gap without requiring code modifications, application recompilation, or major structural overhauls.
Important
This compatibility adapter is supported only on Windows.
Why Use the Compatibility Path?
When upgrading to a newer version of NCache, you have two options:
- Upgrade applications immediately by recompiling and redeploying every application against the new client libraries.
- Take the compatibility path by upgrading the NCache servers first and migrating applications later with the compatibility adapter.
The compatibility path is intended for environments where server and application upgrades cannot be completed during the same maintenance window. It allows infrastructure teams to upgrade NCache servers immediately to benefit from the latest fixes, performance improvements, security updates, and support, while application teams can migrate and validate their applications on their own schedule.
By introducing a compatibility layer, server and application upgrades become independent. Existing applications continue to work with the upgraded servers until they are ready to move to the newer client libraries.
With the compatibility path, you can:
- Upgrade NCache servers without waiting for all applications to be recompiled and redeployed.
- Migrate applications to the newer client libraries incrementally instead of requiring a single coordinated deployment.
- Reduce coordination between infrastructure and application teams during upgrades.
- Deploy the compatibility adapter without modifying application code or updating project references. Simply place the adapter assemblies in the application's bin or installation directory.
- Preserve the original client assembly identity, preventing runtime assembly binding and version mismatch issues.
- Maintain application behavior that closely matches the legacy client while communicating with newer NCache servers.
Note
The compatibility adapter supports all client-side features.
Supported Upgrade Paths
The table below outlines the supported client-to-server forward compatibility combinations:
| Legacy Client Version (Source) | Upgraded Server Version (Target) |
|---|---|
| NCache 4.9 SP1 | NCache 5.3 SP7 |
Steps to Apply the Compatibility Patch
To manually upgrade an existing application to use the Client Forward Compatibility Adapter, follow the steps below:
Step 1 - Halt the Client Application: Stop the application process, IIS Application Pool, or Windows Service that actively references the NCache client libraries. This releases any active operating system file locks on the assemblies.
Step 2 - Verify Server Installation: Make sure your backend cache servers are successfully upgraded to the latest NCache version and running before you configure the client application.
Step 3 - Install Client Machine Dependencies: Install the newer NCache Client on the computer running the application. This is required if your application uses a Client Cache (local L1 cache) or server-managed client tools.
Step 4 - Extract the New Files: Extract the new adapter files to a temporary folder.
Step 5 - Create a Rollback Backup: Navigate to your application's active directory (such as the bin folder) containing the original legacy NCache client binaries. Copy those original legacy DLLs out of the folder and save them in a secure backup folder to ensure an immediate recovery path if needed.
Step 6 - Deploy and Overwrite: Copy the new adapter binaries and paste them directly into the application's bin folder to replace the old ones. (Note: These files only replace items in this specific folder; they do not change any system-wide settings).
Step 7 - Verify Permissions and Restart: Check that the new files have proper Read & Execute permissions, then restart your application, NCache Server, and NCache service.
Important
The compatibility path is intended for migration, not permanent deployment. It allows the NCache server to be upgraded independently while applications are updated over time.
See Also
Upgrade Servers and Clients
Live Upgrade Servers
OS Upgrades and Patches
