Skip to content

Commit 1b0798c

Browse files
neoscieneoscie
committed
Rename Version to SchemaVersion
Clarifies the purpose of the property for cache invalidation strategies across the codebase, documentation, and tests. Reflects that the version relates to the cache's schema rather than a general software version.
1 parent 34292ec commit 1b0798c

8 files changed

Lines changed: 53 additions & 53 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### Added
1111

12-
- `Version` property to distributed cache options for global cache invalidation.
12+
- `SchemaVersion` property to distributed cache options for global cache invalidation.
1313
- `EnvironmentPrefix` property to distributed cache options for multi-environment isolation.
1414
- `[CacheKey]` attribute for refactor-safe cache keys.
1515
- `EnableKeyEncoding` option for automatic URL encoding of optional cache keys (default: true for distributed caches).

‎Neolution.Extensions.Caching.Abstractions/DistributedCache.cs‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,9 @@ public abstract class DistributedCache<TCacheId> : IDistributedCache<TCacheId>
3030
private readonly bool enableKeyLengthValidation;
3131

3232
/// <summary>
33-
/// The cache key version for invalidation purposes.
33+
/// The cache schema version for invalidation purposes.
3434
/// </summary>
35-
private readonly int? version;
35+
private readonly int? schemaVersion;
3636

3737
/// <summary>
3838
/// The environment prefix for cache key isolation.
@@ -54,7 +54,7 @@ protected DistributedCache(IOptions<DistributedCacheOptionsBase> optionsAccessor
5454
var options = optionsAccessor.Value;
5555
this.enableKeyEncoding = options.EnableKeyEncoding;
5656
this.enableKeyLengthValidation = options.EnableKeyLengthValidation;
57-
this.version = options.Version;
57+
this.schemaVersion = options.SchemaVersion;
5858
this.environmentPrefix = options.EnvironmentPrefix;
5959
}
6060

@@ -69,9 +69,9 @@ protected DistributedCache(IOptions<DistributedCacheOptionsBase> optionsAccessor
6969
protected bool EnableKeyLengthValidation => this.enableKeyLengthValidation;
7070

7171
/// <summary>
72-
/// Gets the cache key version for invalidation purposes.
72+
/// Gets the cache schema version for invalidation purposes.
7373
/// </summary>
74-
protected int? Version => this.version;
74+
protected int? SchemaVersion => this.schemaVersion;
7575

7676
/// <summary>
7777
/// Gets the optional environment prefix for cache key isolation.
@@ -311,10 +311,10 @@ private string CreateCacheKey(TCacheId id, string? key = null)
311311

312312
var fullKey = CacheIdName;
313313

314-
// Add version if specified
315-
if (this.Version.HasValue)
314+
// Add schema version if specified
315+
if (this.SchemaVersion.HasValue)
316316
{
317-
fullKey = $"{fullKey}:v{this.Version.Value}";
317+
fullKey = $"{fullKey}:v{this.SchemaVersion.Value}";
318318
}
319319

320320
fullKey = $"{fullKey}:{cacheKey}";

‎Neolution.Extensions.Caching.Abstractions/DistributedCacheOptionsBase.cs‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,16 @@ protected DistributedCacheOptionsBase()
1414
}
1515

1616
/// <summary>
17-
/// Gets or sets the cache key version for invalidation purposes.
18-
/// If null, version is not included in the cache key.
19-
/// Changing this version will invalidate all existing cache entries.
20-
/// The version will be formatted as "v{number}" in the cache key (e.g., v1, v2).
21-
/// Default: null (no version in cache key).
17+
/// Gets or sets the cache schema version for invalidation purposes.
18+
/// If null, schema version is not included in the cache key.
19+
/// Changing this schema version will invalidate all existing cache entries.
20+
/// The schema version will be formatted as "v{number}" in the cache key (e.g., v1, v2).
21+
/// Default: null (no schema version in cache key).
2222
/// </summary>
2323
/// <example>
24-
/// options.Version = 2; // Cache key becomes: "MyCacheId:v2:UserProfile"
24+
/// options.SchemaVersion = 2; // Cache key becomes: "MyCacheId:v2:UserProfile"
2525
/// </example>
26-
public int? Version { get; set; }
26+
public int? SchemaVersion { get; set; }
2727

2828
/// <summary>
2929
/// Gets or sets the optional environment prefix for cache key isolation.

