DOCSEARCHbyAlgolia
Submit Docs

NewLife.Redis

repository·master·Indexed 21 days ago

https://github.com/newlifex/newlife.redis

A high-performance .NET Redis client for high-throughput production environments. It supports a wide range of Redis versions, data structures (Lists, Hashes, Sets, Geo, HyperLogLog), and high-availability modes including Cluster and Sentinel. The library provides multiple queue patterns (Simple, Reliable, Delay, and Stream), Pub/Sub messaging, and pipeline optimization to reduce network RTT. The NewLife.Redis.Extensions package offers integration for ASP.NET Core via IDistributedCache and IDataProtection.

Tokens
28.3K
Snippets
58
Records
112
Agent score
73%

What's inside NewLife.Redis

  1. Overview of NewLife.Redis

    master

    NewLife.Redis is a high-performance, high-throughput .NET Redis client designed for easy integration. It is built to handle massive scale, supporting billions of daily command calls with low latency (200–600µs per round-trip).

    Key capabilities include:

    • Full Protocol Support: Implements RESP2, covering Redis 2.8 through 7.x commands and data structures.
    • Advanced Data Structures: Native support for String, List, Hash, Set, Sorted Set, Stream, Geo, and HyperLogLog.
    • Built-in Message Queues: Includes Simple, Reliable (at-least-once), Delay, and Stream (multi-consumer-group) queue implementations.
    • High Availability: Supports Standalone, Master-Replica, Sentinel, and Native Cluster modes with automatic failover.
    • Cloud Compatibility: Specialized adapters for Alibaba Cloud KVStore/Tair, Tencent Cloud Redis, and Huawei Cloud DCS.
    • Broad Compatibility: Works from .NET Framework 4.5 up to .NET 10+ and auto-detects compatible servers like Microsoft Garnet or kvrocks.

  2. Overview of NewLife.Redis features

    master

    NewLife.Redis is a high-performance, high-throughput .NET Redis client designed for easy integration. Key capabilities include:

    • Protocol Support: Full RESP2/RESP3 support and compatibility with Redis versions 2.8 through 7.x.
    • Data Structures: Supports String, List, Hash, Set, Sorted Set, Stream, Geo, and HyperLogLog.
    • Message Queuing: Provides simple, reliable (RPOPLPUSH+Ack), delayed, and Stream-based multi-consumer group messaging.
    • High Availability: Supports Standalone, Sentinel, and Cluster modes with automatic failover.
    • Cloud Compatibility: Supports Alibaba Cloud KVStore, Tencent Cloud Redis, and Huawei Cloud DCS.
    • Compatibility: Works with .NET Framework 4.5 through .NET 10+. Includes automatic detection for Microsoft Garnet and kvrocks, providing graceful fallbacks for unsupported features.

  3. Compare NewLife.Redis with other .NET Redis clients

    master

    NewLife.Redis is positioned as an industrial-grade, high-throughput client with a focus on reliable message queues and seamless integration with the NewLife ecosystem. It is particularly well-suited for legacy systems requiring support for older .NET versions.

    Key differentiators:

    • Legacy Support: Unlike StackExchange.Redis (which requires .NET 4.6.1+), NewLife.Redis supports .NET Framework 4.5, making it ideal for industrial, IoT, and government legacy systems.
    • Connection Model: Uses an ObjectPool (Connection Pool) model, which provides better isolation and easier debugging compared to the multiplexing model used by StackExchange.Redis.
    • Cloud & Alternative Implementations: Features explicit detection and graceful degradation for alternative Redis implementations like Microsoft Garnet and kvrocks.
    • Ecosystem: Deep integration with the NewLife ecosystem and strong support for Chinese-speaking developer communities.

  4. Key Features of NewLife.Redis

    master

    NewLife.Redis is a high-performance .NET client with the following capabilities:

    • Protocol Support: Full RESP2/RESP3 support; compatible with Redis versions 2.8 through 7.x.
    • Data Structures: Supports String, List, Hash, Set, Sorted Set, Stream, Geo, and HyperLogLog.
    • Message Queues: Provides simple and reliable queues (using RPOPLPUSH+Ack), delayed queues, and Stream-based queues with consumer groups.
    • High Availability: Supports Standalone, Sentinel, and Cluster modes with automatic failover.
    • Cloud Compatibility: Optimized for Alibaba Cloud KVStore, Tencent Cloud Redis, and Huawei Cloud DCS.
    • Framework Support: Compatible with .NET Framework 4.5 through .NET 10+.
    • Alternative Compatibility: Auto-detects Microsoft Garnet or kvrocks with graceful degradation.

  5. Performance Overview of NewLife.Redis

    master

    NewLife.Redis is a high-performance Redis client for the .NET platform. Performance benchmarks focus on five core paths: request serialization, type conversion, command execution, pipeline mode, and batch operations.

    Key performance characteristics include:

    • Low Latency: Single command latency is stable at approximately 44~47μs (including network RTT).
    • Memory Efficiency: Significant reductions in memory allocation per operation (e.g., Execute operations see reductions of ~42-52% per call).
    • Reduced GC Pressure: Optimized paths significantly lower Gen0 garbage collection frequency (by 33% to 50% in large-scale scenarios).

  6. Supported High Availability and Cluster Modes

    master

    NewLife.Redis supports various deployment topologies:

    • Standalone: Direct connection to a single node using connection pool reuse.
    • Replication (Master-Slave): Automatically identifies master and slave nodes to route writes to the master and reads to the slaves.
    • Sentinel: Automatically monitors master-slave transitions and perceives failovers.
    • Native Cluster: Supports CRC16 SLOT routing and handles MOVED/ASK redirections.
    • Auto-Detection: The AutoDetect mode automatically identifies the operational mode via the INFO command.
    • Health Monitoring: Periodically refreshes the node list (every 60 seconds) and removes unhealthy nodes.
    • Distributed Locking: Supports atomic distributed locks using SETNX + TTL and the RedLock algorithm for multi-instance environments.

  7. Core Use Cases for NewLife.Redis

    master

    NewLife.Redis is designed for several high-scale scenarios:

    ScenarioDescription
    High-Frequency CachingUser Sessions, product details, and hot data (up to billions of keys)
    Distributed LockingIdempotency control and concurrency prevention (tens of thousands/sec)
    Message QueuingAsynchronous decoupling for orders, logistics, and notifications
    Delayed TasksOrder timeout cancellations and scheduled callbacks
    Stream ConsumptionIoT data collection and log aggregation (hundreds of millions of messages/day)
    Pub/SubReal-time notifications and configuration pushes
    GeospatialLocation services and nearby merchant searches
    Statistics & LeaderboardsUV/PV counting, cardinality statistics, and ranking lists

  8. Optimize Redis memory allocation and GC performance

    master

    To achieve high performance and minimize Garbage Collection (GC) overhead in NewLife.Redis, the library implements several memory management strategies. If you are experiencing high memory pressure or Large Object Heap (LOH) allocations during heavy Redis operations, understand that the library has been optimized through the following architectural changes:

    1. Removal of BufferedStream: The library avoids using BufferedStream for command I/O, as it can lead to significant Byte[] allocations.
    2. Span-based Encoding: The Encode process (converting parameters to byte arrays) uses Span<T> to perform direct encoding/conversions, avoiding unnecessary intermediate byte array allocations.
    3. Pre-encoded Parameters: To prevent inaccurate buffer size estimation (which causes large memory borrows and LOH allocations), the library encourages/implements a pattern where parameters are encoded into strings or byte arrays before the command execution. This allows for precise Span writing.

  9. Supported Redis Data Structures and .NET Wrappers

    master

    NewLife.Redis provides high-level .NET wrappers for standard Redis data types to simplify development. Use the following mappings to choose the correct class for your data structure:

    Redis Type.NET Wrapper Class
    StringRedis (Direct Key-Value)
    ListRedisList<T>
    HashRedisHash<TKey, TValue>
    SetRedisSet<T>
    Sorted SetRedisSortedSet<T>
    Stack (LIFO)RedisStack<T>
    StreamRedisStream<T>
    GeoRedisGeo
    HyperLogLogHyperLogLog
    Prefixed NamespacePrefixedRedis (String + Prefix)
    Bitmap/BitfieldSupported via String Bitfield

  10. Use RESP3 Protocol for Optimized Performance

    master
    Starting from version v6.5.2026.0302, NewLife.Redis supports the RESP3 protocol. Enabling RESP3 can provide optimized core performance allocations compared to the older RESP2 protocol. This version also improved compatibility detection for Garnet.

  11. Understand NewLife.Redis Performance Optimizations

    master

    The library implements several low-level optimizations to minimize memory allocation and improve throughput:

    1. ReadLine Optimization

    In RedisClient.cs, the ReadLine method was optimized to use stackalloc Char[256] with an index counter instead of retrieving a StringBuilder from a pool. This reduces allocation from ~48B to 0B per call. For NETFRAMEWORK or NETSTANDARD2_0, it gracefully degrades using span[..k].ToString().

    2. Type Conversion Specialization

    The TryChangeType method in RedisClient.cs uses direct TryParse fast paths for common types (Boolean, Int32, Int64, Double, String). This avoids the boxing overhead associated with the generic Convert.ChangeType path.

    3. Single Response Fast Path

    New methods GetSingleResponse and GetSingleResponseAsync were added to RedisClient.cs. Unlike the standard ExecuteCommand which creates a new List<Object?>() to handle responses, these methods use ParseSingleResponse to return the Object? directly, eliminating the list allocation.

    4. Deferred Pipeline Command List

    In the StopPipeline method of RedisClient.cs, the List<String> cmds is now only created if a Tracer is active. If no Tracer is present, the allocation and population of the command list are skipped entirely.

  12. Monitor Redis Performance and Observability

    master

    NewLife.Redis includes built-in support for observability:

    • Logging: Supports the ILog interface for integration with XTrace or other logging frameworks.
    • Metrics:
      • Uses PerfCounter to track operation latency, success, and failure counts.
      • Provides a GetPrometheusMetrics method for Prometheus-formatted metric export.
    • Tracing: Implements ITracer for production/consumption instrumentation, compatible with OpenTelemetry.
    • Connection Pool Stats: Monitor active, idle, and waiting connection counts.
    • Server Info: Automatically parses INFO commands (Version, ServerType, connected_slaves, etc.). Use the ShowInfo method to print detailed information like Stream consumer group status.