Freigeben über

App-Benachrichtigungen von UWP zu WinUI 3-Migration

  • Artikel

Der einzige Unterschied beim Migrieren von App-Benachrichtigungscode von UWP zu WinUI 3 besteht in der Behandlung der Aktivierung von Benachrichtigungen. Das Senden und Verwalten von App-Benachrichtigungen bleibt identisch.

Hinweis

Der Begriff „Popupbenachrichtigung“ wird durch „App-Benachrichtigung“ ersetzt. Diese Begriffe beziehen sich beide auf das gleiche Feature von Windows, aber im Laufe der Zeit wird die Verwendung von „Popupbenachrichtigung“ in der Dokumentation auslaufen.

Hinweis

Einige Informationen beziehen sich auf Vorabversionen, die vor der kommerziellen Freigabe grundlegend geändert werden können. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Aktivierungsunterschiede

Kategorie UWP WinUI 3
Einstiegspunkt für die Vordergrundaktivierung OnActivated -Methode innerhalb App.xaml.cs wird aufgerufen OnLaunched -Methode innerhalb App.xaml.cs wird aufgerufen.
Einstiegspunkt für die Hintergrundaktivierung Separat als Hintergrundaufgabe behandelt Identisch mit der Vordergrundaktivierung. OnLaunched -Methode innerhalb App.xaml.cs wird aufgerufen. Verwenden Sie GetActivatedEventArgs , um zu ermitteln, ob die App die Aufgabe vollständig starten oder einfach verarbeiten und beenden soll.
Aktivieren von Fenstern Das Fenster wird automatisch in den Vordergrund gebracht, wenn die Vordergrundaktivierung eintritt. Sie müssen das Fenster bei Bedarf in den Vordergrund bringen.

Migration für C#-Apps

Schritt 1: Installieren der NuGet-Bibliothek

Bei einer WinUI 3-App behandeln Sie die Aktivierung für Benachrichtigungen mithilfe der AppNotificationManager-Klasse . Diese Klasse wird vom Microsoft.WindowsAppSDK Nuget-Paket bereitgestellt, das standardmäßig in den WinUI 3 Visual Studio-Projektvorlagen enthalten ist.

Schritt 2: Aktualisieren Des Manifests

Fügen Sie in Ihrem Package.appxmanifest Folgendes hinzu:

  1. Deklaration für xmlns:com
  2. Deklaration für xmlns:desktop
  3. Im Attribut IgnorableNamespaces, com und Desktop
  4. desktop:Extension for windows.toastNotificationActivation to declare your toast activator CLSID (using a new GUID of your choice).
  5. MSIX only: com:Extension for the COM activator using the GUID from step #4. Achten Sie darauf, dass Sie wissen Arguments="----AppNotificationActivated:" , dass Ihr Start über eine Benachrichtigung stammt.
<!--Add these namespaces-->
<Package
  ...
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  IgnorableNamespaces="... com desktop">
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

        <!--Specify which CLSID to activate when app notification clicked-->
        <desktop:Extension Category="windows.toastNotificationActivation">
          <desktop:ToastNotificationActivation ToastActivatorCLSID="replaced-with-your-guid-C173E6ADF0C3" /> 
        </desktop:Extension>

        <!--Register COM CLSID LocalServer32 registry key-->
        <com:Extension Category="windows.comServer">
          <com:ComServer>
            <com:ExeServer Executable="YourProject.exe" Arguments="----AppNotificationActivated:" DisplayName="App notification activator">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" DisplayName="App notification activator"/>
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>

      </Extensions>
    </Application>
  </Applications>
 </Package>

Schritt 3: Behandeln der Aktivierung

Aktualisieren Sie den Code im Startcode Ihrer App (in der Regel App.xaml.cs), indem Sie die folgenden Schritte ausführen:

  1. Rufen Sie in OnLaunched die Standardinstanz der AppNotificationManager-Klasse ab.
  2. Registrieren Sie sich für das Ereignis "AppNotificationManager.NotificationInvoked ".
  3. Rufen Sie Microsoft.Windows.AppNotifications.AppNotificationManager.Register auf, um Ihre App für den Empfang von Benachrichtigungsereignissen zu registrieren. Es ist wichtig, dass Sie diese Methode nach dem Registrieren des NotificationInvoked-Handlers aufrufen.
  4. Umgestalten Sie den Start-/Aktivierungscode ihres Fensters in eine dedizierte LaunchAndBringToForegroundIfNeeded Hilfsmethode, damit Sie ihn an mehreren Stellen aufrufen können.
  5. Erstellen Sie eine HandleNotification Hilfsmethode, damit sie an mehreren Stellen aufgerufen werden kann.
  6. Rufen Sie "AppInstance.GetActivatedEventArgs " auf, und überprüfen Sie die AppActivationArguments.Kind-Eigenschaft des zurückgegebenen Objekts auf den Wert "ExtendedActivationKind.AppNotification".
  7. Wenn es sich bei der Aktivierungsart nicht um AppNotification handelt, rufen Sie die LaunchAndBringToForegroundIfNeeded-Hilfsmethode auf.
  8. Wenn die Aktivierungsart "AppNotification" lautet, wandeln Sie die AppActivationArguments.Data-Eigenschaft in eine AppNotificationActivatedEventArgs um, und übergeben Sie sie an die HandleNotification Hilfsmethode.
  9. Rufen Sie in Ihrem ApplicationManager.NotificationInvoked-Handler die HandleNotification Hilfsmethode auf.
  10. Stellen Sie in Ihrer HandleNotification Hilfsmethode sicher, dass Sie an den App- oder Window-Dispatcher verteilen, bevor Sie ui-bezogene Code ausführen, z. B. ein Fenster anzeigen oder die Benutzeroberfläche aktualisieren.
  11. Migrieren Sie Ihren alten UWP-Code OnActivated , der die App-Benachrichtigungsaktivierung behandelt, zu Ihrer neuen HandleNotification Hilfsmethode.

