DOCSEARCHbyAlgolia
Submit Docs

StackExchange.Redis Documentation

repository·main·Indexed 27 days ago

https://github.com/stackexchange/stackexchange.redis

A high-performance .NET client for communicating with Redis and other RESP-compatible servers, including Valkey, Garnet, and AWS ElastiCache. The library includes RESPite, a low-level RESP I/O core, and supports advanced features such as Redis Arrays (Redis 8.8+), ring buffers, and server-side operations. Documentation covers installation via NuGet, asynchronous timeout and cancellation handling, and benchmarking tools like RESPite.Benchmark and OpBench.

Tokens
35.9K
Snippets
80
Records
201
Agent score
42%

What's inside StackExchange.Redis

  3. Use OpBench to measure Redis throughput

    main

    OpBench is a basic client designed to demonstrate achieved throughput by simulating workloads. It is intended to be modified so consumers can substitute commands to better represent their specific workloads. It is not a fully featured benchmarking tool.

    To use OpBench, you specify the work to perform via the Work property. You can optionally provide an Init step for once-only setup tasks.

  5. Understand the RESPite library

    main

    RESPite is an experimental, high-performance, low-level library designed for RESP (Redis Serialization Protocol) parsing and serialization. It serves as the I/O core for StackExchange.Redis v3+.

    Warning: This library is experimental. It is recommended that you do not use RESPite directly unless you have a specific, high-performance requirement that necessitates bypassing the standard StackExchange.Redis API.

  6. New features in StackExchange.Redis v2.1.0

    main

    Version 2.1.0 introduced several new capabilities:

    • Sentinel Support: Added support for Redis Sentinel.
    • IAsyncEnumerable Scanning: Scanning APIs now support IAsyncEnumerable<T>.
    • Condition API: The Condition API for transactions now supports SortedSetLengthEqual.
    • Redis Streams: Updated StreamCreateConsumerGroup to use the MKSTREAM option and added support for NOACK in StreamReadGroup methods.
    • Command Support: Added support for TOUCH, LATENCY, MEMORY, and HSTRLEN commands.
    • Configuration: Added support for the CheckCertificatRevocation configuration option.

  7. Understand Multiplexing in StackExchange.Redis

    main

    StackExchange.Redis uses a single connection to multiplex many concurrent callers. It automatically pipelines requests from different parts of your application, filling the network's 'waiting' time with work from other callers. This allows for extremely high throughput on a single connection.

    Important Limitations:

    • Because of the multiplexing architecture, StackExchange.Redis does not support blocking pops (e.g., BLPOP, BRPOP, BRPOPLPUSH). Using these would stall the entire multiplexer and block all other callers on that connection.
    • If you require the functionality of blocking pops, use a combination of Redis Lists and the Pub/Sub API instead.

  10. Choose between Sync, Async, and Fire-and-Forget patterns

    main

    StackExchange.Redis provides three primary execution patterns:

    1. Synchronous: The method returns only after the operation completes. While it may block the calling thread, it does not block the underlying connection, allowing other threads to share the connection.
    2. Asynchronous: Methods ending in Async return a Task or Task<T>. These should be await-ed for best performance.
    3. Fire-and-Forget: Use the CommandFlags.FireAndForget flag. The method returns the default value (e.g., null or 0) immediately, and the operation continues in the background. Use this when you do not need the response (e.g., incrementing counters).

  11. Profile CPU and network usage by key using HotKeys

    main

    The HOTKEYS command (available in Redis 8.6+) allows for server-side profiling of CPU and network usage by key. You can access this functionality via IServer.HotKeys* methods.

    To use it:

    1. Get an IServer instance using muxer.GetServer(endpoint) or muxer.GetServer(key).
    2. Start the capture using HotKeysStartAsync. It is recommended to specify a duration to prevent the profiler from running indefinitely if a failure occurs.
    3. Perform work or wait for activity.
    4. Fetch results using HotKeysGetAsync. This can be called while the capture is running or after it completes. Note that only one capture can be active at a time.
    5. (Optional) Use HotKeysResetAsync to discard active capture data at the server.
    // Get the server instance.
IConnectionMultiplexer muxer = ... // connect to Redis 8.6 or later
var server = muxer.GetServer(endpoint); // or muxer.GetServer(key)

// Start the capture; specifying a duration is recommended.
await server.HotKeysStartAsync(duration: TimeSpan.FromSeconds(30));

// Now either do some work ourselves, or await for some other activity to happen:
await Task.Delay(TimeSpan.FromSeconds(35)); 

// Fetch the results; note that this does not stop the capture.
var result = await server.HotKeysGetAsync();

// ...investigate the results... 

// Optional: discard the active capture data at the server, if any.
await server.HotKeysResetAsync();