‎Neolution.Extensions.Caching.UnitTests/CacheKeyVersioningTests.cs‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,15 @@
1717
public class CacheKeyVersioningTests
1818
{
1919
/// <summary>
20-
/// Tests backward compatibility - cache key without version by default
20+
/// Tests backward compatibility - cache key without schema version by default
2121
/// </summary>
2222
[Fact]
2323
public void MessagePackCacheKeyWithoutVersionByDefault()
2424
{
2525
// Arrange
2626
var services = new ServiceCollection();
2727
services.AddDistributedMemoryCache();
28-
services.AddSerializedDistributedCache(); // No options - should not include version
28+
services.AddSerializedDistributedCache(); // No options - should not include schema version
2929

3030
using var serviceProvider = services.BuildServiceProvider();
3131
var cache = serviceProvider.GetRequiredService<IDistributedCache<TestCacheId>>();
@@ -39,7 +39,7 @@ public void MessagePackCacheKeyWithoutVersionByDefault()
3939
}
4040

4141
/// <summary>
42-
/// Tests if cache key includes version when configured
42+
/// Tests if cache key includes schema version when configured
4343
/// </summary>
4444
[Fact]
4545
public void MessagePackCacheKeyIncludesConfiguredVersion()
@@ -49,7 +49,7 @@ public void MessagePackCacheKeyIncludesConfiguredVersion()
4949
services.AddDistributedMemoryCache();
5050
services.AddSerializedDistributedCache(options =>
5151
{
52-
options.Version = 1;
52+
options.SchemaVersion = 1;
5353
});
5454

5555
using var serviceProvider = services.BuildServiceProvider();
@@ -59,12 +59,12 @@ public void MessagePackCacheKeyIncludesConfiguredVersion()
5959
// Act
6060
cache.Set(TestCacheId.Foobar, testValue);
6161

62-
// Assert - Verify we can retrieve the value (version is included in key)
62+
// Assert - Verify we can retrieve the value (schema version is included in key)
6363
cache.Get<string>(TestCacheId.Foobar).ShouldBe(testValue);
6464
}
6565

6666
/// <summary>
67-
/// Tests if cache key includes custom version
67+
/// Tests if cache key includes custom schema version
6868
/// </summary>
6969
[Fact]
7070
public void MessagePackCacheKeyIncludesCustomVersion()
@@ -74,7 +74,7 @@ public void MessagePackCacheKeyIncludesCustomVersion()
7474
services.AddDistributedMemoryCache();
7575
services.AddSerializedDistributedCache(options =>
7676
{
77-
options.Version = 2;
77+
options.SchemaVersion = 2;
7878
});
7979

8080
using var serviceProvider = services.BuildServiceProvider();
@@ -89,19 +89,19 @@ public void MessagePackCacheKeyIncludesCustomVersion()
8989
}
9090

9191
/// <summary>
92-
/// Tests if different versions produce different cache keys
92+
/// Tests if different schema versions produce different cache keys
9393
/// </summary>
9494
[Fact]
9595
public void DifferentVersionsProduceDifferentKeys()
9696
{
97-
// Arrange - Create two service providers with different versions
97+
// Arrange - Create two service providers with different schema versions
9898
var servicesV1 = new ServiceCollection();
9999
servicesV1.AddDistributedMemoryCache();
100-
servicesV1.AddSerializedDistributedCache(options => options.Version = 1);
100+
servicesV1.AddSerializedDistributedCache(options => options.SchemaVersion = 1);
101101

102102
var servicesV2 = new ServiceCollection();
103103
servicesV2.AddDistributedMemoryCache();
104-
servicesV2.AddSerializedDistributedCache(options => options.Version = 2);
104+
servicesV2.AddSerializedDistributedCache(options => options.SchemaVersion = 2);
105105

106106
using var providerV1 = servicesV1.BuildServiceProvider();
107107
using var providerV2 = servicesV2.BuildServiceProvider();
@@ -148,7 +148,7 @@ public void MessagePackCacheKeyIncludesEnvironmentPrefix()
148148
}
149149