Migrierte App.xaml.cs


protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    m_window = new MainWindow();

    // To ensure all Notification handling happens in this process instance, register for
    // NotificationInvoked before calling Register(). Without this a new process will
    // be launched to handle the notification.
    AppNotificationManager notificationManager = AppNotificationManager.Default;
    notificationManager.NotificationInvoked += NotificationManager_NotificationInvoked;
    notificationManager.Register();

    var activatedArgs = Microsoft.Windows.AppLifecycle.AppInstance.GetCurrent().GetActivatedEventArgs();
    var activationKind = activatedArgs.Kind;
    if (activationKind != ExtendedActivationKind.AppNotification)
    {
        LaunchAndBringToForegroundIfNeeded();
    } else
    {
        HandleNotification((AppNotificationActivatedEventArgs)activatedArgs.Data);
    }

}

private void LaunchAndBringToForegroundIfNeeded()
{
    if (m_window == null)
    {
        m_window = new MainWindow();
        m_window.Activate();

        // Additionally we show using our helper, since if activated via a app notification, it doesn't
        // activate the window correctly
        WindowHelper.ShowWindow(m_window);
    }
    else
    {
        WindowHelper.ShowWindow(m_window);
    }
}

private void NotificationManager_NotificationInvoked(AppNotificationManager sender, AppNotificationActivatedEventArgs args)
{
    HandleNotification(args);
}

private void HandleNotification(AppNotificationActivatedEventArgs args)
{
  // Use the dispatcher from the window if present, otherwise the app dispatcher
  var dispatcherQueue = m_window?.DispatcherQueue ?? DispatcherQueue.GetForCurrentThread();


  dispatcherQueue.TryEnqueue(async delegate
  {

      switch (args.Arguments["action"])
      {
          // Send a background message
          case "sendMessage":
              string message = args.UserInput["textBox"].ToString();
              // TODO: Send it

              // If the UI app isn't open
              if (m_window == null)
              {
                  // Close since we're done
                  Process.GetCurrentProcess().Kill();
              }

              break;

          // View a message
          case "viewMessage":

              // Launch/bring window to foreground
              LaunchAndBringToForegroundIfNeeded();

              // TODO: Open the message
              break;
      }
  });
}

private static class WindowHelper
{
    [DllImport("user32.dll")]
    private static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);

    [DllImport("user32.dll")]
    [return: MarshalAs(UnmanagedType.Bool)]
    private static extern bool SetForegroundWindow(IntPtr hWnd);

    public static void ShowWindow(Window window)
    {
        // Bring the window to the foreground... first get the window handle...
        var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(window);

        // Restore window if minimized... requires DLL import above
        ShowWindow(hwnd, 0x00000009);

        // And call SetForegroundWindow... requires DLL import above
        SetForegroundWindow(hwnd);
    }
}

Erstellen von App-Benachrichtigungsinhalten

Mit dem Windows App SDK können Sie weiterhin App-Benachrichtigungsinhalte mit unformatiertem XML erstellen. Sie können jedoch auch App-Benachrichtigungsinhalte mithilfe der neuen AppNotificationsBuilder-API erstellen, die die vom Windows Community Toolkit bereitgestellte ToastContentBuilder-Klasse ersetzt. Senden Sie die App-Benachrichtigung, indem Sie "AppNotificationManager.Show" aufrufen. Das Mischen von Windows Community Toolkit- und App SDK-APIs wird nicht empfohlen.

using Microsoft.Windows.AppNotifications;
using Microsoft.Windows.AppNotifications.Builder;

...

var builder = new AppNotificationBuilder()
    .AddText("Send a message.")
    .AddTextBox("textBox")
    .AddButton(new AppNotificationButton("Send")
        .AddArgument("action", "sendMessage"));

var notificationManager = AppNotificationManager.Default;
notificationManager.Show(builder.BuildNotification());