Migrate StackExchange.Redis Applications to NCache

The NCache Redis wrapper for StackExchange.Redis allows existing Redis applications to connect to NCache with minimal code changes. Instead of connecting to a Redis server endpoint, the application connects to an NCache cache by name using the same ConnectionMultiplexer entry point. This page explains the basic migration and connection steps required to use the NCache Redis wrapper in an existing StackExchange.Redis application.

Note

This feature is also available in NCache OpenSource, except for data structure operations (Hash, List, Set) and Object-to-Byte-Array serialization.

Step 1: Install the NCache Redis Wrapper NuGet Package

Install the NCache Redis Wrapper NuGet package in your application. To install the package from Visual Studio, go to Tools -> NuGet Package Manager -> Package Manager Console, and run the following command:

For Enterprise:

Install-Package NCache.StackExchange.Redis.Wrapper

For OpenSource:

Install-Package NCache.OSS.StackExchange.Redis.Wrapper

Step 2: Update the Namespace

Replace the StackExchange.Redis namespace with the NCache Redis wrapper namespace in your application.

For Enterprise:

using NCache.StackExchange.Redis;

For OpenSource:

using NCache.OSS.StackExchange.Redis;

Step 3: Specify the NCache Cache Name

Ensure that the NCache cache is created and running. The wrapper connects to NCache by cache name, so replace the Redis server endpoint used by your application with the name of the NCache cache. If your application reads connection information from configuration, specify the NCache cache name in the application configuration, as shown below:

<configuration>
    <appSettings>
        <add key="CacheId" value="demoCache"/>
    </appSettings>
</configuration>

In this example, demoCache is the name of the NCache cache that the application will connect to.

Step 4: Connect to NCache

Note

Ensure that the NCache cache is running before connecting to it.

In a Redis application that uses StackExchange.Redis, the application typically connects to a Redis server endpoint. When using the NCache Redis wrapper, pass the NCache cache name to ConnectionMultiplexer.Connect instead of the Redis server endpoint.

// Connect to NCache using the cache name
ConnectionMultiplexer ncache = ConnectionMultiplexer.Connect("demoCache");

// Get the database instance for supported cache data operations
IDatabase db = ncache.GetDatabase();

The ConnectionMultiplexer manages the underlying NCache connection. The GetDatabase() method returns an IDatabase instance that the application can use for supported cache data operations. If logging is required, you can optionally pass a Microsoft ILoggerFactory instance while initializing the connection. This uses the Microsoft.Extensions.Logging namespace. For console logging, make sure the Microsoft.Extensions.Logging.Console package is available in your project.

using Microsoft.Extensions.Logging;

// Create a Microsoft logger factory with console logging enabled
using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
});

// Connect to NCache using the cache name and pass the logger factory
ConnectionMultiplexer ncache = ConnectionMultiplexer.Connect("demoCache", loggerFactory: loggerFactory);

After completing these steps, your StackExchange.Redis application can connect to NCache through the NCache Redis wrapper.

Unsupported Redis Features and Behavior Differences

The NCache Redis Wrapper is designed to preserve the StackExchange.Redis programming model for supported operations. However, some Redis-specific features and behaviors do not have direct NCache equivalents. Review these differences before migration, especially if your application depends on Redis server-side behavior.

Area	NCache Redis Wrapper Behavior
Sorted set performance	Sorted set range and rank queries may fetch the full score dictionary and sort it in memory. Not suitable for very large sorted sets under high read concurrency.
Hash field expiration	Redis per-field expiration commands such as HEXPIRE, HGETEX, HSETEX, and HPERSIST are not supported and throw NotSupportedException.
RESP3 / CommandFlags	CommandFlags parameters are accepted for StackExchange.Redis API compatibility but are ignored by the wrapper. NCache manages routing and execution internally.
Scripting (Lua)	ScriptEvaluate and LuaScript are not supported because NCache does not provide a Lua scripting equivalent.
Sharded Pub/Sub	SSUBSCRIBE for sharded channels in Redis Cluster is not applicable to the NCache topology.
Vector Set	Redis vector set commands such as VADD and VSIM are not implemented.
SCAN / KeySearch	IServer.Keys / SCAN performs a full keyspace enumeration. Use this carefully and avoid using it against high-volume production caches.

See Also

.NET: Alachisoft.NCache.Client namespace.