Dela via

Appmeddelanden från UWP till WinUI 3-migrering

Den enda skillnaden när du migrerar appmeddelandekod från UWP till WinUI 3 är att hantera aktiveringen av meddelanden. Att skicka och hantera appaviseringar förblir exakt detsamma.

Note

Termen "toast-meddelande" ersätts med "appavisering". Dessa termer refererar båda till samma funktion i Windows, men med tiden kommer vi att fasa ut användningen av "popup-meddelande" i dokumentationen.

Note

Viss information gäller försläppt produkt, som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

Activation differences

Category UWP WinUI 3
Startpunkt för förgrundsaktivering OnActivated-metoden inne i App.xaml.cs anropas OnLaunched-metoden i App.xaml.cs anropas.
Startpunkt för bakgrundsaktivering Hanteras separat som en bakgrundsaktivitet Samma som förgrundsaktivering. OnLaunched-metoden i App.xaml.cs anropas. Använd GetActivatedEventArgs för att avgöra om appen ska startas helt eller bara hantera uppgiften och avslutas.
Window activation Fönstret förs automatiskt till förgrunden när förgrundsaktiveringen sker Du måste ta fönstret till förgrunden om du så önskar

Migrering för C#-appar

Steg 1: Installera NuGet-biblioteket

För en WinUI 3-app hanterar du aktivering för meddelanden med hjälp AppNotificationManager av klassen . Den här klassen tillhandahålls av Nuget-paketet Microsoft.WindowsAppSDK, som ingår som standard i WinUI 3 Visual Studio-projektmallarna.

Steg 2: Uppdatera manifestet

I Package.appxmanifest lägger du till:

  1. Deklaration för xmlns:com
  2. Deklaration för xmlns:desktop
  3. I attributet IgnorableNamespaces finns com och desktop
  4. desktop:Extension för windows.toastNotificationActivation för att deklarera din toast-aktiverare CLSID (med en ny GUID som du väljer).
  5. Endast MSIX: com:Extension för COM-aktivatorn med hjälp av GUID från steg 4. Se till att inkludera Arguments="----AppNotificationActivated:" så att du vet att din start kom från ett meddelande
<!--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>

Steg 3: Hantera aktivering

I appens startkod (vanligtvis App.xaml.cs) uppdaterar du koden med hjälp av följande steg:

  1. I OnLaunchedhämtar du standardinstansen av klassen AppNotificationManager.
  2. Registrera dig för AppNotificationManager.NotificationInvoked händelsen.
  3. Anropa Microsoft.Windows.AppNotifications.AppNotificationManager.Register för att registrera din app för att ta emot meddelandehändelser. Det är viktigt att du anropar den här metoden när du har registrerat NotificationInvoked hanteraren.
  4. Omstrukturera din start-/aktiveringskod för fönster till en dedikerad LaunchAndBringToForegroundIfNeeded hjälpmetod, så att du kan anropa den från flera platser.
  5. Skapa en HandleNotification hjälpmetod så att den kan anropas från flera platser.
  6. Anropa AppInstance.GetActivatedEventArgs och kontrollera egenskapen AppActivationArguments.Kind för det returnerade objektet för att se om värdet är ExtendedActivationKind.AppNotification.
  7. Om aktiveringstypen inte är AppNotification, anropa hjälpmetoden LaunchAndBringToForegroundIfNeeded.
  8. Om aktiveringstypen är AppNotification omvandla egenskapen AppActivationArguments.Data till en AppNotificationActivatedEventArgs- och skicka den till hjälpmetoden HandleNotification.
  9. I din ApplicationManager.NotificationInvoked-hanterare anropar du hjälpmetoden HandleNotification.
  10. I din HandleNotification hjälpmetod måste du skicka till app- eller fönsterdispatchern innan du kör gränssnittsrelaterad kod, t.ex. att visa ett fönster eller uppdatera användargränssnittet
  11. Migrera din gamla UWP-kod OnActivated som hanterade aktivering av appaviseringar till din nya HandleNotification hjälpmetod.

Migrated 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);
    }
}

Skapa innehåll för appaviseringar

Med Windows App SDK kan du fortfarande skapa appmeddelandeinnehåll med rå xml, men du kan också skapa appmeddelandeinnehåll med hjälp av det nya AppNotificationsBuilder-API :et som ersätter klassen ToastContentBuilder som tillhandahålls av Windows Community Toolkit. Skicka appmeddelandet genom att anropa AppNotificationManager.Show. Vi rekommenderar inte att du blandar API:er för Windows Community Toolkit och App SDK.

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());