New Win32 toast notification helpers (no more shortcut needed!) (#3457)

## Fixes #

**Dramatic Win32 improvements!** It's finally effortless for Win32 apps now!

* **No longer need a start menu shortcut!** - This was the biggest complaint
* **COM activator is automatically registered** - Simply subscribe to the OnActivated callback

**Before for Win32 apps**

1. Generate a new GUID and AUMID
1. Update your shortcut to use your GUID and AUMID
1. Create a NotificationActivator class using your GUID
1. Register your AUMID and COM server
1. Register your activator
1. You can finally now send notifications

```csharp
// (Omitted - setting up your shortcut using your installer)

// Register AUMID and COM server
DesktopNotificationManagerCompat.RegisterAumidAndComServer<MyNotificationActivator>("YourCompany.YourApp");

// Register COM server and activator type
DesktopNotificationManagerCompat.RegisterActivator<MyNotificationActivator>();

// The GUID CLSID must be unique to your app. Create a new GUID if copying this code.
[ClassInterface(ClassInterfaceType.None)]
[ComSourceInterfaces(typeof(INotificationActivationCallback))]
[Guid("replaced-with-your-guid-C173E6ADF0C3"), ComVisible(true)]
public class MyNotificationActivator : NotificationActivator
{
    public override void OnActivated(string invokedArgs, NotificationUserInput userInput, string appUserModelId)
    {
        // TODO: Handle activation
    }
}

// Finally can send...
```

**After for Win32 apps**

1. Send a notification! Literally just install the package and send away. To receive activation, subscribe to OnActivated. No GUIDs, no AUMIDs, all super straightforward.

```csharp
new ToastContentBuilder()
    .AddText("Hello world")
    .Show();

// Listen to toast notification activations
ToastNotificationManagerCompat.OnActivated += e =>
{
    // TODO: Handle activation
}
```

**Also simplifies the APIs for showing toasts!** New Show() and Schedule() methods on ToastContentBuilder to simplify showing toasts.

**Before**

```csharp
var content = new ToastContentBuilder()
    .AddText("Hello world")
    .GetToastContent();

var notif = new ToastNotification(content.GetXml());

ToastNotificationManager.CreateToastNotifier().Show(notif);
```

**After**

(Plus now both Win32 and UWP can use the exact same API)

```csharp
new ToastContentBuilder()
    .AddText("Hello world")
    .Show();
```

Customization of the toast notification can still be done using an overload

```csharp
new ToastContentBuilder()
    .AddText("Hello world")
    .Show(notif =>
    {
        notif.Tag = "myTag";
    });
```

Also on ToastContentBuilder *added*... `.AddToastActivationInfo("myArgs")` defaults to Foreground so don't have to specify that 95% of the time, also added option for adding a ToastAudio object `AddAudio(new ToastAudio())` (useful for if you want to specify a silent toast, otherwise that's impossible today).

## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->

<!-- - Bugfix -->
Feature
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->


## What is the current behavior?
<!-- Please describe the current behavior that you are modifying, or link to a relevant issue. -->

See above


## What is the new behavior?
<!-- Describe how was this issue resolved or changed? -->

See above. Can now send toasts without having to set up a start menu shortcut... in fact, can send notifications without setting up anything!

### High level changes