150150
/// <summary>
151-
/// Tests if cache key includes both version and environment prefix
151+
/// Tests if cache key includes both schema version and environment prefix
152152
/// </summary>
153153
[Fact]
154154
public void MessagePackCacheKeyIncludesBothVersionAndEnvironment()
@@ -158,7 +158,7 @@ public void MessagePackCacheKeyIncludesBothVersionAndEnvironment()
158158
services.AddDistributedMemoryCache();
159159
services.AddSerializedDistributedCache(options =>
160160
{
161-
options.Version = 2;
161+
options.SchemaVersion = 2;
162162
options.EnvironmentPrefix = "prod";
163163
});
164164

@@ -184,7 +184,7 @@ public void MessagePackCacheKeyWithOptionalKeyAndVersion()
184184
services.AddDistributedMemoryCache();
185185
services.AddSerializedDistributedCache(options =>
186186
{
187-
options.Version = 2;
187+
options.SchemaVersion = 2;
188188
options.EnvironmentPrefix = "staging";
189189
});
190190

@@ -233,7 +233,7 @@ public void NullOrEmptyEnvironmentPrefixIsHandledCorrectly(string? environmentPr
233233
}
234234

235235
/// <summary>
236-
/// Tests if RedisHybridCache key includes custom version
236+
/// Tests if RedisHybridCache key includes custom schema version
237237
/// </summary>
238238
[Fact(Skip = "Requires Redis connection - integration test")]
239239
public void RedisHybridCacheKeyIncludesCustomVersion()
@@ -242,7 +242,7 @@ public void RedisHybridCacheKeyIncludesCustomVersion()
242242
var services = new ServiceCollection();
243243
services.AddRedisHybridCache("localhost:6379", options =>
244244
{
245-
options.Version = 2;
245+
options.SchemaVersion = 2;
246246
options.EnvironmentPrefix = "test";
247247
});
248248

