Merge branch 'master' into i17-MigrateMvvmBasic

Author: mrlacey

CHANGELOG.md

@@ -0,0 +1,96 @@
+# API changes in Preview 3:
+
+🆕 New `ObservableValidator` class, which supports the [`INotifyDataErrorInfo`](https://docs.microsoft.com/dotnet/api/system.componentmodel.inotifydataerrorinfo) interface.
+
+🆕 Added new constructors with cancellation support to the async commands, and added new cancellation-related properties to the async command interfaces.
+
+🆕 Added a new `WeakReferenceMessenger` type. This type is less performant than the other messenger, and uses more memory, and in return only uses weak references to track recipients. This type essentially mirrors the behavior of the `Messenger` type from `MvvmLight`, making the transition easier for developers migrating from that library.
+
+🆕 Introduced a new custom delegate to represent message handlers, which also receives the current recipient as additional input parameter (💥 breaking change, see code changes below).
+
+✅ Renamed `Messenger` to `StrongReferenceMessenger` (💥).
+
+✅ The `WeakReferenceMessenger` is now the default messenger used by the `ObservableRecipient` class (💥).
+
+✅ Changed `ObservableObject` overloads using `Expression<Func<T>>` to be more efficient (💥).
+
+✅ API changes to the `SetPropertyAndNotifyOnCompletion` (as detailed in [this blog post]( https://devblogs.microsoft.com/pax-windows/mvvm-toolkit-preview-3-the-journey-of-an-api/), 💥).
+
+🚨 Removed the `Ioc` class (we will include docs on how to easily start using the `Microsoft.Extensions.DependencyInjection` library directly to work with dependency injection, 💥).
+
+## Breaking changes
+
+💥 If you were registering message handlers, no API changes are required for messages registered through the `IRecipient<TMessage>` interface. If you were manually registering handlers with the `Action<TMessage>` delegate instead, you will need to modify their code as follows:
+
+```cs
+// Preview 2
+Messenger.Register<MyMessage>(this, message =>
+{
+    // Do stuff with the message here...
+    // Note that invoking this instance method means that
+    // the lambda expression is also capturing "this".
+    // This issue was also present in MvvmLight.
+    SomeInstanceMethod();
+});
+
+// Preview 3
+Messenger.Register<MyViewModel, MyMessage>(this, (recipient, message) =>
+{
+    // Do stuff here...
+    // Note that since we're accessing the recipient from the
+    // input parameter, the lambda expression is not capturing
+    // anything anymore, which allows the C# compiler to cache it.
+    // Note that we can still access all private members of the
+    // recipient from here, even if we're using the input parameter.
+    recipient.SomeInstanceMethod();
+});
+```
+
+💥 If you were directly referencing `Messenger.Default` to send messages (ie. outside of the `ObservableRecipient` class, which exposes a `Messenger` property which is unchanged), you'll need to replace that with either `WeakReferenceMessenger.Default` or `StrongReferenceMessenger.Default`, depending on the desired messenger to use.
+
+💥 If you want to use the `StrongReferenceMessenger` class for better performance, make sure to pass that to the constructor of the `ObservableRecipient` class, otherwise the `WeakReferenceMessenger.Default` instance will be used.
+
+💥 If you were using the `ObservableObject.SetProperty<T>(Expression<Func<T>>, ...)` overload, the code needs to be updated as follows to replace the LINQ expression with a stateless lambda expression:
+
+```cs
+private readonly User user;
+
+public string Name
+{
+    // Preview 2
+    set => SetProperty(() => user.Name, value);
+
+    // Preview 3
+    set => SetProperty(user.Name, value, user, (u, n) => u.Name = n);
+}
+```
+
+The syntax is slightly more complex, but results in a 150x speed improvement (that's not a typo), requires no memory allocations at all and no reflection, and ensures that all necessary validation of the arguments can be done at compile time too.
+
+💥 If you were using `SetPropertyAndNotifyOnCompletion`, change the code as follows:
+
+```csharp
+// Preview 2
+private Task<string> myTask;
+
+public Task<string> MyTask
+{
+     get => myTask;
+     set => SetPropertyAndNotifyOnCompletion(ref myTask, () => myTask, value);
+}
+
+// Preview 3
+private TaskNotifier<string> myTask;
+
+public Task<string> MyTask
+{
+    get => myTask;
+    set => SetPropertyAndNotifyOnCompletion(ref myTask, value);
+}
+```
+
+💥 If you were using the `Ioc` class, we will provide docs to illustrate how to setup a custom service container using the `Microsoft.Extensions.DependencyInjection` library soon. The temporary link with the preview docs for this is available [here](https://github.com/windows-toolkit/MVVM-Samples/blob/feature/preview2-update/docs/mvvm/Ioc.md).
+
+## Notes
+
+For additional info and discussion, see the related issue [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/3428).

docs/mvvm/AsyncRelayCommand.md

@@ -15,7 +15,8 @@ The [`AsyncRelayCommand`](https://docs.microsoft.com/dotnet/api/microsoft.toolki
 
 `AsyncRelayCommand` and `AsyncRelayCommand<T>` have the following main features:
 
-- They extend the functionalities of the non-asynchronous commands included in the library, with support for `Task`-returning delegates.
+- They extend the functionalities of the synchronous commands included in the library, with support for `Task`-returning delegates.
+- They can wrap asynchronous functions with an additional `CancellationToken` parameter to support cancelation, and they expose a `CanBeCanceled` and `IsCancellationRequested` properties, as well as a `Cancel` method.
 - They expose an `ExecutionTask` property that can be used to monitor the progress of a pending operation, and an `IsRunning` that can be used to check when an operation completes. This is particularly useful to bind a command to UI elements such as loading indicators.
 - They implement the `IAsyncRelayCommand` and `IAsyncRelayCommand<T>` interfaces, which means that viewmodel can easily expose commands using these to reduce the tight coupling between types. For instance, this makes it easier to replace a command with a custom implementation exposing the same public API surface, if needed.
 

docs/mvvm/Ioc.md

@@ -1,47 +1,82 @@
 ---
 title: Ioc
 author: Sergio0694
-description: A type that facilitates the use of the IServiceProvider type
+description: An introduction to the use of the IServiceProvider type through the Microsoft.Extensions.DependencyInjection APIs
 keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, mvvm, service, dependency injection, net core, net standard
 dev_langs:
   - csharp
 ---
 
 # Ioc ([Inversion of control](https://en.wikipedia.org/wiki/Inversion_of_control))
 
-The [`Ioc`](https://docs.microsoft.com/dotnet/api/microsoft.toolkit.mvvm.DependencyInjection.Ioc) class is a type that facilitates the use of the `IServiceProvider` type. It's powered by the `Microsoft.Extensions.DependencyInjection` package, which provides a fully featured and powerful DI set of APIs, and acts as an easy to setup and use `IServiceProvider`.
+A common pattern that can be used to increase modularity in the codebase of an application using the MVVM pattern is to use some form of inversion of control. One of the most common solution in particular is to use dependency injection, which consists in creating a number of services that are injected into backend classes (ie. passed as parameters to the viewmodel constructors) - this allows code using these services not to rely on implementation details of these services, and it also makes it easy to swap the concrete implementations of these services. This pattern also makes it easy to make platform-specific features available to backend code, by abstracting them through a service which is then injected where needed.
+
+The MVVM Toolkit doesn't provide built-in APIs to facilitate the usage of this pattern, as there already exist dedicated libraries specifically for this such as the `Microsoft.Extensions.DependencyInjection` package, which provides a fully featured and powerful DI set of APIs, and acts as an easy to setup and use `IServiceProvider`. The following guide will refer to this library and provide a series of examples of how to integrate it into applications using the MVVM pattern.
 
 ## Configure and resolve services
 
-The main entry point is the `ConfigureServices` method, which can be used like so:
+The first step is to declare an `IServiceProvider` instance, and to initialize all the necessary services, usually at startup. For instance, on UWP (but a similar setup can be used on other frameworks too):
 
 ```csharp
-// Register the services at startup
-Ioc.Default.ConfigureServices(services =>
+public sealed partial class App : Application
 {
-    services.AddSingleton<IFilesService, FilesService>();
-    services.AddSingleton<ISettingsService, SettingsService>();
-    // Other services here...
-});
+    public App()
+    {
+        Services = ConfigureServices();
+
+        this.InitializeComponent();
+    }
+
+    /// <summary>
+    /// Gets the current <see cref="App"/> instance in use
+    /// </summary>
+    public new static App Current => (App)Application.Current;
+
+    /// <summary>
+    /// Gets the <see cref="IServiceProvider"/> instance to resolve application services.
+    /// </summary>
+    public IServiceProvider Services { get; }
+
+    /// <summary>
+    /// Configures the services for the application.
+    /// </summary>
+    private static IServiceProvider ConfigureServices()
+    {
+        var services = new ServiceCollection();
+
+        services.AddSingleton<IFilesService, FilesService>();
+        services.AddSingleton<ISettingsService, SettingsService>();
+        services.AddSingleton<IClipboardService, ClipboardService>();
+        services.AddSingleton<IShareService, ShareService>();
+        services.AddSingleton<IEmailService, EmailService>();
 
-// Retrieve a service instance when needed
-IFilesService fileService = Ioc.Default.GetService<IFilesService>();
+        return services.BuildServiceProvider();
+    }
+}
 ```
 
-The `Ioc.Default` property offers a thread-safe `IServiceProvider` instance that can be used anywhere in the application to resolve services. The `ConfigureService` method handles the initialization of that service. It is also possible to create different `Ioc` instances and to initialize each with different services.
+Here the `Services` property is initialized at startup, and all the application services and viewmodels are registered. There is also a new `Current` property that can be used to easily access the `Services` property from other views in the application. For instance:
+
+```csharp
+IFilesService filesService = App.Current.Services.GetService<IFilesService>();
+
+// Use the files service here...
+```
+
+The key aspect here is that each service may very well be using platform-specific APIs, but since those are all abstracted away through the interface our code is using, we don't need to worry about them whenever we're just resolving an instance and using it to perform operations.
 
 ## Constructor injection
 
 One powerful feature that is available is "constructor injection", which means that the DI service provider is able to automatically resolve indirect dependencies between registered services when creating instances of the type being requested. Consider the following service:
 
 ```csharp
-public class ConsoleLogger : ILogger
+public class FileLogger : IFileLogger
 {
-    private readonly IFileService FileService;
+    private readonly IFilesService FileService;
     private readonly IConsoleService ConsoleService;
 
-    public ConsoleLogger(
-        IFileService fileService,
+    public FileLogger(
+        IFilesService fileService,
         IConsoleService consoleService)
     {
         FileService = fileService;
@@ -52,22 +87,61 @@ public class ConsoleLogger : ILogger
 }
 ```
 
-Here we have a `ConsoleLogger` implementing the `ILogger` interface, and requiring `IFileService` and `IConsoleService` instances. Constructor injection means the DI service provider will "automagically" gather all the necessary services, like so:
+Here we have a `FileLogger` type implementing the `IFileLogger` interface, and requiring `IFilesService` and `IConsoleService` instances. Constructor injection means the DI service provider will automatically gather all the necessary services, like so:
 
 ```csharp
-// Register the services at startup
-Ioc.Default.ConfigureServices(services =>
+/// <summary>
+/// Configures the services for the application.
+/// </summary>
+private static IServiceProvider ConfigureServices()
 {
-    services.AddSingleton<IFileService, FileService>();
+    var services = new ServiceCollection();
+
+    services.AddSingleton<IFilesService, FilesService>();
     services.AddSingleton<IConsoleService, ConsoleService>();
-    services.AddSingleton<ILogger, ConsoleLogger>();
-});
+    services.AddSingleton<IFileLogger, FileLogger>();
+
+    return services.BuildServiceProvider();
+}
 
 // Retrieve a logger service with constructor injection
-ILogger consoleLogger = Ioc.Default.GetService<ILogger>();
+IFileLogger fileLogger = App.Current.Services.GetService<IFileLogger>();
+```
+
+The DI service provider will automatically check whether all the necessary services are registered, then it will retrieve them and invoke the constructor for the registered `IFileLogger` concrete type, to get the instance to return.
+
+## What about viewmodels?
+
+A service provider has "service" in its name, but it can actually be used to resolve instances of any class, including viewmodels! The same concepts explained above still apply, including constructor injection. Imagine we had a `ContactsViewModel` type, using an `IContactsService` and an `IPhoneService` instance through its constructor. We could have a `ConfigureServices` method like this:
+
+```csharp
+/// <summary>
+/// Configures the services for the application.
+/// </summary>
+private static IServiceProvider ConfigureServices()
+{
+    var services = new ServiceCollection();
+
+    // Services
+    services.AddSingleton<IContactsService, ContactsService>();
+    services.AddSingleton<IPhoneService, PhoneService>();
+
+    // Viewmodels
+    services.AddTransient<ContactsViewModel>();
+
+    return services.BuildServiceProvider();
+}
 ```
 
-The DI service provider will automatically check whether all the necessary services are registered, then it will retrieve them and invoke the constructor for the registered `ILogger` concrete type, to get the instance to return - all done automatically!
+And then in our `ContactsView`, we would assign the data context as follows:
+
+```csharp
+public ContactsView()
+{
+    this.InitializeComponent();
+    this.DataContext = App.Current.Services.GetService<ContactsViewModel>();
+}
+```
 
 ## More docs