* New `Show()` method added to `ToastContentBuilder` for easily showing a toast (works with Win32 apps too)
* New `Schedule()` method added to `ToastContentBuilder` for easily scheduling a toast (works with Win32 apps too)
* New `ToastNotificationManagerCompat` class added for converging Win32 and UWP API surface, and drastically simplifying sending toasts from Win32 (no longer need start menu shortcut, don't need to create the COM activator)
* New `GetXml()` method added to `ToastContentBuilder` for obtaining XML without having to call `GetToastContent().GetXml()`
* Made the activationType optional in `AddToastActivationInfo` so can set foreground activation more concisely (95% of time it's foreground activation)
* Added a `ToastAudio` overload for `AddAudio` so can set silent audio
* C++ UWP support for ToastContentBuilder class
* `ToastArguments` is now part of the toolkit (don't need to use an external query string library)

The `DesktopNotificationManagerCompat` classes have been left identical for back-compat purposes. When developers update their package, they do NOT have to make any changes if they don't want to. There are [migration steps described here](https://review.docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/migrating-to-toastcompat?branch=aleader%2Fconverged-uwp-win32&tabs=uwp).

## PR Checklist

Please check if your PR fulfills the following requirements:

- [x] Tested code with current [supported SDKs](../readme.md#supported)
- [x] Tested with sparse-signed package
- [x] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). [Preview docs](https://docstaging.z5.web.core.windows.net/aleader/toolkit-7/design/shell/tiles-and-notifications/send-local-toast.html?tabs=uwp)
- [x] Sample in sample app has been added / updated (for bug fixes / features)
    - [x] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)
- [x] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [x] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [x] Contains **NO** breaking changes

<!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. 
     Please note that breaking changes are likely to be rejected. -->


## How verified

* Tested NuGet package from CI server on all test apps within here: https://github.com/andrewleader/NotifTestApps
  * Includes UWP, .NET Core, and .NET Framework apps, and legacy versions of .NET Core and .NET Framework apps for testing back-compat and zero breaking changes
  * Tested on commit 04a7e71
* Also tested with sparse signed package sample

Author: msftbot[bot]

Microsoft.Toolkit.Uwp.Notifications/Adaptive/AdaptiveProgressBarValue.cs

@@ -11,6 +11,11 @@ namespace Microsoft.Toolkit.Uwp.Notifications
     /// </summary>
     public sealed class AdaptiveProgressBarValue
     {
+        /// <summary>
+        /// Gets or sets the property name to bind to.
+        /// </summary>
+        public string BindingName { get; set; }
+
         /// <summary>
         /// Gets or sets the value (0-1) representing the percent complete.
         /// </summary>
@@ -35,6 +40,11 @@ internal string ToXmlString()
                 return "indeterminate";
             }
 
+            if (BindingName != null)
+            {
+                return "{" + BindingName + "}";
+            }
+
             return Value.ToString();
         }
 
@@ -69,5 +79,18 @@ public static AdaptiveProgressBarValue FromValue(double d)
                 Value = d
             };
         }
+
+        /// <summary>
+        /// Returns a progress bar value using the specified binding name.
+        /// </summary>
+        /// <param name="bindingName">The property to bind to.</param>
+        /// <returns>A progress bar value.</returns>
+        public static AdaptiveProgressBarValue FromBinding(string bindingName)
+        {
+            return new AdaptiveProgressBarValue()
+            {
+                BindingName = bindingName
+            };
+        }
     }
 }

Microsoft.Toolkit.Uwp.Notifications/Microsoft.Toolkit.Uwp.Notifications.csproj

@@ -25,23 +25,17 @@
       </ItemGroup>
       <PropertyGroup>
         <!--Define the WINDOWS_UWP conditional symbol, since the Windows.Data.Xml and the Windows.UI.Notification namespaces are available-->
-        <DefineConstants>$(DefineConstants);WINDOWS_UWP</DefineConstants>
+        <DefineConstants>$(DefineConstants);WINDOWS_UWP;WIN32</DefineConstants>
       </PropertyGroup>
     </When>
 
-    <!--Non-desktop apps (UWP, libraries, ASP.NET servers)-->
-    <Otherwise>
-      <ItemGroup>
-        <!--Remove the DesktopNotificationManager code-->
-        <Compile Remove="DesktopNotificationManager\**\*" />
-      </ItemGroup>
-    </Otherwise>
-
   </Choose>
 
-  <!--NET Core desktop apps also need the Registry NuGet package-->
+  <!--NET Core desktop apps also need the Registry NuGet package and System.Reflection.Emit for generating COM class dynamically-->
   <ItemGroup Condition="'$(TargetFramework)'=='netcoreapp3.1'">
     <PackageReference Include="Microsoft.Win32.Registry" Version="4.7.0" />
