Clean-up warnings around IDisposable pattern and null usages

Author: michael-hawker

Microsoft.Toolkit.Uwp/Extensions/TypedEventHandlerExtensions.cs

@@ -57,9 +57,11 @@ public static Task InvokeAsync<S, R>(this TypedEventHandler<S, R> eventHandler,
 
                     invocationDelegate(sender, eventArgs);
 
+                    #pragma warning disable CS0618 // Type or member is obsolete
                     var deferral = eventArgs.GetCurrentDeferralAndReset();
 
                     return deferral?.WaitForCompletion(cancellationToken) ?? Task.CompletedTask;
+                    #pragma warning restore CS0618 // Type or member is obsolete
                 })
                 .ToArray();
 

Microsoft.Toolkit/Deferred/DeferredEventArgs.cs

@@ -3,13 +3,15 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
+using System.ComponentModel;
+using System.Runtime.CompilerServices;
 
 namespace Microsoft.Toolkit.Deferred
 {
     /// <summary>
     /// <see cref="EventArgs"/> which can retrieve a <see cref="EventDeferral"/> in order to process data asynchronously before an <see cref="EventHandler"/> completes and returns to the calling control.
     /// </summary>
-    public class DeferredEventArgs : EventArgs
+    public class DeferredEventArgs : EventArgs, IDisposable
     {
         /// <summary>
         /// Gets a new <see cref="DeferredEventArgs"/> to use in cases where no <see cref="EventArgs"/> wish to be provided.
@@ -18,7 +20,13 @@ public class DeferredEventArgs : EventArgs
 
         private readonly object _eventDeferralLock = new object();
 
-        private EventDeferral _eventDeferral;
+        private EventDeferral? _eventDeferral;
+        private bool _disposed;
+
+        /// <summary>
+        /// Finalizes an instance of the <see cref="DeferredEventArgs"/> class.
+        /// </summary>
+        ~DeferredEventArgs() => Dispose(false);
 
         /// <summary>
         /// Returns an <see cref="EventDeferral"/> which can be completed when deferred event is ready to continue.
@@ -32,7 +40,17 @@ public EventDeferral GetDeferral()
             }
         }
 
-        internal EventDeferral GetCurrentDeferralAndReset()
+        /// <summary>
+        /// DO NOT USE - This is a support method used by <see cref="EventHandlerExtensions"/>. It is public only for
+        /// additional usage within extensions for the UWP based TypedEventHandler extensions.
+        /// </summary>
+        /// <returns>Internal EventDeferral reference</returns>
+#if !NETSTANDARD1_4
+        [Browsable(false)]
+#endif
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        [Obsolete("This is an internal only method to be used by EventHandler extension classes, public callers should call GetDeferral() instead.")]
+        public EventDeferral? GetCurrentDeferralAndReset()
         {
             lock (_eventDeferralLock)
             {
@@ -43,5 +61,31 @@ internal EventDeferral GetCurrentDeferralAndReset()
                 return eventDeferral;
             }
         }
+
+        /// <summary>
+        /// Recommended helper method pattern for <see cref="IDisposable"/>.
+        /// </summary>
+        /// <param name="disposing">Source of dispose request.</param>
+        protected virtual void Dispose(bool disposing)
+        {
+            if (_disposed)
+            {
+                return;
+            }
+
+            _eventDeferral?.Dispose();
+
+            _disposed = true;
+        }
+
+        /// <inheritdoc/>
+        public void Dispose()
+        {
+            // Dispose of unmanaged resources.
+            Dispose(true);
+
+            // Suppress finalization.
+            GC.SuppressFinalize(this);
+        }
     }
-}
+}

Microsoft.Toolkit/Deferred/EventDeferral.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
+using System.ComponentModel;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -13,29 +14,66 @@ namespace Microsoft.Toolkit.Deferred
     /// </summary>
     public class EventDeferral : IDisposable
     {
-        private readonly TaskCompletionSource<object> _taskCompletionSource = new TaskCompletionSource<object>();
+        //// TODO: If/when .NET 5 is base, we can upgrade to non-generic version
+        private readonly TaskCompletionSource<object?> _taskCompletionSource = new TaskCompletionSource<object?>();
+        private bool _disposed = false;
 
         internal EventDeferral()
         {
         }
 
+        /// <summary>
+        /// Finalizes an instance of the <see cref="EventDeferral"/> class.
+        /// </summary>
+        ~EventDeferral() => Dispose(false);
+
         /// <summary>
         /// Call when finished with the Deferral.
         /// </summary>
         public void Complete() => _taskCompletionSource.TrySetResult(null);
 
-        internal async Task WaitForCompletion(CancellationToken cancellationToken)
+        /// <summary>
+        /// Waits for the <see cref="EventDeferral"/> to be completed by the event handler.
+        /// </summary>
+        /// <param name="cancellationToken"><see cref="CancellationToken"/>.</param>
+        /// <returns><see cref="Task"/>.</returns>
+#if !NETSTANDARD1_4
+        [Browsable(false)]
+#endif
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        [Obsolete("This is an internal only method to be used by EventHandler extension classes, public callers should call GetDeferral() instead on the DeferredEventArgs.")]
+        public async Task WaitForCompletion(CancellationToken cancellationToken)
         {
             using (cancellationToken.Register(() => _taskCompletionSource.TrySetCanceled()))
             {
                 await _taskCompletionSource.Task;
             }
         }
 
+        /// <summary>
+        /// Recommended helper method pattern for <see cref="IDisposable"/>.
+        /// </summary>
+        /// <param name="disposing">Source of dispose request.</param>
+        protected virtual void Dispose(bool disposing)
+        {
+            if (_disposed)
+            {
+                return;
+            }
+
+            Complete();
+
+            _disposed = true;
+        }
+
         /// <inheritdoc/>
         public void Dispose()
         {
-            Complete();
+            // Dispose of unmanaged resources.
+            Dispose(true);
+
+            // Suppress finalization.
+            GC.SuppressFinalize(this);
         }
     }
-}
+}

Microsoft.Toolkit/Extensions/EventHandlerExtensions.cs

@@ -7,7 +7,7 @@
 using System.Threading;
 using System.Threading.Tasks;
 
-namespace Microsoft.Toolkit.Uwp.Deferred
+namespace Microsoft.Toolkit.Deferred
 {
     /// <summary>
     /// Extensions to <see cref="EventHandler{TEventArgs}"/> for Deferred Events.
@@ -53,9 +53,11 @@ public static Task InvokeAsync<T>(this EventHandler<T> eventHandler, object send
 
                     invocationDelegate(sender, eventArgs);
 
+                    #pragma warning disable CS0618 // Type or member is obsolete
                     var deferral = eventArgs.GetCurrentDeferralAndReset();
 
                     return deferral?.WaitForCompletion(cancellationToken) ?? Task.CompletedTask;
+                    #pragma warning restore CS0618 // Type or member is obsolete
                 })
                 .ToArray();