Overhaul DatabaseAccessAbstractions

Code/Light.SharedCore/DatabaseAccessAbstractions/ISession.cs

@@ -1,22 +1,23 @@
 using System;
+using System.Threading;
+using System.Threading.Tasks;
 
 namespace Light.SharedCore.DatabaseAccessAbstractions;
 
 /// <summary>
 /// <para>
-/// PLEASE REMEMBER: database calls should be performed asynchronously
-/// by default, especially in service apps to avoid blocking threads.
-/// Consider using the <see cref="IAsyncSession" /> interface instead.
+/// Represents the base interface for an asynchronous session to a database that manipulates data. This means that
+/// the implementation will either use a single dedicated transaction in the case of ADO.NET or Micro-ORMs
+/// to ensure ACID properties, or the change tracking capabilities of a full ORM like Entity Framework Core.
 /// </para>
 /// <para>
-/// Represents a synchronous session to a database. This means that
-/// the implementation will either use a single dedicated transaction in the case of ADO.NET or Micro-ORMs
-/// to ensure ACID properties, or the Change Tracking capabilities of a full ORM like Entity Framework Core. The
-/// connection to the database can be terminated by calling
-/// <see cref="IDisposable.Dispose" />. Changes can be saved or committed
-/// to the database by calling <see cref="SaveChanges" />.
-/// If your session does not manipulate data, consider deriving your session abstraction from
-/// the <see cref="IDisposable" /> interface instead.
+/// The connection to the database can be terminated by calling
+/// <see cref="IAsyncDisposable.DisposeAsync" />, the underlying transaction
+/// will be automatically rolled back if <see cref="SaveChangesAsync" /> was not called beforehand.
+/// </para>
+/// <para>
+/// If you don't want the caller to explicitly commit the changes, consider deriving your session from
+/// <see cref="IAsyncDisposable"/> directly. 
 /// </para>
 /// </summary>
 /// <remarks>
@@ -26,10 +27,11 @@ namespace Light.SharedCore.DatabaseAccessAbstractions;
 /// to do Change Tracking which plain ADO.NET and all Micro-ORMs do not support. For this reason,
 /// we chose the term "session" instead of "Unit of Work", also because it is simpler to use in daily life.
 /// </remarks>
-public interface ISession : IDisposable
+public interface ISession : IAsyncDisposable
 {
     /// <summary>
-    /// Writes or commits all changes that occurred during the session to the target database.
+    /// Commits all changes to the database.
     /// </summary>
-    void SaveChanges();
+    /// <param name="cancellationToken">The token to cancel this asynchronous operation (optional).</param>
+    Task SaveChangesAsync(CancellationToken cancellationToken = default);
 }