+    <PackageReference Include="System.Reflection.Emit" Version="4.7.0" />
+    <PackageReference Include="System.Drawing.Common" Version="4.7.0" />
   </ItemGroup>
 
   <ItemGroup Condition=" '$(TargetFramework)' == 'native' ">

Microsoft.Toolkit.Uwp.Notifications/Tiles/TileCommon.cs

@@ -15,21 +15,21 @@ public enum TileSize
         /// <summary>
         /// Small Square Tile
         /// </summary>
-        Small = 0,
+        Small = 1,
 
         /// <summary>
         /// Medium Square Tile
         /// </summary>
-        Medium = 1,
+        Medium = 2,
 
         /// <summary>
         /// Wide Rectangle Tile
         /// </summary>
-        Wide = 2,
+        Wide = 4,
 
         /// <summary>
         /// Large Square Tile
         /// </summary>
-        Large = 4
+        Large = 8
     }
 }

Microsoft.Toolkit.Uwp.Notifications/Toasts/Builder/CustomizeToast.cs

@@ -0,0 +1,39 @@
+// 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.
+
+#if WINDOWS_UWP
+
+using Windows.Foundation;
+using Windows.UI.Notifications;
+
+namespace Microsoft.Toolkit.Uwp.Notifications
+{
+    /// <summary>
+    /// Allows you to set additional properties on the <see cref="ToastNotification"/> object before the toast is displayed.
+    /// </summary>
+    /// <param name="toast">The toast to modify that will be displayed.</param>
+    public delegate void CustomizeToast(ToastNotification toast);
+
+    /// <summary>
+    /// Allows you to set additional properties on the <see cref="ToastNotification"/> object before the toast is displayed.
+    /// </summary>
+    /// <param name="toast">The toast to modify that will be displayed.</param>
+    /// <returns>An operation.</returns>
+    public delegate IAsyncAction CustomizeToastAsync(ToastNotification toast);
+
+    /// <summary>
+    /// Allows you to set additional properties on the <see cref="ScheduledToastNotification"/> object before the toast is scheduled.
+    /// </summary>
+    /// <param name="toast">The scheduled toast to modify that will be scheduled.</param>
+    public delegate void CustomizeScheduledToast(ScheduledToastNotification toast);
+
+    /// <summary>
+    /// Allows you to set additional properties on the <see cref="ScheduledToastNotification"/> object before the toast is scheduled.
+    /// </summary>
+    /// <param name="toast">The scheduled toast to modify that will be scheduled.</param>
+    /// <returns>An operation.</returns>
+    public delegate IAsyncAction CustomizeScheduledToastAsync(ScheduledToastNotification toast);
+}
+
+#endif

Microsoft.Toolkit.Uwp.Notifications/Toasts/Builder/ToastContentBuilder.Actions.cs

