Skip to content

Commit 77c2131

Browse files
imperugoimperugo
committed
Bump version to 12.1.0, add migration guide v11→v12
- VersionPrefix 12.0.0 → 12.1.0 - PackageReleaseNotes updated with v12.1.0 changes (VectorSet, llms.txt, Claude plugin, CodeQL, SECURITY.md, CI workflow) - doc/migration-v11-to-v12.md: comprehensive migration guide covering SyncTimeout change, Sentinel fix, SE.Redis upgrade, all new features, dependency changes, FAQ - Linked migration guide from README and doc/README.md
1 parent 4734135 commit 77c2131

File tree

4 files changed

+200
-1
lines changed

4 files changed

+200
-1
lines changed

‎Directory.Build.props‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<!-- General information -->
44
<PropertyGroup>
55
<Authors>Ugo Lattanzi</Authors>
6-
<VersionPrefix>12.0.0</VersionPrefix>
6+
<VersionPrefix>12.1.0</VersionPrefix>
77
<!--
88
<VersionSuffix>pre</VersionSuffix>
99
-->
@@ -46,6 +46,15 @@ Features:
4646
Serializer packages (pick one): System.Text.Json, Newtonsoft, MemoryPack, MsgPack, Protobuf, ServiceStack, Utf8Json.
4747
</Description>
4848
<PackageReleaseNotes>
49+
v12.1.0:
50+
- Added VectorSet API for AI/ML similarity search (Redis 8.0+): VADD, VSIM, VREM, VCONTAINS, VCARD, VDIM, VGETATTR, VSETATTR, VINFO, VRANDMEMBER, VLINKS
51+
- Added llms.txt for AI coding assistant documentation indexing
52+
- Added Claude Code plugin with configure, scaffold, and diagnose skills
53+
- Added complete API reference tables to all feature documentation
54+
- Added SECURITY.md with GitHub Private Vulnerability Reporting
55+
- Added CodeQL Advanced security analysis workflow
56+
- Added CI workflow for automated testing on push/PR
57+
4958
v12.0.0:
5059
- Added .NET 10 target framework
5160
- Added GeoSpatial API (GEOADD, GEOSEARCH, GEODIST, GEOPOS, GEOHASH)

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,7 @@ Full documentation is available in the [doc/](doc/) folder:
326326
- [Compression](doc/compressors.md) — GZip, Brotli, LZ4, Snappy, Zstandard
327327

328328
**Advanced**
329+
- [Migration Guide: v11 → v12](doc/migration-v11-to-v12.md)
329330
- [Logging & Diagnostics](doc/logging.md)
330331
- [Multiple Redis Servers](doc/multipleServers.md)
331332
- [Azure Managed Identity](doc/azure-managed-identity.md)

‎doc/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040

4141
## Advanced
4242

43+
* [Migration Guide: v11 → v12](migration-v11-to-v12.md)
4344
* [Logging & Diagnostics](logging.md)
4445
* [Multiple Redis Servers](multipleServers.md)
4546
* [Azure Managed Identity](azure-managed-identity.md)

