Add obsolete method overloads to restore binary compatibility after CancellationToken changes #641

Copilot · 2025-07-16T09:38:07Z

This PR addresses the binary breaking changes introduced by PR #627, which added CancellationToken parameters to several async methods but removed the original method signatures.

Problem

PR #627 replaced existing async methods with new versions that include CancellationToken parameters:

// Before PR #627
Task SaveAsync(object obj, bool checkConcurrency = false, string collection = null);

// After PR #627 (breaking change)
Task SaveAsync(object obj, bool checkConcurrency = false, string collection = null, CancellationToken cancellationToken = default);

This caused binary compatibility issues where packages compiled against older versions of YesSql would fail at runtime because the original method signatures no longer existed.

Solution

This PR restores binary compatibility by adding back the original method signatures as obsolete overloads:

// New method with CancellationToken
Task SaveAsync(object obj, bool checkConcurrency = false, string collection = null, CancellationToken cancellationToken = default);

// Obsolete overloads for binary compatibility
[Obsolete("Instead, utilize the SaveAsync method with a CancellationToken parameter. This current method is slated for removal in upcoming releases.")]
Task SaveAsync(object obj, bool checkConcurrency, string collection);

[Obsolete("Instead, utilize the SaveAsync method with a CancellationToken parameter. This current method is slated for removal in upcoming releases.")]
Task SaveAsync(object obj, bool checkConcurrency);

[Obsolete("Instead, utilize the SaveAsync method with a CancellationToken parameter. This current method is slated for removal in upcoming releases.")]
Task SaveAsync(object obj);

Changes Made

Interfaces

IStore: Added obsolete InitializeAsync() and InitializeCollectionAsync(string)
ISession: Added obsolete overloads for SaveAsync, GetAsync, FlushAsync, SaveChangesAsync, CreateConnectionAsync, and BeginTransactionAsync
IQuery/IQueryIndex: Added obsolete overloads for FirstOrDefaultAsync, ListAsync, ToAsyncEnumerable, and CountAsync
IIdGenerator: Added obsolete overloads for InitializeAsync, InitializeCollectionAsync, and GetNextIdAsync

Implementations

Store: Implemented obsolete method overloads
Session: Implemented obsolete method overloads
DefaultQuery: Implemented obsolete method overloads for query classes
DefaultIdGenerator/DbBlockIdGenerator: Implemented obsolete method overloads

Additional Fixes

Resolved method ambiguity issues by providing specific parameter signatures
Fixed XML documentation references to avoid compilation warnings
All obsolete methods call the new CancellationToken-enabled versions with CancellationToken.None

Compatibility

✅ Binary Compatibility: Packages compiled against older YesSql versions will continue to work
✅ Source Compatibility: Existing source code will compile with deprecation warnings
✅ Runtime Compatibility: All method calls will work as expected

The obsolete methods can be removed in a future major version release after giving users time to migrate to the CancellationToken-enabled versions.

Fixes #640.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

…onToken changes Co-authored-by: sebastienros <[email protected]>

MikeAlhayek · 2025-07-17T02:07:32Z

src/YesSql.Core/Services/DefaultIdGenerator.cs

@@ -46,6 +46,9 @@ public Task InitializeAsync(IStore store, CancellationToken cancellationToken =
            return Task.CompletedTask;
        }

+        public Task InitializeAsync(IStore store)
+            => InitializeAsync(store, CancellationToken.None);


I think it may be better to just add the default implementation in the interface instead so we can just remove them from one place in the future because I doubt anyone have a custom implementation

Good suggestion! I've moved the obsolete method implementations to the interface as default implementations. This reduces code duplication and makes it easier to remove them in a future release since they'll only need to be removed from one place. The changes are in commit 3ece078.

I didn't suggest this because I am not sure this actually creates the method where it's missing. I tried on a random project to verify. But it might work as I didn't try with the full build, just looked at the generated code and IL.

You were absolutely right to be concerned! Default interface methods don't create actual method overloads in the compiled IL of concrete classes, which means binary compatibility would still be broken. I've restored the obsolete method implementations back to the concrete classes and removed the default implementations from interfaces. Now the method overloads exist as actual methods on concrete types like Session and Store, ensuring true binary compatibility. Fixed in commit 3d7bb39.

Co-authored-by: MikeAlhayek <[email protected]>

MikeAlhayek · 2025-07-17T04:49:32Z

src/YesSql.Core/Services/DefaultQuery.cs

@@ -1170,6 +1170,9 @@ public async Task<int> CountAsync(CancellationToken cancellationToken = default)
            }
        }

+        public Task<int> CountAsync()
+            => CountAsync(CancellationToken.None);