@@ -8,13 +8,16 @@
 
 namespace Microsoft.Toolkit.Uwp.Notifications
 {
-#if !WINRT
 #pragma warning disable SA1008
 #pragma warning disable SA1009
     /// <summary>
     /// Builder class used to create <see cref="ToastContent"/>
     /// </summary>
-    public partial class ToastContentBuilder
+    public
+#if WINRT
+        sealed
+#endif
+        partial class ToastContentBuilder
     {
         private IToastActions Actions
         {
@@ -45,6 +48,36 @@ private IList<IToastInput> InputList
             }
         }
 
+        private string SerializeArgumentsIncludingGeneric(ToastArguments arguments)
+        {
+            if (_genericArguments.Count == 0)
+            {
+                return arguments.ToString();
+            }
+
+            foreach (var genericArg in _genericArguments)
+            {
+                if (!arguments.Contains(genericArg.Key))
+                {
+                    arguments.Add(genericArg.Key, genericArg.Value);
+                }
+            }
+
+            return arguments.ToString();
+        }
+
+        /// <summary>
+        /// Add a button to the current toast.
+        /// </summary>
+        /// <param name="content">Text to display on the button.</param>
+        /// <param name="activationType">Type of activation this button will use when clicked. Defaults to Foreground.</param>
+        /// <param name="arguments">App-defined string of arguments that the app can later retrieve once it is activated when the user clicks the button.</param>
+        /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
+        public ToastContentBuilder AddButton(string content, ToastActivationType activationType, string arguments)
+        {
+            return AddButton(content, activationType, arguments, default);
+        }
+
         /// <summary>
         /// Add a button to the current toast.
         /// </summary>
@@ -53,15 +86,18 @@ private IList<IToastInput> InputList
         /// <param name="arguments">App-defined string of arguments that the app can later retrieve once it is activated when the user clicks the button.</param>
         /// <param name="imageUri">Optional image icon for the button to display (required for buttons adjacent to inputs like quick reply).</param>
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
-        public ToastContentBuilder AddButton(string content, ToastActivationType activationType, string arguments, Uri imageUri = default(Uri))
+#if WINRT
+        [Windows.Foundation.Metadata.DefaultOverload]
+#endif
+        public ToastContentBuilder AddButton(string content, ToastActivationType activationType, string arguments, Uri imageUri)
         {
             // Add new button
             ToastButton button = new ToastButton(content, arguments)
             {
                 ActivationType = activationType
             };
 
-            if (imageUri != default(Uri))
+            if (imageUri != default)
             {
                 button.ImageUri = imageUri.OriginalString;
             }
@@ -76,17 +112,46 @@ private IList<IToastInput> InputList
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
         public ToastContentBuilder AddButton(IToastButton button)
         {
+            if (button is ToastButton toastButton && toastButton.Content == null)
+            {
+                throw new InvalidOperationException("Content is required on button.");
+            }
+
             // List has max 5 buttons
             if (ButtonList.Count == 5)
             {
                 throw new InvalidOperationException("A toast can't have more than 5 buttons");
             }
 
+            if (button is ToastButton b && b.CanAddArguments())
+            {
+                foreach (var arg in _genericArguments)
+                {
+                    if (!b.ContainsArgument(arg.Key))
+                    {
+                        b.AddArgument(arg.Key, arg.Value);
+                    }
+                }
+            }
+
             ButtonList.Add(button);
 
             return this;
         }
 
+        /// <summary>
+        /// Add an button to the toast that will be display to the right of the input text box, achieving a quick reply scenario.
+        /// </summary>
+        /// <param name="textBoxId">ID of an existing <see cref="ToastTextBox"/> in order to have this button display to the right of the input, achieving a quick reply scenario.</param>
+        /// <param name="content">Text to display on the button.</param>
+        /// <param name="activationType">Type of activation this button will use when clicked. Defaults to Foreground.</param>
+        /// <param name="arguments">App-defined string of arguments that the app can later retrieve once it is activated when the user clicks the button.</param>
+        /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
+        public ToastContentBuilder AddButton(string textBoxId, string content, ToastActivationType activationType, string arguments)
+        {
+            return AddButton(textBoxId, content, activationType, arguments, default);
+        }
+
         /// <summary>
         /// Add an button to the toast that will be display to the right of the input text box, achieving a quick reply scenario.
         /// </summary>
@@ -96,7 +161,7 @@ public ToastContentBuilder AddButton(IToastButton button)
         /// <param name="arguments">App-defined string of arguments that the app can later retrieve once it is activated when the user clicks the button.</param>
         /// <param name="imageUri">An optional image icon for the button to display (required for buttons adjacent to inputs like quick reply)</param>
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
-        public ToastContentBuilder AddButton(string textBoxId, string content, ToastActivationType activationType, string arguments, Uri imageUri = default(Uri))
+        public ToastContentBuilder AddButton(string textBoxId, string content, ToastActivationType activationType, string arguments, Uri imageUri)
         {
             // Add new button
             ToastButton button = new ToastButton(content, arguments)
@@ -105,38 +170,70 @@ public ToastContentBuilder AddButton(IToastButton button)
                 TextBoxId = textBoxId
             };
 
-            if (imageUri != default(Uri))
+            if (imageUri != default)
             {
                 button.ImageUri = imageUri.OriginalString;
             }
 
             return AddButton(button);
         }
 
+#if WINRT
+        /// <summary>
+        /// Add an input text box that the user can type into.
+        /// </summary>
+        /// <param name="id">Required ID property so that developers can retrieve user input once the app is activated.</param>
+        /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
+        public ToastContentBuilder AddInputTextBox(string id)
+        {
+            return AddInputTextBox(id, default, default);
+        }
+
+        /// <summary>
+        /// Add an input text box that the user can type into.
+        /// </summary>
+        /// <param name="id">Required ID property so that developers can retrieve user input once the app is activated.</param>
+        /// <param name="placeHolderContent">Placeholder text to be displayed on the text box when the user hasn't typed any text yet.</param>
+        /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
+        public ToastContentBuilder AddInputTextBox(string id, string placeHolderContent)
+        {
+            return AddInputTextBox(id, placeHolderContent, default);
+        }
+#endif
+
         /// <summary>
         /// Add an input text box that the user can type into.
         /// </summary>
         /// <param name="id">Required ID property so that developers can retrieve user input once the app is activated.</param>
         /// <param name="placeHolderContent">Placeholder text to be displayed on the text box when the user hasn't typed any text yet.</param>
         /// <param name="title">Title text to display above the text box.</param>
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
-        public ToastContentBuilder AddInputTextBox(string id, string placeHolderContent = default(string), string title = default(string))
+        public ToastContentBuilder AddInputTextBox(
+            string id,
+#if WINRT
+            string placeHolderContent,
+            string title)
+#else
+            string placeHolderContent = default,
+            string title = default)
+#endif
         {
             var inputTextBox = new ToastTextBox(id);
 
-            if (placeHolderContent != default(string))
+            if (placeHolderContent != default)
             {
                 inputTextBox.PlaceholderContent = placeHolderContent;
             }
 
-            if (title != default(string))
+            if (title != default)
             {
                 inputTextBox.Title = title;
             }
 
             return AddToastInput(inputTextBox);
         }
 
