NewLife.Redis — High-Performance Redis Client Component

// Write / Read
rds.Set("k1", 123, expire: 600);
var v = rds.Get<Int32>("k1");

// Set only if key does not exist
var ok = rds.Add("k2", "init");

// Replace and return old value
var old = rds.Replace("k2", "new");

// Counters
rds.Increment("counter", 1);
rds.Decrement("counter", 2);

// Expiry management
rds.SetExpire("k1", TimeSpan.FromMinutes(10));
var ttl = rds.GetExpire("k1");

// Batch read/write
rds.SetAll(new Dictionary<String, Object> { ["a"] = 1, ["b"] = 2 }, expire: 300);
var dict = rds.GetAll<Int32>(["a", "b"]);

// Key prefix (FullRedis.Prefix)
var scoped = rds.GetPrefixed("myapp:");
scoped.Set("user", "Alice");  // Actual key is myapp:user

List

var list = rds.GetList<String>("queue:demo");
list.Add("job1");
list.Add("job2");
var first = list[0];
var popped = list.RightPop();

Hash

var hash = rds.GetDictionary<String>("user:1001");
hash["Name"] = "Alice";
hash["Email"] = "alice@example.com";
var name = hash["Name"];
var all = hash.GetAll();

Set / Sorted Set

var set = rds.GetSet<String>("tags");
set.Add("redis");
set.Add("cache");
var contains = set.Contains("redis");

var zset = rds.GetSortedSet<String>("leaderboard");
zset.Add("Player1", 100.0);
zset.Add("Player2", 95.5);
var top3 = zset.GetByRank(0, 2);

Stack

var stack = rds.GetStack<String>("undo:ops");
stack.Push("op1");
stack.Push("op2");
var last = stack.Pop();   // "op2"

Geo

var geo = rds.GetGeo("locations");
geo.Add("Beijing",  116.4074, 39.9042);
geo.Add("Shanghai", 121.4737, 31.2304);
var dist = geo.GetDistance("Beijing", "Shanghai", "km");
var nearby = geo.Search("Beijing", 500, "km");

HyperLogLog

var hll = rds.GetHyperLogLog("uv:today");
hll.Add("user1", "user2", "user3");
var count = hll.Count;  // Approximate cardinality
hll.Merge("uv:yesterday");

Note: The base Redis instance only supports KV operations. Use FullRedis for advanced collections.

Pipeline significantly reduces network round-trips (RTT) and improves bulk operation throughput:

// Explicit pipeline
rds.StartPipeline();
for (var i = 0; i < 1000; i++) rds.Set($"p:{i}", i);
var results = rds.StopPipeline(true);

Auto mode (recommended for production):

rds.AutoPipeline = 100;    // Auto-commit when 100 write operations accumulate
rds.FullPipeline = true;   // Both reads and writes enter the pipeline (throughput-first scenarios)

Simple Queue

var queue = rds.GetQueue<OrderMsg>("orders");

// Producer
queue.Add(new OrderMsg { OrderId = "12345", Amount = 99.9m });

// Consumer (blocking wait; timeout=0 means block indefinitely)
var msg = queue.TakeOne(timeout: 30);

Reliable Queue (at-least-once semantics)

var queue = rds.GetReliableQueue<OrderMsg>("orders");

// Produce
queue.Add(new OrderMsg { OrderId = "12345" });

// Consume + Acknowledge
var msg = queue.TakeOne(timeout: 30);
if (msg != null)
{
    // Process the message...
    queue.Acknowledge(msg);   // Acknowledge consumption; removed from Ack queue
}
// If the process crashes without acknowledging, the message is automatically rolled back
// to the main queue after 60 seconds

Delay Queue

var delay = rds.GetDelayQueue<OrderMsg>("orders:delay");

// Available for consumption after 60 seconds
delay.Add(new OrderMsg { OrderId = "12345" }, delay: 60);

// Consume (auto-waits for due messages)
var msg = delay.TakeOne(timeout: 5);

Stream Queue (Redis 5.0+, multi-consumer-group)

var stream = rds.GetStream<LogEntry>("logs");
stream.Group = "processor-group";

// Produce
stream.Add(new LogEntry { Level = "INFO", Message = "Application started" });

// Consume (multiple instances compete within the same group)
var entry = stream.TakeOne(timeout: 15);
if (entry != null)
{
    // Process...
    stream.Acknowledge(entry.Id);
}

var pubsub = rds.GetPubSub("events:user");

// Publish
pubsub.Publish("login:Alice");

// Subscribe (async loop)
var cts = new CancellationTokenSource();
await pubsub.SubscribeAsync((channel, message) =>
{
    Console.WriteLine($"[{channel}] {message}");
}, cts.Token);

Multi-Address Auto Failover

