What's Changed

• chore(deps): bump uuid and mermaid in /docs by @dependabot[bot] in #513
• fix: correct disposal ordering to prevent ObjectDisposedException during shutdown by @niemyjski in #519
• Bump Microsoft.SourceLink.GitHub from 10.0.203 to 10.0.300 by @dependabot[bot] in #520
• perf: change IMessage.Data from byte[] to ReadOnlyMemory by @niemyjski in #530
• chore(deps-dev): bump dompurify from 3.4.0 to 3.4.11 in /docs by @dependabot[bot] in #529
• chore(deps-dev): bump markdown-it from 14.1.0 to 14.2.0 in /docs by @dependabot[bot] in #521
• chore(deps): bump esbuild and vite in /docs by @dependabot[bot] in #531

Full Changelog: v13.0.1...v13.0.2

v13.0.1

This is a major release with 368 files changed across the entire Foundatio codebase. Here are the themes that define v13:

• Reliability & Correctness: Dozens of race conditions, deadlocks, and disposal issues have been hunted down and fixed across queues, messaging, caching, and timers. Cancellation tokens are now properly linked to disposal for clean shutdown, and poison messages are gracefully handled instead of crashing consumers.
• Consistent Error Handling: Every subsystem now has its own exception type (QueueException, MessageBusException, SerializerException) so consumers get predictable, catchable errors regardless of the underlying provider. These feature-specific exceptions are automatically excluded from resilience policy retries.
• API Normalization: Cache TTL behavior, serializer validation, and expiration return values have been normalized across all implementations -- no more provider-specific quirks.
• Null Safety: A comprehensive NRT audit eliminated null! suppressions across the codebase, fixing latent null bugs and adding proper nullable attributes. The API surface now accurately communicates nullability contracts.
• Modern .NET: Dropped netstandard2.0 in favor of net8.0 + net10.0. Replaced DeepCloner with the actively-maintained FastCloner. ScheduledTimer now uses TimeProvider for testability.
• Documentation Overhaul: Foundatio now has a dedicated documentation site with comprehensive guides, source code links, and real-world examples for every subsystem.

Documentation Site

Foundatio v13 ships with a brand-new documentation site covering every subsystem with guides, configuration examples, and direct source code links. Key additions:

• New docs site built with VitePress (061bd763)
• Source code links added to every subsystem: caching (8f6d37c1), queues (bb9af714), messaging (59cc2f57), locks (10241465), jobs (7df97b13), serialization (8819ba09), storage (bf2eb1b9)
• Comprehensive hybrid caching documentation with RedisHybridCacheClient examples (2fc124df, 0791b496)
• Cache stampede protection patterns (a6cfd75c)
• Delayed message delivery and distributed tracing guide (da2c6162)
• RabbitMQ delayed delivery and delayed-exchange plugin deprecation notes (#490)
• Redis read routing and replica support guide (6860a0c1)
• Redis replication lag risk documentation (98323dbe)
• Queue names vs. queue IDs explainer (456389ed)
• Cancellation token behavior clarification (70a63d12)
• Cache expiration differences across implementations (1853daee)
• Enhanced XML doc comments across all core interfaces (7fdad859)
• Updated job samples (3e003a86) and added sample projects + benchmarks to the solution (160dd74f)
• Added Foundatio.Mediator links to README and docs (b8f0eba1)

Breaking Changes

• Dropped netstandard2.0 target: Foundatio now targets net8.0 and net10.0 only. Consumers on .NET Framework or older runtimes must stay on v12.x. by @niemyjski in 4c6aefed, a1089422
• Normalized ICacheClient.IncrementAsync TTL behavior: Increment operations now consistently apply the TTL parameter across all implementations. Removed ListRemoveAsync ExpiresIn argument to align with all other Remove methods. by @niemyjski in #434
• Normalized ICacheClient return values for expiration: GetExpirationAsync returns consistent values across implementations. by @niemyjski in #432
• Normalized ISerializer argument validation: All serializer implementations now consistently validate arguments and throw ArgumentException / ArgumentNullException. by @niemyjski in #440
• Added QueueException: Queue operations now throw QueueException for queue-specific errors. Guard added against reusing behavior instances. by @niemyjski in #448
• MessageBusId and QueueId changed to init-only properties: These properties can no longer be set after construction. by @niemyjski in b73bf128
• Removed obsolete Set/SetAdd/SetRemove methods from cache extensions: These were renamed to List* in v9.0.0 (Nov 2019) and have been [Obsolete] for 6+ years. by @niemyjski in 150beed5
• Removed obsolete single-parameter GetFileStreamAsync overload: Deprecated in v10.7.0 (Jan 2024) when StreamMode was added. Use the overload accepting StreamMode and CancellationToken. by @niemyjski in 037baae5
• Comprehensive NRT (Nullable Reference Types) null-safety audit: Eliminated null! suppressions, fixed latent null bugs, and added nullable attributes across the codebase. Return types and parameters may have changed nullability. by @niemyjski in #484, #498

• Make AcquireAsync throw on failure to fix the silent-null lock footgun by @ejsmith in #508
• Default JobResult.Message to empty string by @ejsmith in #507
• fix: abandon queue entry when GetQueueEntryLockAsync throws by @niemyjski in #509

Added

• Upgrade to xUnit v3 with Foundatio.Xunit.v3: Test infrastructure upgraded to xUnit v3. New Foundatio.Xunit.v3 package with retry test attributes (RetryFactAttribute, RetryTheoryAttribute) for automatic retry of flaky tests. The existing Foundatio.Xunit package continues to support xUnit v2. by @niemyjski in #431
• Memory-limited in-memory cache: InMemoryCacheClient now supports MaxMemorySize with per-entry size limits and intelligent eviction when memory budgets are exceeded. by @niemyjski, @copilot in #400
• Poison message handling for queues and message bus: Deserialization failures in queues and the message bus are now gracefully handled as poison messages instead of crashing consumers. Dead letter logging improved. by @niemyjski in #455
• SerializerException: New exception type for serialization-specific errors, enabling targeted error handling. by @niemyjski in b314a052
• MessageBusException: Consistent error handling for messaging operations with improved delayed message delivery. by @niemyjski in #443
• QueueDeleted event on IQueue<T>: Consumers can now subscribe to queue deletion notifications. by @niemyjski in #447
• OpenTelemetry error recording: Added Activity.AddException polyfill for recording exceptions in distributed traces across all target frameworks. by @niemyjski in #446
• Synchronous IResiliencePolicy methods: Added sync overloads (Execute, ExecuteAsync) alongside existing async methods. by @ejsmith in #445
• Feature-specific exceptions excluded from resilience policy retries: QueueException, MessageBusException, StorageException, SerializerException, and CacheException are no longer retried by resilience policies. by @niemyjski in 318fa1a0
• GetAllExpirationsAsync and SetAllExpirationsAsync on ICacheClient: Bulk expiration read/write support with improved test coverage. by @niemyjski in #426
• Option to dispose underlying scoped implementations: Scoped cache/queue/etc. wrappers can now optionally dispose their underlying instances. by @niemyjski in #412
• Job status description: JobStatus now supports a Description property. by @ejsmith in fdcc1442
• Enforce 5ms minimum expiration across all cache implementations: Prevents extremely short TTLs that cause race conditions. by @niemyjski in #463
• net10.0 target framework: Added .NET 10 support alongside .NET 8. by @niemyjski in 4c6aefed, a1089422
• Delayed message delivery: Message bus now supports delayed/scheduled message publishing. by @niemyjski in #443
• TestCancellationToken in test harness: Added to TestLoggerBase and TestWithLoggingBase (v2 and v3) for better test cancellation support. by @niemyjski in c37508ef, d24afcb7
• Scoped cache constructor overload: New ScopedCacheClient constructor that defaults shouldDispose to false to prevent accidental disposal. by @niemyjski in f28463b9

• LogState LogError nullable exception + matching exception overloads for other log levels by @ejsmith in #506

Changed

• Replaced DeepCloner with FastCloner: Switched deep cloning implementation from DeepCloner to FastCloner (v3.5.3) for better performance and active maintenance. Huge thanks to @lofcz (Matej Stagl) for contributing FastCloner and helping integrate it into Foundatio -- this was a major effort that touched the deep internals of the cloning infrastructure. by @niemyjski, @lofcz in #469, #485
• HybridCacheClient subscription moved out of constructor: Uses AsyncLazy to avoid sync-over-async in constructors. by @niemyjski in 7050c523
• Improved HybridCacheClient consistency and invalidation: Fixed consistency issues, optimized invalidation, and improved double comparison logic. by @niemyjski in #433
• ScheduledTimer uses TimeProvider: Scheduled jobs now use TimeProvider for delays, improving testability. by @niemyjski in 77727cdf
• Two-phase dispose for MessageBus subscription lifecycle: More reliable shutdown behavior. by @niemyjski in #492
• Cancellation tokens linked to disposal: MessageBus and Queue now link cancellation tokens to disposal for prompt shutdown. by @niemyjski in c06fcdef
• Improved disposal logic consistency: Disposal guards, IsDisposed consolidation, and proper CancellationTokenSource disposal across all base classes. by @niemyjski in 49eec83a, be62be11
• Enhanced MessageOptions: Added XML documentation and support for custom properties. by @niemyjski in 692c644d
• Refactored DataDictionary: Uses TryGetValue, nullable returns, and switch expressions. by @niemyjski in 2b423514
• Comprehensive XML documentation: Enhanced docs across ICacheClient, IQueue, IMessageBus, IFileStorage, ILockProvider, and IJob interfaces. by @niemyjski in 7fdad859
• Lock providers accept TimeProvider and IResiliencePolicyProvider: CacheLockProvider and ThrottlingLockProvider now receive dependencies via constructor injection for improved testability and resilience. by @niemyjski in e3e815c4
• Improved async timeout handling: Refactored AsyncCountdownEvent to use WaitAsync consistently; QueueTestBase now implements IAsyncDisposable. by @niemyjski in d78f220d
• Updated dependencies: Microsoft.Extensions packages, BenchmarkDotNet, Aspire, Polly, and others updated to latest versions. by @niemyjski, @ejsmith

Fixed

• Race condition in InMemoryQueue.AbandonAsync: Fixed flaky RunUntilEmptyAsync caused by abandon race. by @niemyjski in #470
• InvalidCastException in InMemoryCacheClient.GetAsync<object>(): Fixed crash for non-IConvertible types. by @copilot in #468
• Race condition in ScheduledTimer: Fixed timing issue in scheduled timer callbacks. by @niemyjski in 65e3116a
• Race condition in HybridCacheClient invalidation tests: Fixed flaky test caused by invalidation timing. by @niemyjski in 5acce8bc
• InMemoryQueue retry entry isolation: Each retry attempt now creates a fresh queue entry, preventing state leakage between attempts. by @niemyjski in #454
• Sync-over-async deadlock in MessageBusBase: Fixed deadlock in CancellationToken.Register callback. by @niemyjski in fdc47d22
• ThrottlingLockProvider period boundary issues: Hardened spin-wait with String.Equals, iteration cap, and improved diagnostics. by @niemyjski in d619b7e3, bbca0e39
• IndexOutOfRangeException in FastCloner GenerateProcessSetMethod: Fixed array bounds issue in deep cloning. by @niemyjski in f1992944
• ArgumentOutOfRangeException in DoMaintenance: Prevented negative timespan in queue maintenance scheduling. by @niemyjski in ee00d141
• DateTime overflow in cache maintenance: Added SafeAdd extension methods to prevent overflow exceptions when adding to DateTime.MaxValue / DateTime.MinValue. by @niemyjski in 6df04edf
• Zero or negative expiration in ReplaceIfEqualAsync: Now correctly removes the key instead of setting an invalid TTL. by @niemyjski in ffc8d352
• Null/empty connection strings in ConnectionStringParser: Now handled gracefully instead of throwing. by @niemyjski in df7c6898
• FaultInjectingSerializer missing ITextSerializer: Now implements ITextSerializer to prevent unexpected Base64 encoding in tests. by @niemyjski in 87fdf6e3
• Flaky metrics test: Fixed timer resolution race with DateTime.UtcNow. by @niemyjski in #488
• Queue metrics when disposed: Returns empty metrics instead of throwing. by @lofcz in 4744fc1b

New Contributors

Huge shoutout to @lofcz (Matej Stagl) for his outstanding contributions to this release! Matej is the author of FastCloner, which replaces DeepCloner as Foundatio's deep cloning engine. He contributed the integration PRs (#469, #485), kept FastCloner in sync with upstream improvements, and fixed a queue metrics edge case -- all while being incredibly responsive and collaborative. Thank you, Matej!

• @niemyjski
• @ejsmith
• @lofcz (Matej Stagl) -- FastCloner author and integration contributor
• @copilot

---

Migration Guide

Target Framework Changes

v13 drops netstandard2.0 and targets net8.0;net10.0. If you are on .NET Framework, you must stay on Foundatio v12.x.

Cache API Changes

• IncrementAsync TTL: The TTL parameter now behaves consistently across all cache implementations. Review any code that relied on implementation-specific TTL behavior during increment operations.
• ListRemoveAsync: The ExpiresIn parameter has been removed. If you were passing an expiration to ListRemoveAsync, remove that argument.
• GetExpirationAsync: Return values are now normalized. Test any code that compared expiration values across implementations.
• Minimum expiration: All cache implementations now enforce a 5ms minimum expiration. Values below 5ms will be clamped.

Serializer Changes

• All ISerializer implementations now validate arguments consistently. If your code was passing null to serializer methods, you will now get ArgumentNullException.
• SerializerException is now thrown for serialization-specific failures. Update any catch blocks that were catching general exceptions from serializers.

Queue Changes

• Queue operations now throw QueueException for queue-specific errors. Update exception handling accordingly.
• Queue behavior instances (e.g., IQueueBehavior<T>) can no longer be reused across multiple queue instances.
• Poison messages (deserialization failures) are now routed to dead letters instead of crashing consumers. Review dead letter handling if you rely on immediate failure notification.

Messaging Changes

• MessageBusException is now thrown for messaging errors. Update exception handling.
• MessageBusId and QueueId are now init-only. Set them during construction only.

Nullable Reference Types

• Many APIs have updated nullability annotations. If you have NRT enabled, expect new warnings that reflect the corrected nullability contracts. These are accurate -- the previous annotations were incorrect.

Removed APIs

• CacheClientExtensions.Set / SetAdd / SetRemove (obsolete overloads) -- These were renamed to ListAdd / ListRemove back in v9.0.0 (November 2019) to avoid confusion between "set" as a verb and "set" as a data structure. The old names have been marked [Obsolete] for over 6 years across 4 major versions. Use the List* equivalents.
• IFileStorage.GetFileStreamAsync(string path) (single-parameter overload) -- Deprecated in v10.7.0 (January 2024) when write-capable file streams were added in #290, which introduced an overload accepting StreamMode and CancellationToken. The single-parameter version has been [Obsolete] for 2+ years. Use GetFileStreamAsync(path, StreamMode.Read, cancellationToken) instead.

Full Changelog: v12.0.0...v13.0.1

v13.0.0

This is a major release with 368 files changed across the entire Foundatio codebase. Here are the themes that define v13:

• Reliability & Correctness: Dozens of race conditions, deadlocks, and disposal issues have been hunted down and fixed across queues, messaging, caching, and timers. Cancellation tokens are now properly linked to disposal for clean shutdown, and poison messages are gracefully handled instead of crashing consumers.
• Consistent Error Handling: Every subsystem now has its own exception type (QueueException, MessageBusException, SerializerException) so consumers get predictable, catchable errors regardless of the underlying provider. These feature-specific exceptions are automatically excluded from resilience policy retries.
• API Normalization: Cache TTL behavior, serializer validation, and expiration return values have been normalized across all implementations -- no more provider-specific quirks.
• Null Safety: A comprehensive NRT audit eliminated null! suppressions across the codebase, fixing latent null bugs and adding proper nullable attributes. The API surface now accurately communicates nullability contracts.
• Modern .NET: Dropped netstandard2.0 in favor of net8.0 + net10.0. Replaced DeepCloner with the actively-maintained FastCloner. ScheduledTimer now uses TimeProvider for testability.
• Documentation Overhaul: Foundatio now has a dedicated documentation site with comprehensive guides, source code links, and real-world examples for every subsystem.

Documentation Site

Foundatio v13 ships with a brand-new documentation site covering every subsystem with guides, configuration examples, and direct source code links. Key additions:

• New docs site built with VitePress (061bd763)
• Source code links added to every subsystem: caching (8f6d37c1), queues (bb9af714), messaging (59cc2f57), locks (10241465), jobs (7df97b13), serialization (8819ba09), storage (bf2eb1b9)
• Comprehensive hybrid caching documentation with RedisHybridCacheClient examples (2fc124df, 0791b496)
• Cache stampede protection patterns (a6cfd75c)
• Delayed message delivery and distributed tracing guide (da2c6162)
• RabbitMQ delayed delivery and delayed-exchange plugin deprecation notes (#490)
• Redis read routing and replica support guide (6860a0c1)
• Redis replication lag risk documentation (98323dbe)
• Queue names vs. queue IDs explainer (456389ed)
• Cancellation token behavior clarification (70a63d12)
• Cache expiration differences across implementations (1853daee)
• Enhanced XML doc comments across all core interfaces (7fdad859)
• Updated job samples (3e003a86) and added sample projects + benchmarks to the solution (160dd74f)
• Added Foundatio.Mediator links to README and docs (b8f0eba1)

Breaking Changes

• Dropped netstandard2.0 target: Foundatio now targets net8.0 and net10.0 only. Consumers on .NET Framework or older runtimes must stay on v12.x. by @niemyjski in 4c6aefed, a1089422
• Normalized ICacheClient.IncrementAsync TTL behavior: Increment operations now consistently apply the TTL parameter across all implementations. Removed ListRemoveAsync ExpiresIn argument to align with all other Remove methods. by @niemyjski in #434
• Normalized ICacheClient return values for expiration: GetExpirationAsync returns consistent values across implementations. by @niemyjski in #432
• Normalized ISerializer argument validation: All serializer implementations now consistently validate arguments and throw ArgumentException / ArgumentNullException. by @niemyjski in #440
• Added QueueException: Queue operations now throw QueueException for queue-specific errors. Guard added against reusing behavior instances. by @niemyjski in #448
• MessageBusId and QueueId changed to init-only properties: These properties can no longer be set after construction. by @niemyjski in b73bf128
• Removed obsolete Set/SetAdd/SetRemove methods from cache extensions: These were renamed to List* in v9.0.0 (Nov 2019) and have been [Obsolete] for 6+ years. by @niemyjski in 150beed5
• Removed obsolete single-parameter GetFileStreamAsync overload: Deprecated in v10.7.0 (Jan 2024) when StreamMode was added. Use the overload accepting StreamMode and CancellationToken. by @niemyjski in 037baae5
• Comprehensive NRT (Nullable Reference Types) null-safety audit: Eliminated null! suppressions, fixed latent null bugs, and added nullable attributes across the codebase. Return types and parameters may have changed nullability. by @niemyjski in #484, #498

Added

• Upgrade to xUnit v3 with Foundatio.Xunit.v3: Test infrastructure upgraded to xUnit v3. New Foundatio.Xunit.v3 package with retry test attributes (RetryFactAttribute, RetryTheoryAttribute) for automatic retry of flaky tests. The existing Foundatio.Xunit package continues to support xUnit v2. by @niemyjski in #431
• Memory-limited in-memory cache: InMemoryCacheClient now supports MaxMemorySize with per-entry size limits and intelligent eviction when memory budgets are exceeded. by @niemyjski, @copilot in #400
• Poison message handling for queues and message bus: Deserialization failures in queues and the message bus are now gracefully handled as poison messages instead of crashing consumers. Dead letter logging improved. by @niemyjski in #455
• SerializerException: New exception type for serialization-specific errors, enabling targeted error handling. by @niemyjski in b314a052
• MessageBusException: Consistent error handling for messaging operations with improved delayed message delivery. by @niemyjski in #443
• QueueDeleted event on IQueue<T>: Consumers can now subscribe to queue deletion notifications. by @niemyjski in #447
• OpenTelemetry error recording: Added Activity.AddException polyfill for recording exceptions in distributed traces across all target frameworks. by @niemyjski in #446
• Synchronous IResiliencePolicy methods: Added sync overloads (Execute, ExecuteAsync) alongside existing async methods. by @ejsmith in #445
• Feature-specific exceptions excluded from resilience policy retries: QueueException, MessageBusException, StorageException, SerializerException, and CacheException are no longer retried by resilience policies. by @niemyjski in 318fa1a0
• GetAllExpirationsAsync and SetAllExpirationsAsync on ICacheClient: Bulk expiration read/write support with improved test coverage. by @niemyjski in #426
• Option to dispose underlying scoped implementations: Scoped cache/queue/etc. wrappers can now optionally dispose their underlying instances. by @niemyjski in #412
• Job status description: JobStatus now supports a Description property. by @ejsmith in fdcc1442
• Enforce 5ms minimum expiration across all cache implementations: Prevents extremely short TTLs that cause race conditions. by @niemyjski in #463
• net10.0 target framework: Added .NET 10 support alongside .NET 8. by @niemyjski in 4c6aefed, a1089422
• Delayed message delivery: Message bus now supports delayed/scheduled message publishing. by @niemyjski in #443
• TestCancellationToken in test harness: Added to TestLoggerBase and TestWithLoggingBase (v2 and v3) for better test cancellation support. by @niemyjski in c37508ef, d24afcb7
• Scoped cache constructor overload: New ScopedCacheClient constructor that defaults shouldDispose to false to prevent accidental disposal. by @niemyjski in f28463b9

Changed

• Replaced DeepCloner with FastCloner: Switched deep cloning implementation from DeepCloner to FastCloner (v3.5.3) for better performance and active maintenance. Huge thanks to @lofcz (Matej Stagl) for contributing FastCloner and helping integrate it into Foundatio -- this was a major effort that touched the deep internals of the cloning infrastructure. by @niemyjski, @lofcz in #469, #485
• HybridCacheClient subscription moved out of constructor: Uses AsyncLazy to avoid sync-over-async in constructors. by @niemyjski in 7050c523
• Improved HybridCacheClient consistency and invalidation: Fixed consistency issues, optimized invalidation, and improved double comparison logic. by @niemyjski in #433
• ScheduledTimer uses TimeProvider: Scheduled jobs now use TimeProvider for delays, improving testability. by @niemyjski in 77727cdf
• Two-phase dispose for MessageBus subscription lifecycle: More reliable shutdown behavior. by @niemyjski in #492
• Cancellation tokens linked to disposal: MessageBus and Queue now link cancellation tokens to disposal for prompt shutdown. by @niemyjski in c06fcdef
• Improved disposal logic consistency: Disposal guards, IsDisposed consolidation, and proper CancellationTokenSource disposal across all base classes. by @niemyjski in 49eec83a, be62be11
• Enhanced MessageOptions: Added XML documentation and support for custom properties. by @niemyjski in 692c644d
• Refactored DataDictionary: Uses TryGetValue, nullable returns, and switch expressions. by @niemyjski in 2b423514
• Comprehensive XML documentation: Enhanced docs across ICacheClient, IQueue, IMessageBus, IFileStorage, ILockProvider, and IJob interfaces. by @niemyjski in 7fdad859
• Lock providers accept TimeProvider and IResiliencePolicyProvider: CacheLockProvider and ThrottlingLockProvider now receive dependencies via constructor injection for improved testability and resilience. by @niemyjski in e3e815c4
• Improved async timeout handling: Refactored AsyncCountdownEvent to use WaitAsync consistently; QueueTestBase now implements IAsyncDisposable. by @niemyjski in d78f220d
• Updated dependencies: Microsoft.Extensions packages, BenchmarkDotNet, Aspire, Polly, and others updated to latest versions. by @niemyjski, @ejsmith

Fixed

• Race condition in InMemoryQueue.AbandonAsync: Fixed flaky RunUntilEmptyAsync caused by abandon race. by @niemyjski in #470
• InvalidCastException in InMemoryCacheClient.GetAsync<object>(): Fixed crash for non-IConvertible types. by @copilot in #468
• Race condition in ScheduledTimer: Fixed timing issue in scheduled timer callbacks. by @niemyjski in 65e3116a
• Race condition in HybridCacheClient invalidation tests: Fixed flaky test caused by invalidation timing. by @niemyjski in 5acce8bc
• InMemoryQueue retry entry isolation: Each retry attempt now creates a fresh queue entry, preventing state leakage between attempts. by @niemyjski in #454
• Sync-over-async deadlock in MessageBusBase: Fixed deadlock in CancellationToken.Register callback. by @niemyjski in fdc47d22
• ThrottlingLockProvider period boundary issues: Hardened spin-wait with String.Equals, iteration cap, and improved diagnostics. by @niemyjski in d619b7e3, bbca0e39
• IndexOutOfRangeException in FastCloner GenerateProcessSetMethod: Fixed array bounds issue in deep cloning. by @niemyjski in f1992944
• ArgumentOutOfRangeException in DoMaintenance: Prevented negative timespan in queue maintenance scheduling. by @niemyjski in ee00d141
• DateTime overflow in cache maintenance: Added SafeAdd extension methods to prevent overflow exceptions when adding to DateTime.MaxValue / DateTime.MinValue. by @niemyjski in 6df04edf
• Zero or negative expiration in ReplaceIfEqualAsync: Now correctly removes the key instead of setting an invalid TTL. by @niemyjski in ffc8d352
• Null/empty connection strings in ConnectionStringParser: Now handled gracefully instead of throwing. by @niemyjski in df7c6898
• FaultInjectingSerializer missing ITextSerializer: Now implements ITextSerializer to prevent unexpected Base64 encoding in tests. by @niemyjski in 87fdf6e3
• Flaky metrics test: Fixed timer resolution race with DateTime.UtcNow. by @niemyjski in #488
• Queue metrics when disposed: Returns empty metrics instead of throwing. by @lofcz in 4744fc1b

New Contributors

Huge shoutout to @lofcz (Matej Stagl) for his outstanding contributions to this release! Matej is the author of FastCloner, which replaces DeepCloner as Foundatio's deep cloning engine. He contributed the integration PRs (#469, #485), kept FastCloner in sync with upstream improvements, and fixed a queue metrics edge case -- all while being incredibly responsive and collaborative. Thank you, Matej!

• @niemyjski
• @ejsmith
• @lofcz (Matej Stagl) -- FastCloner author and integration contributor
• @copilot

---

Migration Guide

Target Framework Changes

v13 drops netstandard2.0 and targets net8.0;net10.0. If you are on .NET Framework, you must stay on Foundatio v12.x.

Cache API Changes

• IncrementAsync TTL: The TTL parameter now behaves consistently across all cache implementations. Review any code that relied on implementation-specific TTL behavior during increment operations.
• ListRemoveAsync: The ExpiresIn parameter has been removed. If you were passing an expiration to ListRemoveAsync, remove that argument.
• GetExpirationAsync: Return values are now normalized. Test any code that compared expiration values across implementations.
• Minimum expiration: All cache implementations now enforce a 5ms minimum expiration. Values below 5ms will be clamped.

Serializer Changes

• All ISerializer implementations now validate arguments consistently. If your code was passing null to serializer methods, you will now get ArgumentNullException.
• SerializerException is now thrown for serialization-specific failures. Update any catch blocks that were catching general exceptions from serializers.

Queue Changes

• Queue operations now throw QueueException for queue-specific errors. Update exception handling accordingly.
• Queue behavior instances (e.g., IQueueBehavior<T>) can no longer be reused across multiple queue instances.
• Poison messages (deserialization failures) are now routed to dead letters instead of crashing consumers. Review dead letter handling if you rely on immediate failure notification.

Messaging Changes

• MessageBusException is now thrown for messaging errors. Update exception handling.
• MessageBusId and QueueId are now init-only. Set them during construction only.

Nullable Reference Types

• Many APIs have updated nullability annotations. If you have NRT enabled, expect new warnings that reflect the corrected nullability contracts. These are accurate -- the previous annotations were incorrect.

Removed APIs

• CacheClientExtensions.Set / SetAdd / SetRemove (obsolete overloads) -- These were renamed to ListAdd / ListRemove back in v9.0.0 (November 2019) to avoid confusion between "set" as a verb and "set" as a data structure. The old names have been marked [Obsolete] for over 6 years across 4 major versions. Use the List* equivalents.
• IFileStorage.GetFileStreamAsync(string path) (single-parameter overload) -- Deprecated in v10.7.0 (January 2024) when write-capable file streams were added in #290, which introduced an overload accepting StreamMode and CancellationToken. The single-parameter version has been [Obsolete] for 2+ years. Use GetFileStreamAsync(path, StreamMode.Read, cancellationToken) instead.

Full Changelog: v12.0.0...v13.0.0

What's Changed

• fix: implement two-phase dispose for MessageBus subscription lifecycle by @niemyjski in #492
• Add poison message handling for queue deserialization failures by @niemyjski in #455
• Enforce 5ms minimum expiration across all cache implementations by @niemyjski in #463
• Fix InvalidCastException in InMemoryCacheClient.GetAsync<object>() for non-IConvertible types by @Copilot in #468
• Fix race condition in InMemoryQueue.AbandonAsync causing flaky RunUntilEmptyAsync by @niemyjski in #470
• FastCloner as DeepCloner replacement by @lofcz in #469
• Bump dompurify from 3.3.1 to 3.3.2 in /docs by @dependabot[bot] in #471
• Bump rollup from 4.55.1 to 4.59.0 in /docs by @dependabot[bot] in #465
• Bump minimatch from 10.1.1 to 10.2.4 in /docs by @dependabot[bot] in #464
• sync fast cloner to 3.5.3 by @lofcz in #485
• refactor: comprehensive NRT null-safety audit — eliminate null! suppressions, fix latent bugs, add nullable attributes by @niemyjski in #484
• Fix flaky metrics test caused by DateTime.UtcNow timer resolution race by @niemyjski in #488
• Bump lodash-es from 4.17.23 to 4.18.1 in /docs by @dependabot[bot] in #489
• Bump vite from 7.3.1 to 7.3.2 in /docs by @dependabot[bot] in #486
• Bump picomatch from 4.0.3 to 4.0.4 in /docs by @dependabot[bot] in #483
• Document RabbitMQ delayed delivery and plugin deprecation by @niemyjski in #490

New Contributors

• @lofcz made their first contribution in #469

Full Changelog: v13.0.0-beta3...v13.0.0-beta6

What's Changed

• Add poison message handling for queue deserialization failures by @niemyjski in #455
• Enforce 5ms minimum expiration across all cache implementations by @niemyjski in #463
• Fix InvalidCastException in InMemoryCacheClient.GetAsync<object>() for non-IConvertible types by @Copilot in #468
• Fix race condition in InMemoryQueue.AbandonAsync causing flaky RunUntilEmptyAsync by @niemyjski in #470
• FastCloner as DeepCloner replacement by @lofcz in #469
• Bump dompurify from 3.3.1 to 3.3.2 in /docs by @dependabot[bot] in #471
• Bump rollup from 4.55.1 to 4.59.0 in /docs by @dependabot[bot] in #465
• Bump minimatch from 10.1.1 to 10.2.4 in /docs by @dependabot[bot] in #464
• sync fast cloner to 3.5.3 by @lofcz in #485
• refactor: comprehensive NRT null-safety audit — eliminate null! suppressions, fix latent bugs, add nullable attributes by @niemyjski in #484
• Fix flaky metrics test caused by DateTime.UtcNow timer resolution race by @niemyjski in #488
• Bump lodash-es from 4.17.23 to 4.18.1 in /docs by @dependabot[bot] in #489
• Bump vite from 7.3.1 to 7.3.2 in /docs by @dependabot[bot] in #486
• Bump picomatch from 4.0.3 to 4.0.4 in /docs by @dependabot[bot] in #483
• Document RabbitMQ delayed delivery and plugin deprecation by @niemyjski in #490

New Contributors

• @lofcz made their first contribution in #469

Full Changelog: v13.0.0-beta3...v13.0.0-beta5

What's Changed

• Add poison message handling for queue deserialization failures by @niemyjski in #455
• Enforce 5ms minimum expiration across all cache implementations by @niemyjski in #463
• Fix InvalidCastException in InMemoryCacheClient.GetAsync<object>() for non-IConvertible types by @Copilot in #468
• Fix race condition in InMemoryQueue.AbandonAsync causing flaky RunUntilEmptyAsync by @niemyjski in #470
• FastCloner as DeepCloner replacement by @lofcz in #469
• Bump dompurify from 3.3.1 to 3.3.2 in /docs by @dependabot[bot] in #471
• Bump rollup from 4.55.1 to 4.59.0 in /docs by @dependabot[bot] in #465
• Bump minimatch from 10.1.1 to 10.2.4 in /docs by @dependabot[bot] in #464
• sync fast cloner to 3.5.3 by @lofcz in #485
• refactor: comprehensive NRT null-safety audit — eliminate null! suppressions, fix latent bugs, add nullable attributes by @niemyjski in #484
• Fix flaky metrics test caused by DateTime.UtcNow timer resolution race by @niemyjski in #488
• Bump lodash-es from 4.17.23 to 4.18.1 in /docs by @dependabot[bot] in #489
• Bump vite from 7.3.1 to 7.3.2 in /docs by @dependabot[bot] in #486
• Bump picomatch from 4.0.3 to 4.0.4 in /docs by @dependabot[bot] in #483
• Document RabbitMQ delayed delivery and plugin deprecation by @niemyjski in #490

New Contributors

• @lofcz made their first contribution in #469

Full Changelog: v13.0.0-beta3...v13.0.0-beta4

What's Changed

• Fix InMemoryQueue retry: create fresh entry per attempt (entry isolation) by @niemyjski in #454

Full Changelog: v13.0.0-beta2...v13.0.0-beta3

What's Changed

• [Breaking]: Normalize ISerializer argument validation and enhance test coverage by @niemyjski in #440
• Improve delayed message delivery and add MessageBusException for consistent error handling by @niemyjski in #443
• Add DeepClone benchmarks, upgrade DeepCloner to v0.10.4, and add sync resilience methods by @niemyjski in #445
• Add QueueDeleted event to IQueue for queue deletion notifications by @niemyjski in #447
• Add QueueException and guard against reusing behavior instances by @niemyjski in #448
• Add OpenTelemetry error recording with Activity.AddException polyfill by @niemyjski in #446

Full Changelog: v13.0.0-beta1...v13.0.0-beta2

Breaking Changes

• [Caching]: Normalized ICacheClient.IncrementAsync TTL behavior to be consistent across all implementations. #434 by @niemyjski
• [Caching]: Removed ExpiresIn argument from ListRemoveAsync to align with all other Remove methods. #434 by @niemyjski
• [Caching]: Ensured consistent return values for ExpiresIn across all cache operations. #432 by @niemyjski
• [Caching]: Removed obsolete Set methods from cache extensions. by @niemyjski

Added

• [.NET 10 Support]: Added .NET 10.0 target framework support. by @niemyjski
• [Caching]: Added memory-limited in-memory cache with per-entry size limits and intelligent eviction. #400 by @Copilot
• [Caching]: Added GetAllExpirationsAsync and SetAllExpirationsAsync methods to ICacheClient. #426 by @niemyjski
• [Caching]: Added GetExpirationsAsync method to retrieve cache entry expiration information. by @niemyjski
• [Testing]: Added Foundatio.Xunit.v3 package with support for xUnit v3. #431 by @niemyjski
• [Caching]: Added scoped cache constructor overload for improved flexibility. by @niemyjski
• [Caching]: Added option to dispose underlying scoped cache implementations. #412 by @niemyjski
• [Locks]: Lock providers now receive dependencies for better integration. by @niemyjski
• [Documentation]: Added comprehensive documentation site with source code links across all features. by @niemyjski @ejsmith

Changed

• [Caching]: Optimized hybrid cache invalidation for improved performance. by @niemyjski
• [Caching]: Improved hybrid cache consistency and double comparison handling. #433 by @niemyjski
• [Caching]: Normalized increment behavior in hybrid cache. by @niemyjski
• [Messaging]: Replaced cancellation token source in MessageBusBase for better resource management. by @niemyjski
• [Jobs]: Improved ScheduledTimer disposal and scheduling. by @niemyjski
• [Queues]: Uses DateTimeOffset for queue stats update for better timezone handling. by @niemyjski
• [Testing]: Refactored hosting tests to use HostBuilder due to deprecations. by @niemyjski
• [Testing]: Improved test coverage for caching features. #426 by @niemyjski
• [Build]: Enhanced versioning in build workflow. by @ejsmith
• [Build]: Fixed build workflow publishing empty.nupkg from EmptyFiles test package. #428 by @Copilot

Fixed

• [Caching]: Guards against DateTime overflow in caching operations. by @niemyjski
• [Caching]: Handles zero or negative expiration times correctly. by @niemyjski
• [Cancellation]: Ensures proper disposal of cancellation token sources across all components. by @niemyjski
• [Cancellation]: Ensures tasks are cancelled on disposal. by @niemyjski
• [Cancellation]: Fixed dispose cancellation token usage. by @niemyjski
• [Resilience]: Improved asynchronous timeout handling. by @niemyjski

Dependencies

• Updated to Microsoft.AspNetCore.TestHost 8.0.20 #409
• Updated to BenchmarkDotNet 0.15.3 #410
• Updated to Polly 8.6.3 #406
• Updated to Aspire.Hosting.Redis 9.4.2 #407
• Updated Aspire packages to 9.5.0
• Updated Microsoft package versions
• Updated benchmark dependencies
• Optimized some code for .NET 8

Notes

• This is a beta release. The breaking changes in caching behavior ensure consistency across all implementations and providers.
• .NET 10 support is experimental and subject to change as .NET 10 evolves.
• The new memory-limited cache provides better control over memory usage in high-load scenarios.
• Documentation has been significantly expanded with source code links and implementation details.

Full Changelog

What's Changed

• Storage Exception + FileSpec Data Prop by @niemyjski in #385
• #382 tweak dependencies based on new tfm by @thompson-tomo in #383
• Add extensible resilience policies by @ejsmith in #388
• Adding Foundatio builders for configuring in IServiceCollection. Various other improvements. by @ejsmith in #393
• BREAKING: Improved Cache Tests and normalized ICacheClient.RemoveByPrefix by @niemyjski in #395
• Don't throw immediately if passed in cancellation token is cancelled. by @ejsmith in #397
• Add IHybridAwareCacheClient and Implement Local Cache lookups to HybridCacheClient for GetAllAsync, ExistsAsync, and GetExpirationAsync. by @niemyjski in #401
• Adds queue dequeue activity tracking by @niemyjski in #402

New Contributors

• @thompson-tomo made their first contribution in #383

Full Changelog: v11.1.0...v12.0.0