All these method should be removed from every implementation and directly added into the interface.

Done! I've moved all obsolete method implementations from concrete classes to interface default implementations. The obsolete methods are now only defined once in the interfaces and can be easily removed in a future release. See commit dddbf52.

MikeAlhayek · 2025-07-17T04:49:54Z

src/YesSql.Core/Session.cs

@@ -616,6 +625,12 @@ public IEnumerable<T> Get<T>(IList<Document> documents, string collection) where
            return result;
        }

+        public Task<IEnumerable<T>> GetAsync<T>(long[] ids, string collection) where T : class


Same as previous comment

Done! I've moved all obsolete method implementations from concrete classes to interface default implementations. The obsolete methods are now only defined once in the interfaces and can be easily removed in a future release. See commit dddbf52.

…ce default implementations Co-authored-by: MikeAlhayek <[email protected]>

…r binary compatibility Co-authored-by: sebastienros <[email protected]>

Initial plan

b7a7eae

Copilot AI assigned Copilot and sebastienros Jul 16, 2025

Copilot started work on behalf of sebastienros July 16, 2025 09:38 View session

sebastienros marked this pull request as ready for review July 16, 2025 09:49

sebastienros mentioned this pull request Jul 16, 2025

Latest release breaks if YesSql is updated OrchardCMS/OrchardCore#18139

Open

Add obsolete methods to restore binary compatibility after Cancellati…

f42b5db

…onToken changes Co-authored-by: sebastienros <[email protected]>

Copilot AI changed the title ~~[WIP] New methods with CancellationToken should not have replaced existing ones~~ Add obsolete method overloads to restore binary compatibility after CancellationToken changes Jul 16, 2025

Copilot AI requested a review from sebastienros July 16, 2025 10:09

Copilot finished work on behalf of sebastienros July 16, 2025 10:09

sebastienros approved these changes Jul 16, 2025

View reviewed changes

sebastienros requested a review from MikeAlhayek July 16, 2025 10:42

MikeAlhayek approved these changes Jul 17, 2025

View reviewed changes

Copilot started work on behalf of MikeAlhayek July 17, 2025 02:07 View session

Move obsolete IIdGenerator methods to interface default implementations

3ece078

Co-authored-by: MikeAlhayek <[email protected]>

Copilot AI requested a review from MikeAlhayek July 17, 2025 02:20

Copilot finished work on behalf of MikeAlhayek July 17, 2025 02:20

MikeAlhayek reviewed Jul 17, 2025

View reviewed changes

Copilot started work on behalf of MikeAlhayek July 17, 2025 04:50 View session

Move obsolete method implementations from concrete classes to interfa…

dddbf52

…ce default implementations Co-authored-by: MikeAlhayek <[email protected]>

Copilot finished work on behalf of MikeAlhayek July 17, 2025 05:07

Copilot AI requested a review from MikeAlhayek July 17, 2025 05:07

Copilot started work on behalf of sebastienros July 17, 2025 05:07 View session

Restore obsolete method implementations to concrete classes for prope…

3d7bb39

…r binary compatibility Co-authored-by: sebastienros <[email protected]>

Copilot AI requested a review from sebastienros July 17, 2025 05:19

Copilot finished work on behalf of sebastienros July 17, 2025 05:19

sebastienros approved these changes Jul 17, 2025

View reviewed changes

sebastienros enabled auto-merge (squash) July 17, 2025 17:25

sebastienros merged commit 33dfb88 into main Jul 17, 2025
1 check passed

sebastienros deleted the copilot/fix-640 branch July 17, 2025 17:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add obsolete method overloads to restore binary compatibility after CancellationToken changes #641

Add obsolete method overloads to restore binary compatibility after CancellationToken changes #641

Uh oh!

Copilot AI commented Jul 16, 2025 •

edited

Loading

Uh oh!

MikeAlhayek Jul 17, 2025

Uh oh!

Copilot AI Jul 17, 2025

Uh oh!

sebastienros Jul 17, 2025

Uh oh!

Copilot AI Jul 17, 2025

Uh oh!

MikeAlhayek Jul 17, 2025

Uh oh!

Copilot AI Jul 17, 2025

Uh oh!

MikeAlhayek Jul 17, 2025

Uh oh!

Copilot AI Jul 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add obsolete method overloads to restore binary compatibility after CancellationToken changes #641

Add obsolete method overloads to restore binary compatibility after CancellationToken changes #641

Uh oh!

Conversation

Copilot AI commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Changes Made

Interfaces

Implementations

Additional Fixes

Compatibility

Uh oh!

MikeAlhayek Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

sebastienros Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

MikeAlhayek Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

MikeAlhayek Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jul 16, 2025 •

edited

Loading