Merge pull request #3229 from Sergio0694/feature/mvvm-apis

Microsoft.Toolkit.Mvvm package

Author: michael-hawker

Microsoft.Toolkit.Mvvm/ComponentModel/ObservableObject.cs

@@ -0,0 +1,234 @@
+// 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.
+
+#pragma warning disable SA1512
+
+// This file is inspired from the MvvmLight libray (lbugnion/mvvmlight),
+// more info in ThirdPartyNotices.txt in the root of the project.
+
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using Microsoft.Toolkit.Mvvm.Messaging;
+using Microsoft.Toolkit.Mvvm.Messaging.Messages;
+
+namespace Microsoft.Toolkit.Mvvm.ComponentModel
+{
+    /// <summary>
+    /// A base class for observable objects that also acts as recipients for messages. This class is an extension of
+    /// <see cref="ObservableObject"/> which also provides built-in support to use the <see cref="IMessenger"/> type.
+    /// </summary>
+    public abstract class ObservableRecipient : ObservableObject
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ObservableRecipient"/> class.
+        /// </summary>
+        /// <remarks>
+        /// This constructor will produce an instance that will use the <see cref="Messaging.Messenger.Default"/> instance
+        /// to perform requested operations. It will also be available locally through the <see cref="Messenger"/> property.
+        /// </remarks>
+        protected ObservableRecipient()
+            : this(Messaging.Messenger.Default)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ObservableRecipient"/> class.
+        /// </summary>
+        /// <param name="messenger">The <see cref="IMessenger"/> instance to use to send messages.</param>
+        protected ObservableRecipient(IMessenger messenger)
+        {
+            Messenger = messenger;
+        }
+
+        /// <summary>
+        /// Gets the <see cref="IMessenger"/> instance in use.
+        /// </summary>
+        protected IMessenger Messenger { get; }
+
+        private bool isActive;
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the current view model is currently active.
+        /// </summary>
+        public bool IsActive
+        {
+            get => this.isActive;
+            set
+            {
+                if (SetProperty(ref this.isActive, value, true))
+                {
+                    if (value)
+                    {
+                        OnActivated();
+                    }
+                    else
+                    {
+                        OnDeactivated();
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Raised whenever the <see cref="IsActive"/> property is set to <see langword="true"/>.
+        /// Use this method to register to messages and do other initialization for this instance.
+        /// </summary>
+        /// <remarks>
+        /// The base implementation registers all messages for this recipients that have been declared
+        /// explicitly through the <see cref="IRecipient{TMessage}"/> interface, using the default channel.
+        /// For more details on how this works, see the <see cref="MessengerExtensions.RegisterAll"/> method.
+        /// If you need more fine tuned control, want to register messages individually or just prefer
+        /// the lambda-style syntax for message registration, override this method and register manually.
+        /// </remarks>
+        protected virtual void OnActivated()
+        {
+            Messenger.RegisterAll(this);
+        }
+
+        /// <summary>
+        /// Raised whenever the <see cref="IsActive"/> property is set to <see langword="false"/>.
+        /// Use this method to unregister from messages and do general cleanup for this instance.
+        /// </summary>
+        /// <remarks>
+        /// The base implementation unregisters all messages for this recipient. It does so by
+        /// invoking <see cref="IMessenger.UnregisterAll"/>, which removes all registered
+        /// handlers for a given subscriber, regardless of what token was used to register them.
+        /// That is, all registered handlers across all subscription channels will be removed.
+        /// </remarks>
+        protected virtual void OnDeactivated()
+        {
+            Messenger.UnregisterAll(this);
+        }
+
+        /// <summary>
+        /// Broadcasts a <see cref="PropertyChangedMessage{T}"/> with the specified
+        /// parameters, without using any particular token (so using the default channel).
+        /// </summary>
+        /// <typeparam name="T">The type of the property that changed.</typeparam>
+        /// <param name="oldValue">The value of the property before it changed.</param>
+        /// <param name="newValue">The value of the property after it changed.</param>
+        /// <param name="propertyName">The name of the property that changed.</param>
+        /// <remarks>
+        /// You should override this method if you wish to customize the channel being
+        /// used to send the message (eg. if you need to use a specific token for the channel).
+        /// </remarks>
+        protected virtual void Broadcast<T>(T oldValue, T newValue, string? propertyName)
+        {
+            var message = new PropertyChangedMessage<T>(this, propertyName, oldValue, newValue);
+
+            Messenger.Send(message);
+        }
+
+        /// <summary>
+        /// Compares the current and new values for a given property. If the value has changed,
+        /// raises the <see cref="ObservableObject.PropertyChanging"/> event, updates the property with
+        /// the new value, then raises the <see cref="ObservableObject.PropertyChanged"/> event.
+        /// </summary>
+        /// <typeparam name="T">The type of the property that changed.</typeparam>
+        /// <param name="field">The field storing the property's value.</param>
+        /// <param name="newValue">The property's value after the change occurred.</param>
+        /// <param name="broadcast">If <see langword="true"/>, <see cref="Broadcast{T}"/> will also be invoked.</param>
+        /// <param name="propertyName">(optional) The name of the property that changed.</param>
+        /// <returns><see langword="true"/> if the property was changed, <see langword="false"/> otherwise.</returns>
+        /// <remarks>
+        /// This method is just like <see cref="ObservableObject.SetProperty{T}(ref T,T,string)"/>, just with the addition
+        /// of the <paramref name="broadcast"/> parameter. As such, following the behavior of the base method,
+        /// the <see cref="ObservableObject.PropertyChanging"/> and <see cref="ObservableObject.PropertyChanged"/> events
+        /// are not raised if the current and new value for the target property are the same.
+        /// </remarks>
+        protected bool SetProperty<T>(ref T field, T newValue, bool broadcast, [CallerMemberName] string? propertyName = null)
+        {
+            return SetProperty(ref field, newValue, EqualityComparer<T>.Default, broadcast, propertyName);
+        }
+
+        /// <summary>
+        /// Compares the current and new values for a given property. If the value has changed,
+        /// raises the <see cref="ObservableObject.PropertyChanging"/> event, updates the property with
+        /// the new value, then raises the <see cref="ObservableObject.PropertyChanged"/> event.
+        /// See additional notes about this overload in <see cref="SetProperty{T}(ref T,T,bool,string)"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of the property that changed.</typeparam>
+        /// <param name="field">The field storing the property's value.</param>
+        /// <param name="newValue">The property's value after the change occurred.</param>
+        /// <param name="comparer">The <see cref="IEqualityComparer{T}"/> instance to use to compare the input values.</param>
+        /// <param name="broadcast">If <see langword="true"/>, <see cref="Broadcast{T}"/> will also be invoked.</param>
+        /// <param name="propertyName">(optional) The name of the property that changed.</param>
+        /// <returns><see langword="true"/> if the property was changed, <see langword="false"/> otherwise.</returns>
+        protected bool SetProperty<T>(ref T field, T newValue, IEqualityComparer<T> comparer, bool broadcast, [CallerMemberName] string? propertyName = null)
+        {
+            if (!broadcast)
+            {
+                return SetProperty(ref field, newValue, comparer, propertyName);
+            }
+
+            T oldValue = field;
+
+            if (SetProperty(ref field, newValue, comparer, propertyName))
+            {
+                Broadcast(oldValue, newValue, propertyName);
+
+                return true;
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Compares the current and new values for a given property. If the value has changed,
+        /// raises the <see cref="ObservableObject.PropertyChanging"/> event, updates the property with
+        /// the new value, then raises the <see cref="ObservableObject.PropertyChanged"/> event. Similarly to
+        /// the <see cref="ObservableObject.SetProperty{T}(T,T,Action{T},string)"/> method, this overload should only be
+        /// used when <see cref="ObservableObject.SetProperty{T}(ref T,T,string)"/> can't be used directly.
+        /// </summary>
+        /// <typeparam name="T">The type of the property that changed.</typeparam>
+        /// <param name="oldValue">The current property value.</param>
+        /// <param name="newValue">The property's value after the change occurred.</param>
+        /// <param name="callback">A callback to invoke to update the property value.</param>
+        /// <param name="broadcast">If <see langword="true"/>, <see cref="Broadcast{T}"/> will also be invoked.</param>
+        /// <param name="propertyName">(optional) The name of the property that changed.</param>
+        /// <returns><see langword="true"/> if the property was changed, <see langword="false"/> otherwise.</returns>
+        /// <remarks>
+        /// This method is just like <see cref="ObservableObject.SetProperty{T}(T,T,Action{T},string)"/>, just with the addition
+        /// of the <paramref name="broadcast"/> parameter. As such, following the behavior of the base method,
+        /// the <see cref="ObservableObject.PropertyChanging"/> and <see cref="ObservableObject.PropertyChanged"/> events
+        /// are not raised if the current and new value for the target property are the same.
+        /// </remarks>
+        protected bool SetProperty<T>(T oldValue, T newValue, Action<T> callback, bool broadcast, [CallerMemberName] string? propertyName = null)
+        {
+            return SetProperty(oldValue, newValue, EqualityComparer<T>.Default, callback, broadcast, propertyName);
+        }
+
+        /// <summary>
+        /// Compares the current and new values for a given property. If the value has changed,
+        /// raises the <see cref="ObservableObject.PropertyChanging"/> event, updates the property with
+        /// the new value, then raises the <see cref="ObservableObject.PropertyChanged"/> event.
+        /// See additional notes about this overload in <see cref="SetProperty{T}(T,T,Action{T},bool,string)"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of the property that changed.</typeparam>
+        /// <param name="oldValue">The current property value.</param>
+        /// <param name="newValue">The property's value after the change occurred.</param>
+        /// <param name="comparer">The <see cref="IEqualityComparer{T}"/> instance to use to compare the input values.</param>
+        /// <param name="callback">A callback to invoke to update the property value.</param>
+        /// <param name="broadcast">If <see langword="true"/>, <see cref="Broadcast{T}"/> will also be invoked.</param>
+        /// <param name="propertyName">(optional) The name of the property that changed.</param>
+        /// <returns><see langword="true"/> if the property was changed, <see langword="false"/> otherwise.</returns>
+        protected bool SetProperty<T>(T oldValue, T newValue, IEqualityComparer<T> comparer, Action<T> callback, bool broadcast, [CallerMemberName] string? propertyName = null)
+        {
+            if (!broadcast)
+            {
+                return SetProperty(oldValue, newValue, comparer, callback, propertyName);
+            }
+
+            if (SetProperty(oldValue, newValue, comparer, callback, propertyName))
+            {
+                Broadcast(oldValue, newValue, propertyName);
+
+                return true;
+            }
+
+            return false;
+        }
+    }
+}

Microsoft.Toolkit.Mvvm/ComponentModel/ObservableRecipient.cs

@@ -0,0 +1,145 @@
+// 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.
+
+using System;
+using System.Threading;
+using Microsoft.Extensions.DependencyInjection;
+
+#nullable enable
+
+namespace Microsoft.Toolkit.Mvvm.DependencyInjection
+{
+    /// <summary>
+    /// A type that facilitates the use of the <see cref="IServiceProvider"/> type.
+    /// The <see cref="Ioc"/> provides the ability to configure services in a singleton, thread-safe
+    /// service provider instance, which can then be used to resolve service instances.
+    /// The first step to use this feature is to declare some services, for instance:
+    /// <code>
+    /// public interface ILogger
+    /// {
+    ///     void Log(string text);
+    /// }
+    /// </code>
+    /// <code>
+    /// public class ConsoleLogger : ILogger
+    /// {
+    ///     void Log(string text) => Console.WriteLine(text);
+    /// }
+    /// </code>
+    /// Then the services configuration should then be done at startup, by calling one of
+    /// the available <see cref="ConfigureServices(IServiceCollection)"/> overloads, like so:
+    /// <code>
+    /// Ioc.Default.ConfigureServices(services =>
+    /// {
+    ///     services.AddSingleton&lt;ILogger, Logger&gt;();
+    /// });
+    /// </code>
+    /// Finally, you can use the <see cref="Ioc"/> instance (which implements <see cref="IServiceProvider"/>)
+    /// to retrieve the service instances from anywhere in your application, by doing as follows:
+    /// <code>
+    /// Ioc.Default.GetService&lt;ILogger&gt;().Log("Hello world!");
+    /// </code>
+    /// </summary>
+    public sealed class Ioc : IServiceProvider
+    {
+        /// <summary>
+        /// Gets the default <see cref="Ioc"/> instance.
+        /// </summary>
+        public static Ioc Default { get; } = new Ioc();
+
+        /// <summary>
+        /// The <see cref="ServiceProvider"/> instance to use, if initialized.
+        /// </summary>
+        private ServiceProvider? serviceProvider;
+
+        /// <inheritdoc/>
+        object? IServiceProvider.GetService(Type serviceType)
+        {
+            // As per section I.12.6.6 of the official CLI ECMA-335 spec:
+            // "[...] read and write access to properly aligned memory locations no larger than the native
+            // word size is atomic when all the write accesses to a location are the same size. Atomic writes
+            // shall alter no bits other than those written. Unless explicit layout control is used [...],
+            // data elements no larger than the natural word size [...] shall be properly aligned.
+            // Object references shall be treated as though they are stored in the native word size."
+            // The field being accessed here is of native int size (reference type), and is only ever accessed
+            // directly and atomically by a compare exhange instruction (see below), or here. We can therefore
+            // assume this read is thread safe with respect to accesses to this property or to invocations to one
+            // of the available configuration methods. So we can just read the field directly and make the necessary
+            // check with our local copy, without the need of paying the locking overhead from this get accessor.
+            ServiceProvider? provider = this.serviceProvider;
+
+            if (provider is null)
+            {
+                ThrowInvalidOperationExceptionForMissingInitialization();
+            }
+
+            return provider!.GetService(serviceType);
+        }
+
+        /// <summary>
+        /// Initializes the shared <see cref="IServiceProvider"/> instance.
+        /// </summary>
+        /// <param name="setup">The configuration delegate to use to add services.</param>
+        public void ConfigureServices(Action<IServiceCollection> setup)
+        {
+            ConfigureServices(setup, new ServiceProviderOptions());
+        }
+
+        /// <summary>
+        /// Initializes the shared <see cref="IServiceProvider"/> instance.
+        /// </summary>
+        /// <param name="setup">The configuration delegate to use to add services.</param>
+        /// <param name="options">The <see cref="ServiceProviderOptions"/> instance to configure the service provider behaviors.</param>
+        public void ConfigureServices(Action<IServiceCollection> setup, ServiceProviderOptions options)
+        {
+            var collection = new ServiceCollection();
+
+            setup(collection);
+
+            ConfigureServices(collection, options);
+        }
+
+        /// <summary>
+        /// Initializes the shared <see cref="IServiceProvider"/> instance.
+        /// </summary>
+        /// <param name="services">The input <see cref="IServiceCollection"/> instance to use.</param>
+        public void ConfigureServices(IServiceCollection services)
+        {
+            ConfigureServices(services, new ServiceProviderOptions());
+        }
+
+        /// <summary>
+        /// Initializes the shared <see cref="IServiceProvider"/> instance.
+        /// </summary>
+        /// <param name="services">The input <see cref="IServiceCollection"/> instance to use.</param>
+        /// <param name="options">The <see cref="ServiceProviderOptions"/> instance to configure the service provider behaviors.</param>
+        public void ConfigureServices(IServiceCollection services, ServiceProviderOptions options)
+        {
+            ServiceProvider newServices = services.BuildServiceProvider(options);
+
+            ServiceProvider? oldServices = Interlocked.CompareExchange(ref this.serviceProvider, newServices, null);
+
+            if (!(oldServices is null))
+            {
+                ThrowInvalidOperationExceptionForRepeatedConfiguration();
+            }
+        }
+
+        /// <summary>
+        /// Throws an <see cref="InvalidOperationException"/> when the <see cref="ServiceProvider"/> property is used before initialization.
+        /// </summary>
+        private static void ThrowInvalidOperationExceptionForMissingInitialization()
+        {
+            throw new InvalidOperationException("The service provider has not been configured yet");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="InvalidOperationException"/> when a configuration is attempted more than once.
+        /// </summary>
+        private static void ThrowInvalidOperationExceptionForRepeatedConfiguration()
+        {
+            throw new InvalidOperationException("The default service provider has already been configured");
+        }
+    }
+}