// Comma-separated addresses; auto-failover on network errors;
// switches back to the primary node after 60 seconds
var rds = new FullRedis("10.0.0.1:6379,10.0.0.2:6379,10.0.0.3:6379", "pass", 0)
{
    ShieldingTime = 10,   // Shield unavailable nodes for 10 seconds (default)
    Retry = 3,            // Retry count (default)
};

Auto Cluster Mode Detection

// When AutoDetect=true, automatically detect the working mode via INFO
// ⚠️ For public cloud proxy mode, keep the default false to avoid obtaining internal node addresses
var rds = new FullRedis("sentinel-host:26379", "pass", 0)
{
    AutoDetect = true,    // Auto-detect Cluster / Sentinel / Replication
};

Alibaba Cloud KVStore / Tair

// Standard edition (Redis 2.8/4.0/5.0/6.0/7.0)
var rds = new FullRedis("xxxxxx.redis.rds.aliyuncs.com:6379", "YourPassword", 0);

// Redis 6.0 ACL user authentication
var rds = new FullRedis("xxxxxx.redis.rds.aliyuncs.com:6379", "YourUser", "YourPassword", 0);

// SSL encrypted connection
var rds = new FullRedis("xxxxxx.redis.rds.aliyuncs.com:6380", "YourPassword", 0)
{
    SslProtocol = SslProtocols.Tls12,
};

// ⚠️ Public cloud proxy mode: Keep AutoDetect at its default false
// ⚠️ Cluster edition: Proxy handles shard routing; clients don't need to know the internal topology

Tencent Cloud Redis

// Tencent Cloud standard/cluster edition: use instance ID as UserName (AUTH instanceId:password format)
var rds = new FullRedis("xxxxxx.redis.tencentcds.com:6379", "instanceId", "YourPassword", 0);

// Or via connection string
var rds = FullRedis.Create("server=xxxxxx.redis.tencentcds.com:6379;username=instanceId;password=YourPassword;db=0");

Huawei Cloud DCS

// Master/Standby edition (standard AUTH)
var rds = new FullRedis("xxxxxx.dcs.myhuaweicloud.com:6379", "YourPassword", 0);

// SSL edition (use after downloading the PEM certificate)
var rds = new FullRedis("xxxxxx.dcs.myhuaweicloud.com:6380", "YourPassword", 0)
{
    SslProtocol = SslProtocols.Tls12,
    Certificate = new X509Certificate2("huawei-dcs.pem"),
};

// ⚠️ Cluster edition does not support SELECT; Db must be 0
// ⚠️ AutoDetect = false (default) to avoid internal node address issues

General Cloud Provider Notes:

• Public cloud proxy mode: Keep AutoDetect = false (default) to prevent auto-detection of internal nodes
• Connection quota: Each cloud provider and instance size has connection limits; set the pool Max parameter accordingly
• TCP keepalive: Huawei Cloud defaults to a 300-second TCP idle timeout; set Timeout below that value and periodically PING

Default encoder: RedisJsonEncoder (built-in JSON host), ready to use out of the box.

// Inspect current JSON configuration
var jsonHost = RedisJsonEncoder.GetJsonHost();

// Switch to a custom encoder (e.g., MessagePack)
rds.Encoder = new MyMessagePackEncoder();

Primitive types (String / Int32 / Int64 / Double / Boolean) are serialized directly without going through JSON for maximum performance.

// Redis 6.0+ ACL authentication
var rds = new FullRedis("host:6379", "username", "password", 0);

// TLS encryption (specify protocol version)
rds.SslProtocol = SslProtocols.Tls12;

// Certificate verification (mutual mTLS)
rds.Certificate = new X509Certificate2("client.pem", "certPassword");

// Connection string password encryption (ProtectedKey mechanism)
// Configure ProtectedKey.Instance.Secret; passwords in connection strings are auto-decrypted

// Structured logging
rds.Log       = XTrace.Log;      // Component-level logs (connection changes, cluster changes, retries)
rds.ClientLog = XTrace.Log;      // Protocol-level logs (every command; enable only when debugging)

// Performance counters
rds.Counter = new PerfCounter();
var stats = rds.Counter.GetAll();   // Get ops/s, latency, error rate

// APM distributed tracing (compatible with NewLife.Stardust / OpenTelemetry)
rds.Tracer = DefaultTracer.Instance;
// All Execute / queue produce-consume operations are automatically instrumented, with key as tag

// OpenTelemetry native tracing (net8.0+): subscribe to the built-in ActivitySource
// builder.Services.AddOpenTelemetry().WithTracing(t => t.AddSource(Redis.ActivitySourceName));

NewLife.Redis.Extensions provides deep ASP.NET Core integration:

dotnet add package NewLife.Redis.Extensions

// Program.cs
builder.Services.AddRedisCaching(options =>
{
    options.Server   = "127.0.0.1:6379";
    options.Password = "pass";
    options.Db       = 0;
    options.Prefix   = "myapp:";
});

// Automatically registers IDistributedCache + FullRedis as singletons