‎Neolution.Extensions.Caching.UnitTests/RedisHybridCacheOptionsTests.cs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ public void ServiceCollection_ConfiguresOptions_Correctly()
5151
services.AddRedisHybridCache("localhost:6379", options =>
5252
{
5353
options.EnableCompression = true;
54-
options.Version = 2;
54+
options.SchemaVersion = 2;
5555
options.EnvironmentPrefix = "test";
5656
options.EnableKeyEncoding = false;
5757
options.EnableKeyLengthValidation = false;
@@ -63,7 +63,7 @@ public void ServiceCollection_ConfiguresOptions_Correctly()
6363

6464
// Assert
6565
options.Value.EnableCompression.ShouldBeTrue();
66-
options.Value.Version.ShouldBe(2);
66+
options.Value.SchemaVersion.ShouldBe(2);
6767
options.Value.EnvironmentPrefix.ShouldBe("test");
6868
options.Value.EnableKeyEncoding.ShouldBeFalse();
6969
options.Value.EnableKeyLengthValidation.ShouldBeFalse();
@@ -85,7 +85,7 @@ public void ServiceCollection_DefaultConfiguration_UsesDefaultValues()
8585

8686
// Assert
8787
options.Value.EnableCompression.ShouldBeFalse(); // Default is false
88-
options.Value.Version.ShouldBeNull();
88+
options.Value.SchemaVersion.ShouldBeNull();
8989
options.Value.EnvironmentPrefix.ShouldBeNull();
9090
options.Value.EnableKeyEncoding.ShouldBeTrue(); // Default is true
9191
options.Value.EnableKeyLengthValidation.ShouldBeTrue(); // Default is true
@@ -100,14 +100,14 @@ public void RedisHybridCacheOptions_InheritsFromBase()
100100
// Arrange & Act
101101
var options = new RedisHybridCacheOptions
102102
{
103-
Version = 5,
103+
SchemaVersion = 5,
104104
EnvironmentPrefix = "prod",
105105
EnableKeyEncoding = false,
106106
EnableKeyLengthValidation = false,
107107
};
108108

109109
// Assert
110-
options.Version.ShouldBe(5);
110+
options.SchemaVersion.ShouldBe(5);
111111
options.EnvironmentPrefix.ShouldBe("prod");
112112
options.EnableKeyEncoding.ShouldBeFalse();
113113
options.EnableKeyLengthValidation.ShouldBeFalse();

‎Neolution.Extensions.Caching.UnitTests/RedisHybridCacheTests.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ private IServiceCollection CreateServiceCollection()
129129
{
130130
// Example: Enable compression if Redis bandwidth is a concern
131131
options.EnableCompression = false; // Default is false for CPU optimization
132-
options.Version = 1;
132+
options.SchemaVersion = 1;
133133
});
134134

135135
return services;

‎README.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -228,13 +228,13 @@ public class MyDistributedCache : MessagePackDistributedCache<MyCacheId>
228228

229229
#### Cache Key Versioning and Environment Isolation
230230

231-
**Version Management:**
232-
The `Version` property (integer) allows you to invalidate all cached data when you need to force a cache refresh (e.g., after schema changes or bug fixes).
231+
**Schema Version Management:**
232+
The `SchemaVersion` property (integer) allows you to invalidate all cached data when you need to force a cache refresh (e.g., after schema changes or bug fixes).
233233

234234
```csharp
235235
services.AddSerializedDistributedCache(options =>
236236
{
237-
options.Version = 2;
237+
options.SchemaVersion = 2;
238238
});
239239
```
240240

@@ -303,9 +303,9 @@ services.AddSerializedDistributedCache(options =>
303303
// (requires decorating your classes with [MessagePackObject])
304304
options.RequireMessagePackObjectAnnotation = true;
305305

306-
// Cache key version for invalidation (default: null - not included in key)
307-
// Version is formatted as "v{number}" in cache key (e.g., v1, v2)
308-
options.Version = 1;
306+
// Cache schema version for invalidation (default: null - not included in key)
307+
// Schema version is formatted as "v{number}" in cache key (e.g., v1, v2)
308+
options.SchemaVersion = 1;
309309

310310
// Optional environment prefix for cache isolation (default: null - not included in key)
311311
options.EnvironmentPrefix = "prod";
@@ -327,9 +327,9 @@ services.AddRedisHybridCache("localhost:6379", options =>
327327
// Set to true when bandwidth is more important than CPU usage
328328
options.EnableCompression = false;
329329

330-
// Cache key version for invalidation (default: null - not included in key)
331-
// Version is formatted as "v{number}" in cache key (e.g., v1, v2)
332-
options.Version = 1;
330+
// Cache schema version for invalidation (default: null - not included in key)
331+
// Schema version is formatted as "v{number}" in cache key (e.g., v1, v2)
332+
options.SchemaVersion = 1;
333333

334334
// Optional environment prefix for cache isolation (default: null - not included in key)
335335
options.EnvironmentPrefix = "prod";

‎docs/MIGRATION_GUIDE_V3.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -141,19 +141,19 @@ services.AddStackExchangeRedisCache(options => { ... });
141141

142142
### Cache Key Versioning
143143

144-
Invalidate all cache entries by incrementing version:
144+
Invalidate all cache entries by incrementing schema version:
145145

146146
```csharp
147147
services.AddSerializedDistributedCache(options =>
148148
{
149-
options.Version = 1; // Keys: "MyCacheId:v1:UserProfile"
149+
options.SchemaVersion = 1; // Keys: "MyCacheId:v1:UserProfile"
150150
});
151151

152152
// Later: increment to invalidate all entries
153-
options.Version = 2; // Keys: "MyCacheId:v2:UserProfile"
153+
options.SchemaVersion = 2; // Keys: "MyCacheId:v2:UserProfile"
154154
```
155155

156-
**Default**: `null` (no version) - maintains v2.x compatibility.
156+
**Default**: `null` (no schema version) - maintains v2.x compatibility.
157157

158158
### Environment Isolation
159159

@@ -189,7 +189,7 @@ public enum MyCacheId
189189
### Will my existing cache entries still work?
190190

191191
**Yes**, if you:
192-
- Don't set `Version` (default)
192+
- Don't set `SchemaVersion` (default)
193193
- Don't set `EnvironmentPrefix` (default)
194194
- Keep `EnableKeyEncoding = true` (default)
195195

@@ -211,6 +211,6 @@ v3.0 improves configuration and error handling for distributed cache:
211211
- Fluent API support
212212
- Refactor-safe cache keys
213213

214-
New features are opt-in. Existing cache entries remain compatible with default settings (no `Version`, no `EnvironmentPrefix`, `EnableKeyEncoding = true`).
214+
New features are opt-in. Existing cache entries remain compatible with default settings (no `SchemaVersion`, no `EnvironmentPrefix`, `EnableKeyEncoding = true`).
215215

216216
**Need Help?** Open an issue on GitHub.

0 commit comments

Comments
 (0)