Smart.StackRedis 5.0.0

Smart.StackRedis

English | 中文

<a name="english"></a>

English

Smart.StackRedis is a Redis helper library built on StackExchange.Redis. It provides dependency injection support, key prefixing, JSON serialization, Redis data type modules, distributed lock helpers, counters, transactions, and pub/sub (StackExchange.Redis restores subscriptions automatically after a reconnect). It supports .NET 8, 9, and 10.

Installation

dotnet add package Smart.StackRedis

Registration

using Microsoft.Extensions.DependencyInjection;
using Smart.StackRedis;

services.AddSmartRedis(new RedisOptions
{
    Server = "127.0.0.1:6379,password=password,abortConnect=false",
    Prefix = "prod:",
    ConnectTimeout = 15000,
    SyncTimeout = 5000,
    AbortOnConnectFail = false,
    ConnectRetry = 3
});

Examples

public class UserService
{
    private readonly SmartRedisService _redis;

    public UserService(SmartRedisService redis)
    {
        _redis = redis;
    }

    public Task<bool> CacheUserAsync(User user)
    {
        return _redis.String.SetAsync($"users:{user.Id}", user, TimeSpan.FromHours(1));
    }

    public Task<User?> GetUserAsync(string userId)
    {
        return _redis.String.GetAsync<User>($"users:{userId}");
    }
}

await redis.Hash.SetAsync("profiles:1", "name", "Tom");
string? name = await redis.Hash.GetAsync("profiles:1", "name");

await redis.List.RightPushAsync("jobs", job);
Job? next = await redis.List.LeftPopAsync<Job>("jobs");

await redis.Set.AddAsync("tags", new List<string> { "redis", "cache" });
string[] tags = await redis.Set.GetAllMembersAsync("tags");

string lockToken = Guid.NewGuid().ToString("N"); // value must be unique to the lock holder
bool locked = await redis.Lock.TakeAsync("order:1", lockToken, expiry: 30);
try
{
    if (locked)
    {
        await ProcessOrderAsync();
    }
}
finally
{
    if (locked)
    {
        await redis.Lock.ReleaseAsync("order:1", lockToken);
    }
}

await redis.Counter.InitialValueAsync("article:1:views", 0);
long views = await redis.Counter.IncrementAsync("article:1:views");
long current = await redis.Counter.CurrentValueAsync("article:1:views");

redis.SubscribeReceived += (channel, message) =>
{
    Console.WriteLine($"Received message on {channel}: {message}");
};

await redis.Subscribe.SubscribeAsync("notifications");
await redis.Subscribe.PublishAsync("notifications", "hello");

Configuration Notes

RedisOptions wins over the connection string for the settings it exposes; set a property to null to fall back to the connection-string value.

services.AddSmartRedis(new RedisOptions
{
    Server = "127.0.0.1:6379,password=password",
    Prefix = "prod:",
    ConnectTimeout = null,   // keep the value from the connection string
    AllowAdmin = false       // FLUSHALL / CONFIG / SHUTDOWN stay disabled
});

Stream Example

// Create the group once (idempotent, creates the stream if it does not exist yet)
await redis.Stream.CreateConsumerGroupAsync("orders", "billing", "$");

// Bound the stream so it cannot grow forever
string? messageId = await redis.Stream.AddAsync("orders", "payload", json, maxLength: 100_000);

StreamEntry[] entries = await redis.Stream.ReadGroupAsync("orders", "billing", "worker-1", "$", count: 10);
foreach (StreamEntry entry in entries)
{
    await redis.Stream.AcknowledgeAsync("orders", "billing", entry.Id);
}

Modules

<a name="chinese"></a>

中文

Smart.StackRedis 是基于 StackExchange.Redis 的 Redis 工具库，提供依赖注入、键前缀、JSON 序列化、Redis 数据类型模块、分布式锁、计数器、事务和发布订阅能力（断线后的重新订阅由 StackExchange.Redis 自动完成）。兼容 .NET 8/9/10。

安装

dotnet add package Smart.StackRedis

注册

using Microsoft.Extensions.DependencyInjection;
using Smart.StackRedis;

services.AddSmartRedis(new RedisOptions
{
    Server = "127.0.0.1:6379,password=password,abortConnect=false",
    Prefix = "prod:",
    ConnectTimeout = 15000,
    SyncTimeout = 5000,
    AbortOnConnectFail = false,
    ConnectRetry = 3
});

示例

public class UserService
{
    private readonly SmartRedisService _redis;

    public UserService(SmartRedisService redis)
    {
        _redis = redis;
    }

    public Task<bool> CacheUserAsync(User user)
    {
        return _redis.String.SetAsync($"users:{user.Id}", user, TimeSpan.FromHours(1));
    }

    public Task<User?> GetUserAsync(string userId)
    {
        return _redis.String.GetAsync<User>($"users:{userId}");
    }
}

await redis.Hash.SetAsync("profiles:1", "name", "Tom");
string? name = await redis.Hash.GetAsync("profiles:1", "name");

await redis.List.RightPushAsync("jobs", job);
Job? next = await redis.List.LeftPopAsync<Job>("jobs");

await redis.Set.AddAsync("tags", new List<string> { "redis", "cache" });
string[] tags = await redis.Set.GetAllMembersAsync("tags");

string lockToken = Guid.NewGuid().ToString("N"); // value must be unique to the lock holder
bool locked = await redis.Lock.TakeAsync("order:1", lockToken, expiry: 30);
try
{
    if (locked)
    {
        await ProcessOrderAsync();
    }
}
finally
{
    if (locked)
    {
        await redis.Lock.ReleaseAsync("order:1", lockToken);
    }
}

await redis.Counter.InitialValueAsync("article:1:views", 0);
long views = await redis.Counter.IncrementAsync("article:1:views");
long current = await redis.Counter.CurrentValueAsync("article:1:views");

redis.SubscribeReceived += (channel, message) =>
{
    Console.WriteLine($"在 {channel} 收到消息: {message}");
};

await redis.Subscribe.SubscribeAsync("notifications");
await redis.Subscribe.PublishAsync("notifications", "hello");

配置与行为说明

RedisOptions 中显式赋值的属性会覆盖连接字符串中的同名参数；将属性设为 null 则以连接字符串为准。

services.AddSmartRedis(new RedisOptions
{
    Server = "127.0.0.1:6379,password=password",
    Prefix = "prod:",
    ConnectTimeout = null,   // 沿用连接字符串中的设置
    AllowAdmin = false       // 默认关闭 FLUSHALL / CONFIG / SHUTDOWN
});

Stream 示例

// 创建消费者组（幂等；流不存在时自动创建）
await redis.Stream.CreateConsumerGroupAsync("orders", "billing", "$");

// 限制流长度，避免无界增长
string? messageId = await redis.Stream.AddAsync("orders", "payload", json, maxLength: 100_000);

StreamEntry[] entries = await redis.Stream.ReadGroupAsync("orders", "billing", "worker-1", "$", count: 10);
foreach (StreamEntry entry in entries)
{
    await redis.Stream.AcknowledgeAsync("orders", "billing", entry.Id);
}

模块

Developed by zenglei