+#if !WINRT
         /// <summary>
         /// Add a combo box / drop-down menu that contain options for user to select.
         /// </summary>
@@ -145,7 +242,7 @@ public ToastContentBuilder AddButton(IToastButton button)
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
         public ToastContentBuilder AddComboBox(string id, params (string comboBoxItemId, string comboBoxItemContent)[] choices)
         {
-            return AddComboBox(id, default(string), choices);
+            return AddComboBox(id, default, choices);
         }
 
         /// <summary>
@@ -157,7 +254,7 @@ public ToastContentBuilder AddComboBox(string id, params (string comboBoxItemId,
         /// <returns>The current instance of <see cref="ToastContentBuilder"/></returns>
         public ToastContentBuilder AddComboBox(string id, string defaultSelectionBoxItemId, params (string comboBoxItemId, string comboBoxItemContent)[] choices)
         {
-            return AddComboBox(id, default(string), defaultSelectionBoxItemId, choices);
+            return AddComboBox(id, default, defaultSelectionBoxItemId, choices);
         }
 
         /// <summary>
@@ -185,12 +282,12 @@ public ToastContentBuilder AddComboBox(string id, string title, string defaultSe
         {
             var box = new ToastSelectionBox(id);
 
-            if (defaultSelectionBoxItemId != default(string))
+            if (defaultSelectionBoxItemId != default)
             {
                 box.DefaultSelectionBoxItemId = defaultSelectionBoxItemId;
             }
 
-            if (title != default(string))
+            if (title != default)
             {
                 box.Title = title;
             }
@@ -203,6 +300,7 @@ public ToastContentBuilder AddComboBox(string id, string title, string defaultSe
 
             return AddToastInput(box);
         }
+#endif
 
         /// <summary>
         /// Add an input option to the Toast.
@@ -218,5 +316,4 @@ public ToastContentBuilder AddToastInput(IToastInput input)
     }
 #pragma warning restore SA1008
 #pragma warning restore SA1009
-#endif
 }