NewLife.Redis.Extensions
6.3.2025.820-beta1830
.NET 5.0
This package targets .NET 5.0. The package is compatible with this framework or higher.
.NET Core 3.1
This package targets .NET Core 3.1. The package is compatible with this framework or higher.
.NET Standard 2.0
This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
This is a prerelease version of NewLife.Redis.Extensions.
dotnet add package NewLife.Redis.Extensions --version 6.3.2025.820-beta1830
NuGet\Install-Package NewLife.Redis.Extensions -Version 6.3.2025.820-beta1830
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NewLife.Redis.Extensions" Version="6.3.2025.820-beta1830" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="NewLife.Redis.Extensions" Version="6.3.2025.820-beta1830" />
<PackageReference Include="NewLife.Redis.Extensions" />
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add NewLife.Redis.Extensions --version 6.3.2025.820-beta1830
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: NewLife.Redis.Extensions, 6.3.2025.820-beta1830"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package NewLife.Redis.Extensions@6.3.2025.820-beta1830
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=NewLife.Redis.Extensions&version=6.3.2025.820-beta1830&prerelease
#tool nuget:?package=NewLife.Redis.Extensions&version=6.3.2025.820-beta1830&prerelease
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
NewLife.Redis - 高性能 Redis 客户端组件
[English]
NewLife.Redis 是新生命团队打造的 高性能 / 高吞吐 / 易集成 的 Redis 客户端，核心目标：支撑实时计算、海量缓存、可靠消息、分布式基础设施等场景。组件自 2017 年起在多个千万 / 百亿级数据与高并发生产平台稳定运行，经受日均 80+ 亿次 调用考验。
目录
- 核心特性
- 架构与模块划分
- 对比说明
- 安装与快速开始
- 基础用法
- 批量与集合操作
- 管道 Pipeline 与自动合并
- 消息 / 队列 / 可靠消费
- 序列化与编码器
- 性能测试参考
- 最佳实践与经验
- 多实例 & 高可用策略
- 扩展包 (Extensions)
- 与 MemoryCache 的协同
- 常见问题 FAQ
- 路线图 Roadmap
- 新生命项目矩阵
- 贡献指南 & 社区
- 许可证
核心特性
- 经大规模生产验证：200+ Redis 实例，日峰值 1 亿+ 业务对象写入 / 80+ 亿命令调用
- 低延迟：单次 Get/Set 往返 200~600µs（微秒级，含网络）
- 高吞吐：内置 连接池 (最大 100000 并发) + 同步高效协议解析 + 可选自动管道合并
- 自动重试与多地址故障切换：Server 支持逗号分隔多节点，网络型异常快速切换
- 丰富高级结构：List / Hash / Set / Queue / Stack / 延迟与可靠消费（基于 RPOPLPUSH/BRPOPLPUSH）
- 批量优化：
GetAll/SetAll/ 管道聚合显著降低 RTT - 可插拔编码器：默认 JSON，可扩展二进制 / 自定义序列化，以减小包长与 GC 压力
- 追踪与监控：支持
ITracer（APM 链路），可插入性能计数器PerfCounter - 强命名 + 多目标框架：一份包覆盖 net45 / net461 / netstandard2.0 / netstandard2.1 / (扩展包含 netcoreapp3.1→net9)
- 零外部重量级依赖，充分复用 NewLife 生态（日志、配置、序列化、安全）
架构与模块划分
┌──────────────────────────────────────────┐
│ Redis (基础核心) │
│ ├─ 连接池 IPool<ObjectPool<RedisClient>>│
│ ├─ 协议解析 RedisClient / RESP │
│ ├─ 基础 KV / 批量 / 过期 / 计数器 │
│ ├─ 重试 & 多节点切换 / 超时 / 限制 │
│ ├─ Pipeline 管理 (Start/Stop/Auto) │
│ └─ 序列化编码 (IPacketEncoder) │
│ │
│ FullRedis (扩展) │
│ ├─ 列表 RedisList<T> │
│ ├─ 哈希 RedisHash<T> (键值字典) │
│ ├─ 队列 / 栈 / Set / 延迟消费 │
│ ├─ 发布订阅 (若启用) / 搜索辅助 │
│ └─ 可靠消息 (RPOPLPUSH / BRPOPLPUSH) │
│ │
│ Extensions (DI 集成) │
│ ├─ IDistributedCache 实现 │
│ └─ IDataProtection 后端存储 │
└──────────────────────────────────────────┘
关键类说明：
Redis：核心客户端，提供协议管线、连接复用、自动管道、批量操作、性能统计、重试与故障转移。RedisClient：底层连接与 RESP 命令执行单元（内部对象，池化管理）。FullRedis：在Redis基础上追加更丰富数据结构及更高级场景能力。RedisList<T>/RedisHash<T>等：对 Redis 原生命令进行泛型包装，统一编码与序列化策略。IPacketEncoder：编解码策略，可切换 JSON / 二进制。
对比说明
| 能力 | NewLife.Redis | StackExchange.Redis | 备注 |
|---|---|---|---|
| 连接池 | 内置，支持 Max=100000 | Multiplexer（逻辑复用） | 大并发场景更直观可控 |
| 自动管道 | 支持 AutoPipeline/FullPipeline | 默认批量写入合并 | 精细控制与显式 StartPipeline |
| 性能追踪 | ITracer 接口 | 需外部集成 | 生态一致 APM 链路 |
| 序列化 | 可插拔 Encoder | 仅字节/字符串，需外部序列化 | 降低调用侧样板代码 |
| 可靠消费 | RPOPLPUSH/BRPOPLPUSH 包装 | 需手动实现 | 队列式工作流场景便利 |
| 生态整合 | 与 NewLife.* 组件无缝 | 无 | 同一风格 & 工具链 |
安装与快速开始
NuGet：NewLife.Redis
# 稳定版
dotnet add package NewLife.Redis
# 或开发版 (包含预发布)
dotnet add package NewLife.Redis -v *-*
示例（推荐单例，线程安全）：
using NewLife.Caching;
using NewLife.Log;
XTrace.UseConsole();
var rds = new FullRedis("127.0.0.1:6379", "pass", 7)
{
Log = XTrace.Log,
ClientLog = XTrace.Log, // 调试阶段打开
AutoPipeline = 100 // 达到阈值自动提交管道
};
rds.Set("user:1", new { Name = "Alice", Time = DateTime.Now }, 3600);
var user = rds.Get<String>("user:1");
Console.WriteLine(user);
基础用法
rds.Set("k1", 123, 600); // 设置并指定过期
var v = rds.Get<Int32>("k1");
var ok = rds.Add("k2", "init"); // 仅在不存在时写入
var old = rds.Replace("k2", "new");
rds.Increment("counter", 1);
rds.Decrement("counter", 2);
过期管理：SetExpire(key, TimeSpan) 与 GetExpire(key)。
批量与集合操作
rds.SetAll(new Dictionary<String,Object>{{"a",1},{"b",2},{"c",3}}, 300);
var dict = rds.GetAll<Int32>(new[]{"a","b","c"});
泛型集合：
var list = rds.GetList<String>("queue:demo");
list.Add("job1");
var first = list[0];
注意：基础
Redis实例仅支持字符串类操作，高级集合请实例化FullRedis。
管道 Pipeline 与自动合并
场景：减少 RTT、提升批量操作吞吐。
var client = rds.StartPipeline();
for (var i = 0; i < 1000; i++) rds.Set($"p:{i}", i);
var results = rds.StopPipeline(); // results 为命令返回集合
自动模式：设置 AutoPipeline = 100 后，写操作累积到阈值自动提交；FullPipeline = true 时读请求也进入管道。
消息 / 队列 / 可靠消费
利用 List + RPOPLPUSH / BRPOPLPUSH 保障“取出-处理中-确认”原子性：
var src = rds.GetList<String>("jobs:ready");
var bak = rds.GetList<String>("jobs:working");
var job = src.RPOPLPUSH(bak.Key); // 取出放入备份队列
// 处理成功后从备份列表删除
bak.Remove(job);
阻塞获取：BRPOPLPUSH(destKey, timeoutSeconds)，timeout=0 表示永久阻塞。
序列化与编码器
默认编码：RedisJsonEncoder（内置 JSON 主机）。可通过实现 IPacketEncoder 定制二进制格式以减少内存与网络：
rds.Encoder = new MyBinaryEncoder();
如需共享 JSON 配置或自定义时间/数字格式，可设置：rds.JsonHost = RedisJsonEncoder.GetJsonHost();
性能测试参考
源码内置 Benchmark（Redis.Bench），典型结果（40 逻辑处理器，批量优化）：
写入 400,000 项 4 线程 ~576,368 ops
读取 800,000 项 8 线程 ~647,249 ops
删除 800,000 项 8 线程 ~1,011,378 ops
可执行：
rds.Bench(rand:true, batch:100); // 随机 + 批量
实际性能受网络 RTT / 序列化复杂度 / Value 大小影响。建议单 Value 控制在 1.4KB 附近提升整体效率。
最佳实践与经验
- 多实例拆分：按 Key 哈希 (CRC16/CRC32) 分布到多 Redis，提高扩展性
- 合理 Value 大小：控制在 1~2KB；过大分片 / 压缩 / 结构化
- 批量优先：能
GetAll/SetAll不循环单键；利用管道降低往返 - 高可靠消费：
RPOPLPUSH+ 备份列表手动确认 - 序列化：二进制优于 JSON；必要时，用池化缓冲减少 GC
- 性能监控：开启
Counter/Tracer仅在需要时，避免热路径开销
多实例 & 高可用策略
Server 可配置："10.0.1.10:6379,10.0.1.11:6379"。
- 发生网络型异常（Socket/IO）时自动切换下一个地址
ShieldingTime控制不可用节点屏蔽窗口- 一段时间后自动尝试回切主节点
扩展包 (Extensions)
NewLife.Redis.Extensions 提供 ASP.NET Core 集成：
IDistributedCache后端实现IDataProtection密钥存储
安装：
dotnet add package NewLife.Redis.Extensions
示例：
builder.Services.AddRedisCaching(options =>
{
options.Server = "127.0.0.1:6379";
options.Password = "pass";
});
与 MemoryCache 的协同
建议以 ICache 编程：小数据或临时热点 → MemoryCache；规模上升/跨进程共享 → 切换 Redis/FullRedis，无须修改业务逻辑。
常见问题 FAQ
Q: 是否支持发布订阅 / Stream / Cluster？
A: 基础代码已具备扩展点，发布订阅/更多结构可在 FullRedis 扩展层或后续版本完善。Cluster 分片可通过多实例 + Key 路由策略实现。
Q: 如何处理反序列化失败？
A: TryGetValue 返回是否存在键，即使反序列化失败仍可感知，用于容错与告警。
Q: 如何降低大 Value 带来的慢查询？
A: 拆分结构 + 批量 + 二进制编码 + 控制 MaxMessageSize（默认 1MB）。
路线图 Roadmap
- [*] 发布订阅友好封装（模式订阅 / 回调）
- 更完善的分布式锁 / RedLock 支持
- [*] Stream / 消费组封装
- 更灵活的二进制/Span Encoder 示例
- 内置指标导出（Prometheus 适配器）
- 单测覆盖率提升 & BenchmarkDotNet 场景脚本化
欢迎通过 Issue / PR 参与投票或补充需求。
新生命项目矩阵
（节选） | 项目 | 说明 | | ---- | ---- | | NewLife.Core | 核心库，日志/配置/缓存/序列化/APM | | NewLife.XCode | 大数据 ORM，百亿级 + 分表 + 读写分离 | | NewLife.Net | 超高性能网络库（千万级吞吐） | | Stardust | 分布式服务/配置/注册/发布中心 | | AntJob | 分布式计算 & 调度平台 | | NewLife.RocketMQ | RocketMQ 纯托管客户端 | | ... | 更多见官网与组织首页 |
完整矩阵、企业级解决方案与商业支持请访问：https://newlifex.com
贡献指南 & 社区
- 提交前阅读仓库
.github/copilot-instructions.md（编码规范 & 审核清单） - 提交 PR：保持最小变更、添加必要注释与测试说明
- Issue：提供版本、运行环境、最小复现场景
社区：QQ群 1600800 / 1600838 ；GitHub Discussions / Issues 参与答疑。
许可证
MIT License。可自由商用 / 修改 / 再发行（无需额外授权）。保留版权声明即可。
新生命开发团队
团队自 2002 年迄今，维护 80+ .NET / IoT / 分布式相关开源项目，NuGet 累计下载超 400 万。产品与组件已广泛服务于电力、物流、工业控制、教育、通信、文博等行业。
网站：https://newlifex.com | 开源：https://github.com/NewLifeX
微信公众号：
若本文档未覆盖你的使用场景，欢迎提交 Issue 补充；一起让文档更完善！
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 is compatible. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 is compatible. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
.NETCoreApp 3.1
- Microsoft.AspNetCore.DataProtection (>= 3.1.0)
- Microsoft.Extensions.Caching.Abstractions (>= 3.1.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 3.1.0)
- Microsoft.Extensions.Options (>= 3.1.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
.NETStandard 2.0
- Microsoft.AspNetCore.DataProtection (>= 6.0.0)
- Microsoft.Extensions.Caching.Abstractions (>= 6.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 6.0.0)
- Microsoft.Extensions.Options (>= 6.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
.NETStandard 2.1
- Microsoft.AspNetCore.DataProtection (>= 6.0.0)
- Microsoft.Extensions.Caching.Abstractions (>= 6.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 6.0.0)
- Microsoft.Extensions.Options (>= 6.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
net5.0
- Microsoft.AspNetCore.DataProtection (>= 5.0.8)
- Microsoft.Extensions.Caching.Abstractions (>= 5.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 5.0.0)
- Microsoft.Extensions.Options (>= 5.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
net6.0
- Microsoft.AspNetCore.DataProtection (>= 6.0.0)
- Microsoft.Extensions.Caching.Abstractions (>= 6.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 6.0.0)
- Microsoft.Extensions.Options (>= 6.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
net7.0
- Microsoft.AspNetCore.DataProtection (>= 7.0.0)
- Microsoft.Extensions.Caching.Abstractions (>= 7.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
net8.0
- Microsoft.AspNetCore.DataProtection (>= 8.0.0)
- Microsoft.Extensions.Caching.Abstractions (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Options (>= 8.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
-
net9.0
- Microsoft.AspNetCore.DataProtection (>= 9.0.0)
- Microsoft.Extensions.Caching.Abstractions (>= 9.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.0)
- Microsoft.Extensions.Options (>= 9.0.0)
- NewLife.Redis (>= 6.3.2025.820-beta1830)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on NewLife.Redis.Extensions:
| Package | Downloads |
|---|---|
|
CodeRule
业务流水号规则生成器，便于快速生成流水号 |
GitHub repositories
This package is not used by any popular GitHub repositories.
新增数据保护IDataProtection