Skip to content

Migration Guide StackExchange.Redis

Jump to bottom
Alex Rehnby-Martin edited this page Sep 17, 2025 · 1 revision

Migration Guide: StackExchange.Redis to Valkey Glide

DRAFT

Overview

The Valkey.Glide C# library is designed to be generally compatible with the popular StackExchange.Redis library v2.8.58, making migration straightforward for developers. This guide will help you quickly transition your existing Redis applications to use Valkey with minimal code changes.

Valkey.Glide maintains similar APIs and patterns to StackExchange.Redis, ensuring that your existing Redis knowledge and code patterns remain largely applicable. The primary differences lie in the namespace and package references rather than fundamental API changes. There will be a small set of differences in the final GA release which will be documented.

Important

Valkey.Glide C# wrapper is in a preview state and still has many features that remain to be implemented before GA. The guide currently references our anticipated state for the Preview release and will be updated again after the Preview release is officially out, and again after the GA release later this year.

Migration Steps

Migrating from StackExchange.Redis to Valkey.Glide requires just two main steps:

Step 1: Update Package References

Remove the StackExchange.Redis NuGet package and add the Valkey.Glide package to your project.

Using Package Manager Console:

# Remove StackExchange.Redis
Uninstall-Package StackExchange.Redis

# Add Valkey.Glide
Install-Package Valkey.Glide

Using .NET CLI:

# Remove StackExchange.Redis
dotnet remove package StackExchange.Redis

# Add Valkey.Glide
dotnet add package Valkey.Glide

Using PackageReference in .csproj:

<!-- Remove this line -->
<!-- <PackageReference Include="StackExchange.Redis" Version="2.x.x" /> -->

<!-- Add this line -->
<PackageReference Include="Valkey.Glide" Version="1.x.x" />

Step 2: Update Namespace References

Update all StackExchange.Redis namespace references to Valkey.Glide in your code.

Option A: Update Individual Files

Replace namespace imports in each file:

// Before
using StackExchange.Redis;

// After
using Valkey.Glide;

Option B: Global Using Directive (Recommended)

For simplicity, add a global using directive to your .csproj file so you only need to make the change in one location:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Using Include="Valkey.Glide" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Valkey.Glide" Version="1.x.x" />
  </ItemGroup>

</Project>

With this approach, you won't need to add using Valkey.Glide; statements to individual files.

Code Compatibility

Most of your existing StackExchange.Redis code should work with minimal or no changes after updating the namespace. Common patterns that remain compatible include:

Connection Management

// Connection string and basic setup remain the same
var connection = ConnectionMultiplexer.Connect("localhost:6379");
var database = connection.GetDatabase();

Basic Operations

// String operations
await database.StringSetAsync("key", "value");
var value = await database.StringGetAsync("key");

// Hash operations
await database.HashSetAsync("hash:key", "field", "value");
var hashValue = await database.HashGetAsync("hash:key", "field");

// List operations
await database.ListLeftPushAsync("list:key", "item");
var item = await database.ListRightPopAsync("list:key");

Advanced Features

// Transactions
var transaction = database.CreateTransaction();
transaction.StringSetAsync("key1", "value1");
transaction.StringSetAsync("key2", "value2");
await transaction.ExecuteAsync();

// Batch operations
var batch = database.CreateBatch();
var task1 = batch.StringSetAsync("key1", "value1");
var task2 = batch.StringSetAsync("key2", "value2");
batch.Execute();
await Task.WhenAll(task1, task2);

Configuration Considerations

Connection Strings

Valkey.Glide uses the same connection string format as StackExchange.Redis, so your existing configuration should work without changes:

var connectionString = "localhost:6379,abortConnect=false";
var connection = ConnectionMultiplexer.Connect(connectionString);

Configuration Options

Most configuration options from StackExchange.Redis are supported in Valkey.Glide:

var config = new ConfigurationOptions
{
    EndPoints = { "localhost:6379" },
    AbortOnConnectFail = false,
    ConnectTimeout = 5000,
    SyncTimeout = 5000
};
var connection = ConnectionMultiplexer.Connect(config);

Testing Your Migration

After completing the migration steps:

  1. Build your project to ensure there are no compilation errors
  2. Run your existing unit tests to verify functionality
  3. Test key application flows to ensure Redis operations work as expected
  4. Monitor performance to confirm there are no unexpected changes

Compatible Commands

The following Commands are currently supported and are fully compatible[^1]
ExecuteAsync CustomCommand Exec
KeyMoveAsync KeyCopyAsync KeyDeleteAsync
KeyUnlinkAsync KeyExistsAsync KeyExpireAsync
KeyTimeToLiveAsync KeyTypeAsync KeyRenameAsync
KeyRenameNXAsync KeyPersistAsync KeyDumpAsync
KeyRestoreAsync KeyRestoreDateTimeAsync KeyTouchAsync
HashGetAsync HashGetAllAsync HashSetAsync
HashDeleteAsync HashExistsAsync HashLengthAsync
HashStringLengthAsync HashValuesAsync HashRandomFieldAsync
HashRandomFieldsAsync HashRandomFieldsWithValuesAsync ListLeftPopAsync
ListLeftPushAsync ListRightPushAsync ListRightPopAsync
ListLengthAsync ListRemoveAsync ListTrimAsync
ListRangeAsync Info EchoAsync
PingAsync SetAddAsync SetRemoveAsync
SetMembersAsync SetLengthAsync SetIntersectionLengthAsync
SetPopAsync SetUnionAsync SetIntersectAsync
SetDifferenceAsync SetUnionStoreAsync SetIntersectStoreAsync
SetDifferenceStoreAsync SortedSetAddAsync SortedSetRemoveAsync
SortedSetLengthAsync SortedSetCardAsync SortedSetCountAsync
SortedSetRangeByRankAsync SortedSetRangeByRankWithScoresAsync SortedSetRangeByScoreAsync
SortedSetRangeByScoreWithScoresAsync SortedSetRangeByValueAsync StringSetAsync
StringGetAsync StringGetRangeAsync StringSetRangeAsync
StringLengthAsync StringAppendAsync StringDecrementAsync
StringIncrementAsync

Troubleshooting

Common Issues

  1. Namespace not found: Ensure you've properly updated package references and namespace imports
  2. Method not available: Some advanced features might have slight API differences - consult the Valkey.Glide documentation
  3. Connection issues: Verify your Valkey server is running and accessible

Getting Help

Conclusion

Migrating from StackExchange.Redis to Valkey.Glide is designed to be a straightforward process. The compatibility-focused design means you can leverage your existing Redis knowledge while benefiting from Valkey's improvements and features.

The two-step migration process (package update + namespace change) should handle the majority of use cases with minimal code changes required.

TODO:

  • Describe which parameters are removed from configuration options and from connection string. List which new parameters added.

  • SER automatically pipelines all async API, while GLIDE - don’t.

  • Exception handling - exception mapping SER <-> GLIDE. TBD - do we need to rename our exceptions and/or change namespace?

[^1]: CommandFlags values other than CommandFlags.None are not currently supported and will throw an error if used.

Clone this wiki locally