Freigeben über

Senden einer lokalen Popupbenachrichtigung aus C++-UWP-Apps

  • Artikel

Eine Popupbenachrichtigung ist eine Nachricht, die Ihre App erstellen und an Ihren Benutzer übermitteln kann, während er sich derzeit nicht in Ihrer App befindet.

Screenshot einer Popupbenachrichtigung

Diese Schnellstartanleitung führt Sie durch die Schritte zum Erstellen, Bereitstellen und Anzeigen einer Windows 10 oder Windows 11 Popupbenachrichtigung mithilfe von umfangreichen Inhalten und interaktiven Aktionen. In dieser Schnellstartanleitung werden lokale Benachrichtigungen verwendet, die die einfachste zu implementierende Benachrichtigung sind. Alle Arten von Apps (WPF, UWP, WinForms, Konsole) können Benachrichtigungen senden!

Wichtig

Wenn Sie eine C++-Nicht-UWP-App schreiben, lesen Sie die Dokumentation zu C++-WRL . Wenn Sie eine C#-App schreiben, lesen Sie die C#-Dokumentation.

Schritt 1: Installieren des NuGet-Pakets

Sie können Popupbenachrichtigungen mit der Generatorsyntax des Windows Community Toolkits (WCT) oder mit XML erstellen. Wenn Sie letzteres bevorzugen, fahren Sie mit Schritt 2 fort, und lesen Sie die Codebeispiele für die Syntax ohne Generator .

Klicken Sie in Ihrer Visual Studio-Projektmappe mit der rechten Maustaste auf Ihr Projekt, klicken Sie auf "NuGet-Pakete verwalten...", und suchen Sie nach dem NuGet-Paket version 7.0 oder höher, und installieren Sie esMicrosoft.Toolkit.Uwp.Notifications.

In unseren Syntaxcodebeispielen des Generators wird dieses Paket verwendet. Mit diesem Paket können Sie Popupbenachrichtigungen ohne XML erstellen.

Schritt 2: Hinzufügen von Namespacedeklarationen

using namespace Microsoft::Toolkit::Uwp::Notifications;

Schritt 3: Senden eines Popups

In Windows 10 und Windows 11 werden Ihre Popupbenachrichtigungsinhalte mit einer adaptiven Sprache beschrieben, die eine große Flexibilität beim Aussehen Ihrer Benachrichtigung ermöglicht. Weitere Informationen finden Sie in der Dokumentation zum Popupinhalt.

Wir beginnen mit einer einfachen textbasierten Benachrichtigung. Erstellen Sie den Benachrichtigungsinhalt (mithilfe der Benachrichtigungsbibliothek), und zeigen Sie die Benachrichtigung an! Beachten Sie, dass der Namespace ist Microsoft.Toolkit.Uwp.Notifications.

Einfache Textbenachrichtigung

Wenn Sie nicht die Syntax des WCT-Benachrichtigungs-Bibliotheks-Generators verwenden, erstellen Sie stattdessen die XML-Popupvorlage, füllen sie mit Text und Werten, erstellen die Benachrichtigung und zeigen sie an.

// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)
    ->AddText("Andrew sent you a picture")
    ->AddText("Check this out, The Enchantments in Washington!")
    ->Show();

Schritt 4: Behandeln der Aktivierung

Wenn der Benutzer auf Ihre Benachrichtigung (oder eine Schaltfläche in der Benachrichtigung mit Vordergrundaktivierung) klickt, wird die App.xaml.cppOnActivated Ihrer App aufgerufen.

App.xaml.cpp

void App::OnActivated(IActivatedEventArgs^ e)
{
    // Handle notification activation
    if (e->Kind == ActivationKind::ToastNotification)
    {
        ToastNotificationActivatedEventArgs^ toastActivationArgs = (ToastNotificationActivatedEventArgs^)e;

        // Obtain the arguments from the notification
        ToastArguments^ args = ToastArguments::Parse(toastActivationArgs->Argument);

        // Obtain any user input (text boxes, menu selections) from the notification
        auto userInput = toastActivationArgs->UserInput;
 
        // TODO: Show the corresponding content
    }
}

Wichtig

Sie müssen Ihren Frame initialisieren und Ihr Fenster wie Ihr OnLaunched-Code aktivieren. OnLaunched wird NICHT aufgerufen, wenn der Benutzer auf Ihr Popup klickt, auch wenn Ihre App geschlossen wurde und zum ersten Mal gestartet wird. Es wird häufig empfohlen, OnLaunched und OnActivated in Ihrer eigenen OnLaunchedOrActivated Methode zu kombinieren, da die gleiche Initialisierung in beiden erfolgen muss.

Aktivierung im Detail

Der erste Schritt, um Ihre Benachrichtigungen handlungsfähig zu machen, besteht darin, Ihrer Benachrichtigung einige Startargumente hinzuzufügen, damit Ihre App wissen kann, was gestartet werden soll, wenn der Benutzer auf die Benachrichtigung klickt (in diesem Fall enthalten wir einige Informationen, die uns später mitteilen, dass wir eine Unterhaltung öffnen sollten, und wir wissen, welche bestimmte Konversation geöffnet werden soll).

// Construct the content and show the toast!
(ref new ToastContentBuilder())

    // Arguments returned when user taps body of notification
    ->AddArgument("action", "viewConversation")
    ->AddArgument("conversationId", 9813)

    ->AddText("Andrew sent you a picture")
    ->Show();

Hinzufügen von Bildern

Sie können Benachrichtigungen umfangreiche Inhalte hinzufügen. Wir fügen ein Inlinebild und ein Profilbild (App-Logo außer Kraft) hinzu.

Hinweis

Bilder können aus dem App-Paket, dem lokalen Speicher der App oder aus dem Web verwendet werden. Ab dem Fall Creators Update können Webbilder bei normalen Verbindungen bis zu 3 MB und bei getakteten Verbindungen bis zu 1 MB groß sein. Auf Geräten, auf denen das Fall Creators Update noch nicht ausgeführt wird, dürfen Webimages nicht größer als 200 KB sein.

Popup mit Bildern 
// Construct the content and show the toast!
(ref new ToastContentBuilder())
    ...

    // Inline image
    ->AddInlineImage(ref new Uri("https://picsum.photos/360/202?image=883"))

    // Profile (app logo override) image
    ->AddAppLogoOverride(ref new Uri("ms-appdata:///local/Andrew.jpg"), ToastGenericAppLogoCrop::Circle)
    
    ->Show();

Hinzufügen von Schaltflächen und Eingaben

Sie können Schaltflächen und Eingaben hinzufügen, um Ihre Benachrichtigungen interaktiv zu machen. Schaltflächen können Ihre Vordergrund-App, ein Protokoll oder Ihre Hintergrundaufgabe starten. Wir fügen ein Antworttextfeld, eine Schaltfläche "Gefällt mir" und eine Schaltfläche "Ansicht" hinzu, mit der das Bild geöffnet wird.

Screenshot einer Popupbenachrichtigung mit Eingaben und Schaltflächen 
// Construct the content
(ref new ToastContentBuilder())
    ->AddArgument("conversationId", 9813)
    ...

    // Text box for replying
    ->AddInputTextBox("tbReply", "Type a response")

    // Buttons
    ->AddButton((ref new ToastButton())
        ->SetContent("Reply")
        ->AddArgument("action", "reply")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("Like")
        ->AddArgument("action", "like")
        ->SetBackgroundActivation())

    ->AddButton((ref new ToastButton())
        ->SetContent("View")
        ->AddArgument("action", "view"))
    
    ->Show();

Die Aktivierung von Vordergrundschaltflächen wird auf die gleiche Weise behandelt wie der Standard Popuptext (Ihr App.xaml.cpp OnActivated wird aufgerufen).

Behandeln der Hintergrundaktivierung

Wenn Sie die Hintergrundaktivierung für Ihr Popup (oder auf einer Schaltfläche innerhalb des Popups) angeben, wird Ihre Hintergrundaufgabe ausgeführt, anstatt Ihre Vordergrund-App zu aktivieren.

Weitere Informationen zu Hintergrundaufgaben finden Sie unter Unterstützen Ihrer App mit Hintergrundaufgaben.

Wenn Sie Build 14393 oder höher als Ziel haben, können Sie prozessinterne Hintergrundaufgaben verwenden, die die Dinge erheblich vereinfachen. Beachten Sie, dass in älteren Versionen von Windows prozessinterne Hintergrundaufgaben nicht ausgeführt werden können. In diesem Codebeispiel verwenden wir eine prozessinterne Hintergrundaufgabe.

const string taskName = "ToastBackgroundTask";

// If background task is already registered, do nothing
if (BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals(taskName)))
    return;

// Otherwise request access
BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();

// Create the background task
BackgroundTaskBuilder builder = new BackgroundTaskBuilder()
{
    Name = taskName
};

// Assign the toast action trigger
builder.SetTrigger(new ToastNotificationActionTrigger());

// And register the task
BackgroundTaskRegistration registration = builder.Register();

Überschreiben Sie dann in Ihrer App.xaml.cs die OnBackgroundActivated-Methode. Anschließend können Sie die vordefinierten Argumente und Benutzereingaben abrufen, ähnlich wie bei der Vordergrundaktivierung.

App.xaml.cs

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();
 
    switch (args.TaskInstance.Task.Name)
    {
        case "ToastBackgroundTask":
            var details = args.TaskInstance.TriggerDetails as ToastNotificationActionTriggerDetail;
            if (details != null)
            {
                string arguments = details.Argument;
                var userInput = details.UserInput;

                // Perform tasks
            }
            break;
    }
 
    deferral.Complete();
}

Festlegen einer Ablaufzeit

In Windows 10 und 11 werden alle Popupbenachrichtigungen im Info-Center angezeigt, nachdem sie vom Benutzer geschlossen oder ignoriert wurden, sodass Benutzer Ihre Benachrichtigung anzeigen können, nachdem das Popup nicht mehr angezeigt wurde.

Wenn die Nachricht in Ihrer Benachrichtigung jedoch nur für einen bestimmten Zeitraum relevant ist, sollten Sie eine Ablaufzeit für die Popupbenachrichtigung festlegen, damit den Benutzern keine veralteten Informationen aus Ihrer App angezeigt werden. Wenn eine Promotion beispielsweise nur 12 Stunden gültig ist, legen Sie die Ablaufzeit auf 12 Stunden fest. Im folgenden Code legen wir die Ablaufzeit auf 2 Tage fest.

Hinweis

Die Standard- und maximale Ablaufzeit für lokale Popupbenachrichtigungen beträgt 3 Tage.

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("Expires in 2 days...")
    ->Show(toast =>
    {
        toast->ExpirationTime = DateTime::Now->AddDays(2);
    });

Bereitstellen eines Primärschlüssels für Das Popup

Wenn Sie die gesendete Benachrichtigung programmgesteuert entfernen oder ersetzen möchten, müssen Sie die Tag-Eigenschaft (und optional die Group-Eigenschaft) verwenden, um einen Primärschlüssel für Ihre Benachrichtigung bereitzustellen. Anschließend können Sie diesen Primärschlüssel in Zukunft verwenden, um die Benachrichtigung zu entfernen oder zu ersetzen.

Weitere Details zum Ersetzen/Entfernen bereits bereitgestellter Popupbenachrichtigungen finden Sie unter Schnellstart: Verwalten von Popupbenachrichtigungen im Info-Center (XAML)..

Tag und Gruppe kombiniert fungieren als zusammengesetzter Primärschlüssel. Group ist der generischere Bezeichner, in dem Sie Gruppen wie "wallPosts", "messages", "friendRequests" usw. zuweisen können. Und dann sollte Tag die Benachrichtigung selbst innerhalb der Gruppe eindeutig identifizieren. Mithilfe einer generischen Gruppe können Sie dann alle Benachrichtigungen aus dieser Gruppe entfernen, indem Sie die RemoveGroup-API verwenden.

// Create toast content and show the toast!
(ref new ToastContentBuilder())
    ->AddText("New post on your wall!")
    ->Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

Löschen Ihrer Benachrichtigungen

Apps sind für das Entfernen und Löschen eigener Benachrichtigungen verantwortlich. Wenn Ihre App gestartet wird, löschen wir Ihre Benachrichtigungen NICHT automatisch.

Windows entfernt eine Benachrichtigung nur automatisch, wenn der Benutzer explizit auf die Benachrichtigung klickt.

Hier sehen Sie ein Beispiel dafür, was eine Messaging-App tun sollte...

  1. Benutzer erhält mehrere Popups zu neuen Nachrichten in einer Unterhaltung
  2. Der Benutzer tippt auf eines dieser Popups, um die Unterhaltung zu öffnen.
  3. Die App öffnet die Unterhaltung und löscht dann alle Popups für diese Unterhaltung (mithilfe von RemoveGroup in der von der App bereitgestellten Gruppe für diese Unterhaltung).
  4. Das Info-Center des Benutzers spiegelt jetzt ordnungsgemäß den Benachrichtigungsstatus wider, da es keine veralteten Benachrichtigungen für diese Unterhaltung im Info-Center gibt.

Informationen zum Löschen aller Benachrichtigungen oder zum Entfernen bestimmter Benachrichtigungen finden Sie unter Schnellstart: Verwalten von Popupbenachrichtigungen im Info-Center (XAML).

ToastNotificationManagerCompat::History->Clear();

Ressourcen