‎doc/migration-v11-to-v12.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Migration Guide: v11 to v12
2+
3+
This guide covers everything you need to know to upgrade from StackExchange.Redis.Extensions v11 to v12.
4+
5+
## Quick Summary
6+
7+
v12 is a major release with **no breaking changes to the public API**. All existing code continues to work. The upgrade brings new features, bug fixes, performance improvements, and 5 new NuGet packages for compression.
8+
9+
## Step 1: Update NuGet Packages
10+
11+
```bash
12+
# Update core packages
13+
dotnet add package StackExchange.Redis.Extensions.Core --version 12.1.0
14+
dotnet add package StackExchange.Redis.Extensions.AspNetCore --version 12.1.0
15+
16+
# Update your serializer (pick the one you use)
17+
dotnet add package StackExchange.Redis.Extensions.System.Text.Json --version 12.1.0
18+
# or: Newtonsoft, MsgPack, Protobuf, MemoryPack, ServiceStack, Utf8Json
19+
20+
# Optional: add compression (new in v12)
21+
dotnet add package StackExchange.Redis.Extensions.Compression.LZ4 --version 12.1.0
22+
```
23+
24+
## Step 2: Verify Your Configuration
25+
26+
### SyncTimeout Default Changed
27+
28+
The default `SyncTimeout` changed from **1000ms to 5000ms** to match StackExchange.Redis defaults and the XML documentation.
29+
30+
**If you were relying on the old 1000ms default** and want to keep it:
31+
```csharp
32+
config.SyncTimeout = 1000;
33+
```
34+
35+
**If you had no explicit SyncTimeout**, your app now has a more generous timeout, which should reduce `RedisTimeoutException` occurrences.
36+
37+
### Sentinel Users
38+
39+
`CommandMap.Sentinel` is **no longer applied** to the master connection. In v11, Sentinel configuration incorrectly disabled data commands (GET, SET, EVAL, SCAN) on the resolved master. This is now fixed.
40+
41+
**Action required:** If you had a workaround for this (e.g., `ExcludeCommands = null` or connection string overrides), you can remove it.
42+
43+
### StackExchange.Redis Upgraded
44+
45+
The SE.Redis dependency changed from `[2.8.*,3.0)` to `2.12.14`. This is a **pinned version** (no range).
46+
47+
**Possible impact:** If you were using SE.Redis features that changed between 2.8 and 2.12, check the [SE.Redis release notes](https://github.com/StackExchange/StackExchange.Redis/releases).
48+
49+
## Step 3: Take Advantage of New Features
50+
51+
### .NET 10 Support
52+
53+
v12 targets `netstandard2.1`, `net8.0`, `net9.0`, and `net10.0`. No action needed — the correct TFM is selected automatically.
54+
55+
### Connection Pool Resilience
56+
57+
`GetConnection()` now **skips disconnected connections** automatically. If all connections are down, the pool falls back to any connection (letting SE.Redis's internal reconnection handle recovery). A warning is logged (EventId 1003).
58+
59+
**Action:** No code changes needed. This just works.
60+
61+
### Pub/Sub Error Handling
62+
63+
Subscription handler exceptions are now **logged** (EventId 4001) instead of being silently swallowed. To see these logs, ensure `RedisConfiguration.LoggerFactory` is set (automatic with `AddStackExchangeRedisExtensions`).
64+
65+
**Action:** Check your logs for subscription handler errors that were previously hidden.
66+
67+
### AddAllAsync with Expiry — Fixed
68+
69+
In v11, `AddAllAsync` with expiry used a two-phase approach (MSET + separate EXPIREAT commands) that had a race condition. In v12, each key is set atomically with its expiry via `SET key value PX <ms>` in a batch.
70+
71+
**Action:** No code changes needed. Your data is now more reliable.
72+
73+
### New: GeoSpatial API
74+
75+
```csharp
76+
await redis.GeoAddAsync("stores", 13.361389, 38.115556, "Palermo");
77+
var nearby = await redis.GeoSearchAsync("stores", 13.361389, 38.115556,
78+
new GeoSearchCircle(200, GeoUnit.Kilometers));
79+
```
80+
81+
[Full documentation](geospatial.md)
82+
83+
### New: Redis Streams
84+
85+
```csharp
86+
await redis.StreamAddAsync("orders", "payload", orderData);
87+
var entries = await redis.StreamReadGroupAsync("orders", "processors", "worker-1", ">");
88+
await redis.StreamAcknowledgeAsync("orders", "processors", entries[0].Id.ToString());
89+
```
90+
91+
[Full documentation](streams.md)
92+
93+
### New: Hash Field Expiry (Redis 7.4+)
94+
95+
```csharp
96+
await redis.HashSetWithExpiryAsync("user:1", "session", data, TimeSpan.FromMinutes(30));
97+
```
98+
99+
[Full documentation](hash-field-expiry.md)
100+
101+
### New: VectorSet for AI/ML (Redis 8.0+)
102+
103+
```csharp
104+
await redis.VectorSetAddAsync("docs", VectorSetAddRequest.Member("doc-1", embedding));
105+
using var results = await redis.VectorSetSimilaritySearchAsync("docs",
106+
VectorSetSimilaritySearchRequest.ByVector(queryEmb) with { Count = 5 });
107+
```
108+
109+
[Full documentation](vectorset.md)
110+
111+
### New: Transparent Compression
112+
113+
```csharp
114+
services.AddStackExchangeRedisExtensions<SystemTextJsonSerializer>(config);
115+
services.AddRedisCompression<LZ4Compressor>(); // one line!
116+
```
117+
118+
**Warning:** Enabling compression on existing data makes old (uncompressed) values unreadable. Plan a migration strategy.
119+
120+
[Full documentation](compressors.md)
121+
122+
### New: Azure Managed Identity
123+
124+
```csharp
125+
config.ConfigurationOptionsAsyncHandler = async opts =>
126+
{
127+
await opts.ConfigureForAzureWithTokenCredentialAsync(new DefaultAzureCredential());
128+
return opts;
129+
};
130+
```
131+
132+
[Full documentation](azure-managed-identity.md)
133+
134+
### New: Configuration Properties
135+
136+
| Property | Description |
137+
|----------|-------------|
138+
| `ClientName` | Set Redis connection client name |
139+
| `KeepAlive` | Heartbeat interval (seconds). -1 = default, 0 = disabled |
140+
| `CertificateSelection` | TLS client certificate selection callback |
141+
| `ConfigurationOptionsAsyncHandler` | Async callback for custom ConfigurationOptions (e.g., Azure) |
142+
143+
### New: Source-Generated Logging
144+
145+
All logging now uses `[LoggerMessage]` attributes for zero-allocation performance. [See logging reference](logging.md) for EventId table.
146+
147+
## Step 4: Test
148+
149+
```bash
150+
# Run tests against your codebase
151+
dotnet test
152+
153+
# If using Moq — consider switching to NSubstitute
154+
# v12 replaced Moq internally due to the SponsorLink data collection incident
155+
```
156+
157+
## Dependency Changes
158+
159+
| Package | v11 | v12 |
160+
|---------|-----|-----|
161+
| StackExchange.Redis | [2.8.*,3.0) | 2.12.14 |
162+
| Target Frameworks | netstandard2.1, net8.0, net9.0 | + net10.0 |
163+
| Test Framework | Moq | NSubstitute |
164+
| Analyzers | Roslynator 4.12, CodeAnalysis 3.11 | Roslynator 4.15, CodeAnalysis 5.3 |
165+
166+
## New NuGet Packages (v12)
167+
168+
| Package | Description |
169+
|---------|-------------|
170+
| `StackExchange.Redis.Extensions.Compression.LZ4` | LZ4 compression (fastest) |
171+
| `StackExchange.Redis.Extensions.Compression.Snappier` | Snappy compression |
172+
| `StackExchange.Redis.Extensions.Compression.ZstdSharp` | Zstandard compression |
173+
| `StackExchange.Redis.Extensions.Compression.GZip` | GZip compression (no deps) |
174+
| `StackExchange.Redis.Extensions.Compression.Brotli` | Brotli compression (no deps) |
175+
176+
## FAQ
177+
178+
**Q: Is v12 backward compatible with v11?**
179+
A: Yes. No public API was removed or changed. All new features are additive.
180+
181+
**Q: Do I need to flush Redis when upgrading?**
182+
A: No. Existing data is fully compatible. Only enable compression if you understand the migration implications.
183+
184+
**Q: Does v12 support .NET 6 or .NET 7?**
185+
A: Not as explicit TFMs, but `netstandard2.1` covers .NET Core 3.0+ and .NET 5+.
186+
187+
**Q: I was using the `nuget` branch to trigger publish. Is that still supported?**
188+
A: No. Publishing is now manual via GitHub Actions workflow dispatch. The `nuget` branch has been deleted.

0 commit comments

Comments
 (0)