fix(cache): refuse configuration written under a key 2.0 removed, and document the 1.x to 2.0 upgrade

[cosmin-staicu]

Summary

The first consumer to move onto 2.0.0-preview.2 (Cloud-RPA #27279) nearly shipped with its L1 cap silently gone: the binder ignores a PrimaryMaxExpiration it can no longer place, and nothing in the build, at startup or in the logs said so. This makes the library refuse the four keys 2.0 removed, corrects the changelog where that upgrade found it wrong, and adds the migration guide the PR author had to write themselves.

Changes

• Removed config keys throw at registration. AddMemory(sectionName), AddInMemoryRedis(sectionName) and both section-bound AddRedisConnection overloads fail with InvalidOperationException when PrimaryMaxExpiration, PrimaryMaxExpirationDisconnected, UsePrimaryOnlyWhenDisconnected or ThreadPoolSocketManager is present under the section, naming the section, every offending key and its replacement. Runs whether or not the provider is enabled. Code-only overloads are not checked: the property no longer exists to assign. The existing leftover-ISerializerProxy<RedisValue> guard now runs on the same terms, before the Enabled switch, so a disabled test profile reports it too. No public API change.
• Changelog floors corrected. The entry said Microsoft.Extensions 10.0.11 and omitted StackExchange.Redis; it is now a table from Directory.Packages.props (SE.Redis 3.1.13 → 3.1.31, Microsoft.Extensions 10.0.10 → 10.0.12, Logging.Abstractions 10.0.11 → 10.0.12, OpenTelemetry 1.17.0 → 1.18.0).
• Changelog compat entry corrected. "Call sites are unchanged" holds for production code only. Moq inspects the Setup/Verify expression and refuses a static call, so a short form inside one throws NotSupportedException at test run time. The entry now says so and shows the re-targeting with an any-policy matcher. NSubstitute is unaffected and the entry says that too.
• New docs/upgrade-to-2.0.md, linked from the docs index and README. Opens with how each break shows itself (three do not show at compile time), then covers floors, config keys, the serializer seam and IMemorySerializerProxy, the nullable-expiration branch and the throw on zero or past values, mocking, hand-written implementations, the clock, renamed types, the binary-compat position for integrations built against 1.x, and rollback.
• settings.md gains a one-line pointer above each of the three affected sections.

Test plan

• Unit tests added/updated — RemovedConfigurationKeysTests: each renamed key on both multilayer sections, the socket-manager key on both connection overloads, disabled provider still refused, all offending keys in one message, renamed keys bind cleanly, unrelated sections untouched, code-only overload not guarded.
• Full suite passes locally on net10.0 (1734 passed, 0 failed, 12 skipped); the new class also passes on net8.0.
• CHANGELOG.md updated

Linked issues

Prompted by UiPath/Cloud-RPA#27279.

Contributor declaration

• I signed off my commits per the DCO (git commit -s).
• I am contributing on behalf of my employer, or in the course of employment / using employer resources.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The migration documentation contains incorrect compatibility, NSubstitute, and dependency-floor claims.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds safeguards and migration guidance for upgrading from 1.x to 2.0.

Changes:

• Rejects removed configuration keys during registration.
• Adds comprehensive upgrade documentation and navigation links.
• Corrects dependency and mocking guidance in the changelog.

File summaries

File	Description
RemovedConfigurationKeysTests.cs	Tests removed-key validation.
RemovedConfigurationKeys.cs	Detects removed configuration keys.
RedisCollectionExtensions.cs	Validates Redis connection configuration.
InMemoryRedisCollectionExtensions.cs	Validates multilayer Redis configuration.
InMemoryCollectionExtensions.cs	Validates memory configuration.
README.md	Links the upgrade guide.
docs/upgrade-to-2.0.md	Documents 2.0 migration steps.
docs/reference/settings.md	Warns about removed settings.
docs/index.md	Adds upgrade-guide navigation.
CHANGELOG.md	Revises migration and dependency notes.

Review details

Suppressed comments (2)

docs/upgrade-to-2.0.md:202

• This compatibility statement is too broad for an upgrade guide: 2.0 already removes methods and changes constructors/interfaces, so a 1.3 binary that references those contracts can fail now with MissingMethodException or TypeLoadException. Only integrations verified to use the listed unchanged seams can be described as binary-compatible.

A package compiled against `UiPath.Caching` 1.3.0 loads against 2.0: .NET accepts a higher assembly
version than the one referenced, and the seams such packages reach for, `ICachingTelemetryProvider`,
`ITelemetryOperation`, `ICachingBuilder`, `IRedisProfiler` and the `RedisConnectionOptions` members
they read, have no binary change since 1.3.0. That is a fact about 2.0.0, not a promise; a later
release that moves one of those members would fail at runtime with `MissingMethodException` or

CHANGELOG.md:372

• This is not a consumer dependency floor. UiPath.Caching.OpenTelemetry.csproj has no OpenTelemetry package references, and every OpenTelemetry PackageReference in this repository is under samples; listing the central sample pins in a table introduced as requirements for consumer restore can cause unnecessary upgrades.

  | `OpenTelemetry.*` (`UiPath.Caching.OpenTelemetry`) | 1.17.0 | 1.18.0 (`Instrumentation.StackExchangeRedis` 1.18.0-beta.1) |

• Files reviewed: 10/10 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

The migration guide contains several inaccurate guarantees about serializer detection, expiration validation, and no-TTL read results.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The migration guide contains two inaccurate guarantees, and the PR description still incorrectly includes NSubstitute in the Moq-specific failure.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The relocated serializer check can miss legacy registrations added by completion callbacks.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Null-valued removed keys can bypass the new validation and silently retain changed defaults.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The migration guide contains several inaccurate or contradictory upgrade instructions that should be corrected before release.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

docs/upgrade-to-2.0.md:44

• ThreadPoolSocketManager was an obsolete no-op, not an alias; the table itself correctly says there is no replacement. Distinguish it from the three renamed multilayer aliases so the migration history is accurate.

Four options keys were `[Obsolete]` aliases in 1.x and are gone in 2.0. The configuration binder
ignores a key it cannot place, so a leftover alias does not fail the build or write a log line; the
value falls back to its default. For `PrimaryMaxExpiration` that means the L1 cap disappears.

docs/upgrade-to-2.0.md:178

• Interface implementations cannot override default interface methods, and an ordinary public method matching a removed member can remain without a compile error. Only an explicit interface implementation becomes invalid when that member leaves the interface, so the current instruction tells consumers to remove something that may not need removal and uses a C# construct that was never valid here.

- **The compat and sync forwarders are gone from the interfaces**, so an implementation no longer
  inherits them and cannot have overridden them by accident. Remove any override.

• Files reviewed: 12/12 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The implementation, tests, and migration documentation consistently cover the intended failure modes.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud