(#384) Added SynchronizationProgress event

Author: StefanCuypers

src/CommunityToolkit.Datasync.Client/Offline/OfflineDbContext.cs

@@ -99,6 +99,12 @@ public abstract partial class OfflineDbContext : DbContext
     /// </summary>
     internal OperationsQueueManager QueueManager { get; }
 
+    /// <summary>
+    /// An event delegate that allows the app to monitor synchronization events.
+    /// </summary>
+    /// <remarks>This event can be called from background threads.</remarks>
+    public event EventHandler<SynchronizationEventArgs>? SynchronizationProgress;
+
     /// <summary>
     ///     Initializes a new instance of the <see cref="OfflineDbContext" /> class. The 
     ///     <see cref="OnConfiguring(DbContextOptionsBuilder)" /> method will be called to 
@@ -561,6 +567,15 @@ public async Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess, bool add
         return await base.SaveChangesAsync(acceptAllChangesOnSuccess, cancellationToken).ConfigureAwait(false);
     }
 
+    /// <summary>
+    /// Sends a synchronization event to the consumers.
+    /// </summary>
+    /// <param name="eventArgs">The event arguments.</param>
+    internal void SendSynchronizationEvent(SynchronizationEventArgs eventArgs)
+    {
+        SynchronizationProgress?.Invoke(this, eventArgs);
+    }
+
     #region IDisposable
     /// <summary>
     /// Ensure that the context has not been disposed.

src/CommunityToolkit.Datasync.Client/Offline/Operations/PullOperationManager.cs

@@ -105,6 +105,15 @@ public async Task<PullResult> ExecuteAsync(IEnumerable<PullRequest> requests, Pu
                 }
             }
 
+            context.SendSynchronizationEvent(new SynchronizationEventArgs()
+            {
+                EventType = SynchronizationEventType.ItemsCommitted,
+                EntityType = pullResponse.EntityType,
+                ItemsProcessed = pullResponse.TotalItemsProcessed,
+                TotalNrItems = pullResponse.TotalRequestItems,
+                QueryId = pullResponse.QueryId
+            });
+
             if (pullOptions.SaveAfterEveryServiceRequest)
             {
                 _ = await context.SaveChangesAsync(true, false, cancellationToken).ConfigureAwait(false);
@@ -120,10 +129,22 @@ public async Task<PullResult> ExecuteAsync(IEnumerable<PullRequest> requests, Pu
             try
             {
                 bool completed = false;
+                long itemsProcessed = 0;
                 do
                 {
                     Page<object> page = await GetPageAsync(pullRequest.HttpClient, requestUri, pageType, cancellationToken).ConfigureAwait(false);
-                    databaseUpdateQueue.Enqueue(new PullResponse(pullRequest.EntityType, pullRequest.QueryId, page.Items));
+                    itemsProcessed += page.Items.Count();
+
+                    context.SendSynchronizationEvent(new SynchronizationEventArgs()
+                    {
+                        EventType = SynchronizationEventType.ItemsFetched,
+                        EntityType = pullRequest.EntityType,
+                        ItemsProcessed = itemsProcessed,
+                        TotalNrItems = page.Count ?? 0,
+                        QueryId = pullRequest.QueryId
+                    });
+
+                    databaseUpdateQueue.Enqueue(new PullResponse(pullRequest.EntityType, pullRequest.QueryId, page.Items, page.Count ?? 0, itemsProcessed));
                     if (!string.IsNullOrEmpty(page.NextLink))
                     {
                         requestUri = new UriBuilder(endpoint) { Query = page.NextLink }.Uri;
@@ -173,6 +194,8 @@ public async Task<PullResult> ExecuteAsync(IEnumerable<PullRequest> requests, Pu
     /// <exception cref="DatasyncPullException">Thrown on error</exception>
     internal async Task<Page<object>> GetPageAsync(HttpClient client, Uri requestUri, Type pageType, CancellationToken cancellationToken = default)
     {
+        PropertyInfo countPropInfo = pageType.GetProperty("Count")
+            ?? throw new DatasyncException($"Page type '{pageType.Name}' does not have a 'Count' property");
         PropertyInfo itemsPropInfo = pageType.GetProperty("Items")
             ?? throw new DatasyncException($"Page type '{pageType.Name}' does not have an 'Items' property");
         PropertyInfo nextLinkPropInfo = pageType.GetProperty("NextLink")
@@ -193,6 +216,7 @@ internal async Task<Page<object>> GetPageAsync(HttpClient client, Uri requestUri
 
             return new Page<object>()
             {
+                Count = (long?)countPropInfo.GetValue(result),
                 Items = (IEnumerable<object>)itemsPropInfo.GetValue(result)!,
                 NextLink = (string?)nextLinkPropInfo.GetValue(result)
             };
@@ -237,6 +261,8 @@ internal static QueryDescription PrepareQueryDescription(QueryDescription source
     /// <param name="EntityType">The type of entity contained within the items.</param>
     /// <param name="QueryId">The query ID for the request.</param>
     /// <param name="Items">The list of items to process.</param>
+    /// <param name="TotalRequestItems">The total number of items in the current pull request.</param>
+    /// <param name="TotalItemsProcessed">The total number of items processed, <paramref name="Items"/> included.</param>
     [ExcludeFromCodeCoverage]
-    internal record PullResponse(Type EntityType, string QueryId, IEnumerable<object> Items);
+    internal record PullResponse(Type EntityType, string QueryId, IEnumerable<object> Items, long TotalRequestItems, long TotalItemsProcessed);
 }

src/CommunityToolkit.Datasync.Client/Offline/SynchronizationEventArgs.cs

@@ -0,0 +1,54 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace CommunityToolkit.Datasync.Client.Offline;
+
+/// <summary>
+/// The list of synchronization events that we support.
+/// </summary>
+public enum SynchronizationEventType
+{
+    /// <summary>
+    /// Occurs when items have been successfully fetches from the server.
+    /// </summary>
+    /// <remarks>This event is raised after a page of entities was succesfully fetched from the server, ready to be commited to the data store.</remarks>
+    ItemsFetched,
+
+    /// <summary>
+    /// Occurs when items have been successfully committed to the underlying data store.
+    /// </summary>
+    /// <remarks>This event is raised after a page of entities was succesfully commited to the database</remarks>
+    ItemsCommitted,
+}
+
+/// <summary>
+/// The event arguments sent when a synchronization event occurs.
+/// </summary>
+public class SynchronizationEventArgs
+{
+    /// <summary>
+    /// The type of event.
+    /// </summary>
+    public required SynchronizationEventType EventType { get; init; }
+
+    /// <summary>
+    /// The EntityType that is being processed.
+    /// </summary>
+    public required Type EntityType { get; init; }
+
+    /// <summary>
+    /// When pulling records, the number of items that have been processed in the current pull request.
+    /// </summary>
+    public long ItemsProcessed { get; init; } = -1;
+
+    /// <summary>
+    /// The total number of items in the current pull request.
+    /// </summary>
+    public long TotalNrItems { get; init; }
+
+    /// <summary>
+    /// The query ID that is being processed
+    /// </summary>
+    public required string QueryId { get; init; }
+}