// Persist data protection keys to Redis
builder.Services.AddDataProtection()
    .PersistKeysToRedis(redis, "DataProtection-Keys");

NewLife.Redis fully supports Microsoft’s Garnet high-performance Redis-compatible server, with auto-detection and graceful degradation.

var redis = new FullRedis("127.0.0.1:7000", null, 0);

// Auto-detect server type
if (redis.IsGarnet)
    Console.WriteLine("Connected to Garnet server");

Console.WriteLine($"Server type: {redis.ServerType}");  // Redis / Garnet / Unknown
Console.WriteLine($"Server version: {redis.Version}");

See: Garnet Compatibility Documentation (中文)

Legend: ✅ Completed | 🔄 Planned | ❌ Explicitly Not Planned

Data Structures

Message Queues

Cluster Support

Protocol & Advanced Features

Built-in benchmark in source (Samples/Benchmark), typical results (40 logical processors, local Redis 7.0):

Write 400,000 items | 4 threads  | ~576,368 ops/s
Read  800,000 items | 8 threads  | ~647,249 ops/s
Delete 800,000 items | 8 threads | ~1,011,378 ops/s
Batch Write (pipeline) | 4 threads | ~1,800,000 ops/s

Manual bench trigger:

rds.Bench(rand: true, batch: 100);  // Random keys + batch optimization

Actual performance is affected by network RTT / value size / serialization complexity. It is recommended to keep individual values between 1–1.4KB.

• Singleton reuse: FullRedis has an internal connection pool; strongly recommend using a single instance for the entire application lifetime — do not new each time
• Key design: Use : as a hierarchical separator, e.g., user:1001:profile; use Prefix for namespace isolation in production
• Batch first: Prefer GetAll/SetAll over looping single-key operations; use AutoPipeline to auto-merge write operations
• Value size: Keep values within 1–2KB; split large objects / compress / use Hash for field-level storage
• Reliable consumption: Use RedisReliableQueue<T> in production rather than a simple List to avoid message loss
• Cloud providers: Keep AutoDetect = false on public clouds to avoid internal node address issues
• Monitoring: Enable Counter statistics in production; only enable ClientLog when debugging to avoid hot-path logging overhead
• SSL: Enable TLS encrypted transport on public clouds and in production environments

Q: Does it support Redis Cluster sharding? A: Yes. FullRedis auto-detects Cluster mode with AutoDetect=true. CRC16 routing, MOVED/ASK redirections are all implemented. For public cloud proxy mode, keep the default AutoDetect=false.

Q: How does it compare to StackExchange.Redis? A: NewLife.Redis uses a connection-pool model (vs. StackExchange’s multiplexing) for more intuitive connection behavior. Built-in message queue wrappers (reliable queue / delay queue) are a key differentiator. It also supports .NET Framework 4.5. See Competitive Analysis (中文).

Q: How to handle slow queries caused by large values? A: Split data structures (e.g., Hash per-field) + batch reads/writes + binary encoder + control MaxMessageSize (default 1MB limit).

Q: What if the connection pool runs out? A: The default max is 100,000 connections; normal workloads won’t exhaust it. The pool is configurable via Redis.PoolConfig (RedisPoolConfig): min idle / max capacity / idle cleanup time / max lifetime / borrow wait timeout. Connections idle beyond IdleTime are proactively PING-checked when leased; for master-slave switch or rolling proxy update scenarios, lower MaxLifetime to recycle connections faster. If you see wait timeouts, check for connection leaks (missing Dispose) or operations that hold connections for excessively long periods.

Q: Why do connections fail on Alibaba Cloud / Tencent Cloud? A: Check: ① Is AutoDetect set to false (correct default)? ② Is the auth format correct (Tencent Cloud requires username=instanceId)? ③ Are the network security group / whitelist allowing the client IP? ④ Does the cluster edition prohibit using SELECT to switch databases?

Q: Does Garnet support all features? A: Basic operations, List/Hash/Set/ZSet/HLL/Geo, and queues are all supported. Stream is not yet supported and will automatically throw NotSupportedException with a suggestion to use RedisQueue<T> as an alternative.

• RESP3 protocol support (Completed)
• Redis Functions (FCALL/FUNCTION, replacing Lua scripts)
• LMPOP / ZMPOP (Redis 7.0 batch pop)
• RedLock multi-instance distributed lock
• Bitmap / Bitfield operations
• Pattern subscription PSUBSCRIBE full implementation
• UNLINK async delete
• Prometheus metrics export adapter
• Alibaba Cloud Tair Extension (TairString / TairHash / TairZSet supported)
• Huawei Cloud DCS cluster edition node address mapping adapter
• Pub/Sub (Completed)
• RedisStream multi-consumer-group (Completed)
• Garnet server type detection (Completed)

Feedback and feature requests welcome via Issue / PR.

See Competitive Analysis Document (中文) for details.