Upgrade Client

When NCache servers are upgraded, client applications can be updated immediately or continue using an older NCache client version, depending on the application lifecycle and version compatibility.

Important

Verify that the client and server version combination is supported before selecting an upgrade option. For assistance with version-specific compatibility, contact Alachisoft Support.

Prerequisites

Before changing the NCache client version:

  • Identify the NCache NuGet packages and provider modules used by the application.
  • Review configuration files for assembly versions or binding redirects.
  • Confirm that the application can connect to the upgraded NCache servers.
  • Back up the application configuration and deployment package.
  • Test the selected upgrade approach in a staging or test environment.
Note

The client package or provider assembly version may differ from the installed NCache product version. Use the version specified for the relevant package or integration.

Option 1: Recompile the Client with the New NuGet Package

This is the recommended approach when the application can be rebuilt and redeployed.

Update the NCache NuGet package references to the version intended for the upgraded NCache environment, restore the application dependencies, and recompile the application. In most cases, the existing caching code can continue to be used without modification.

Use this option when:

  • The application is under active development.
  • A normal build and deployment cycle is available.
  • You want to use the latest client-side features, fixes, and performance improvements.
  • You want the client and server versions to remain aligned.

To upgrade the client:

  1. Update the NCache NuGet packages referenced by the application.
  2. Restore the application dependencies.
  3. Rebuild the application.
  4. Update any configuration entries that explicitly reference an older assembly version.
  5. Deploy the rebuilt application.
  6. Test cache connectivity and application operations.

Applications Using NCache APIs

Applications using NCache object caching or other direct client APIs should be rebuilt with the updated NCache NuGet packages. Unless the newer version introduces an API change that affects the application, no source-code modification is generally required.

Applications Using Provider Modules

If the application uses an NCache provider, such as Session State or another framework integration, update the corresponding provider package and review its configuration. Where the configuration contains a version-specific assembly reference, replace the old version with the assembly version supplied by the updated provider package. For example:

<assemblies>
  <add assembly="Alachisoft.NCache.SessionStoreProvider, Version=x.x.x.x, Culture=neutral, PublicKeyToken=CFF5926ED6A53769"/>
</assemblies>

Replace x.x.x.x with the assembly version used by the installed provider package.

Note

The assembly version is not necessarily identical to the NCache product or service-pack version.

Option 2: Use the Client Forward Compatibility Adapter

Use the Client Forward Compatibility Adapter to connect an application built with an older NCache client to newer NCache servers without modifying or recompiling the application.

Important

The Client Forward Compatibility Adapter is supported only on Windows.

This approach is suitable when:

  • NCache servers must be upgraded before client applications.
  • Server and application upgrades cannot occur in the same maintenance window.
  • Applications must continue using their existing client assemblies temporarily.
  • Application teams need additional time to migrate to the newer NCache client libraries.

The adapter assemblies replace the legacy NCache binaries in the application's bin or installation directory while preserving the existing assembly identity.

Important

Use the adapter as a temporary migration path. Applications should eventually be rebuilt with the newer NCache client libraries.

Note

For supported upgrade paths and deployment steps, refer to the Client Forward Compatibility Adapter guide.

Option 3: Keep the Existing Client Without Upgrading

An existing NCache client can remain unchanged when it is compatible with the upgraded NCache servers.

With this option:

  • The application is not recompiled.
  • The NCache NuGet package is not updated.
  • Existing configuration and assemblies remain unchanged.
  • The application continues connecting to the upgraded cache cluster through its current client version.

This option is useful for phased deployments where servers are upgraded first and client applications are updated later.

Use it when:

  • The existing client version is supported with the upgraded server version.
  • The application cannot currently be rebuilt or redeployed.
  • The application does not require newer client-side functionality.
  • The older client will be upgraded during a later deployment phase.
Important

Retaining an older client should generally be treated as a transitional approach. The application will not receive client-side features, fixes, security improvements, or performance enhancements introduced in newer packages.

Older clients may also behave differently from newer clients when using recently introduced server capabilities. Test all required cache operations before using this approach in production.

Upgrade an Installed Remote Client

If NCache Remote Client is installed on the application machine, upgrading the NuGet package does not upgrade the installed NCache software. Where an installed Remote Client must also be upgraded:

  1. Stop applications and processes using NCache.
  2. Deactivate the existing license when required.
  3. Uninstall the older Remote Client installation.
  4. Install the required NCache Remote Client version.
  5. Activate the new installation when required.
  6. Restart and test the client application.
Important

Stop all applications using NCache before uninstalling an installed Remote Client. The uninstallation can fail if NCache assemblies or processes are still in use.

Test Client Connectivity

After applying the selected upgrade option, verify:

  • The application can connect to the upgraded cache cluster.
  • Cache read, write, update, and removal operations succeed.
  • Serialized application objects can be exchanged correctly.
  • Provider-based integrations operate as expected.
  • Client failover works when a cache server becomes unavailable.
  • Application logs do not contain assembly-loading, serialization, or protocol errors.

You can also generate test activity by using Test Stress and monitor the cache through the NCache Management Center.

In This Section

Forward Compatible Client
Learn how to use the NCache Client Forward Compatibility Adapter to connect NCache legacy client applications to newer NCache servers without code changes.