Freigeben über

App-Benachrichtigungen von UWP zu WinUI 3-Migration

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

Note

Der Begriff „Toast-Benachrichtigung“ wird durch „App-Benachrichtigung“ ersetzt. Diese Begriffe beziehen sich beide auf dasselbe Feature von Windows, aber im Laufe der Zeit werden wir die Verwendung von „Toast-Benachrichtigung“ in der Dokumentation auslaufen lassen.

Note

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

Category UWP WinUI
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.
Fensteraktivierung 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-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-Visual Studio project-Vorlagen 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 für windows.toastNotificationActivation, um die CLSID Ihres Toast-Benachrichtigungsaktivators zu deklarieren (mithilfe einer neuen GUID Ihrer Wahl).
  5. Nur MSIX: com:Extension für den COM-Aktivator unter Verwendung der GUID aus Schritt #4. Stellen Sie sicher, dass Sie Arguments="----AppNotificationActivated:" einfügen, damit Sie wissen, dass Ihr Start über eine Benachrichtigung erfolgt ist.
<!--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: Verwaltung 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 die Aktivierungsart nicht AppNotification ist, rufen Sie die Hilfsmethode LaunchAndBringToForegroundIfNeeded auf.
  8. Wenn die Aktivierungsart AppNotification ist, konvertieren Sie die Eigenschaft AppActivationArguments.Data zu einem AppNotificationActivatedEventArgs 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 dem App- oder Window-Dispatcher übergeben, bevor Sie UI-bezogenen Code ausführen, wie 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
  {
      if (args.Argument.Contains("action"))
      {
          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;
          }
      }
      else
      {
          Debug.Print("Notification args is null");
      }
  });
}

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 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 Klasse ToastContentBuilder 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());
  • Last updated on