Freigeben über

Senden einer lokalen app Benachrichtigung aus C++-UWP-Apps

Eine app Benachrichtigung ist eine Nachricht, die Sie app erstellen und an den Benutzer übermitteln können, während er sich derzeit nicht in Ihrer app-App befindet.

Screenshot einer app Benachrichtigung

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

Note

Der Begriff "toast notification" wird durch "app notification" ersetzt. Diese Begriffe beziehen sich beide auf dieselbe Funktion von Windows, aber im Laufe der Zeit werden wir die Verwendung von "toast Benachrichtigung" in der Dokumentation einstellen.

Important

Wenn Sie eine C++-Nicht-UWP appschreiben, lesen Sie die C++-WRL-Dokumentation . Wenn Sie eine C# app-Datei schreiben, lesen Sie die C#-Dokumentation.

Schritt 1: Installieren des NuGet-Pakets

Sie können Benachrichtigungen mit der Generatorsyntax des Windows Community Toolkit (WCT) ODER mit XML erstellen app . Wenn Sie letzteres bevorzugen, fahren Sie mit Schritt 2 fort und verweisen Sie auf die Ohne Builder-Syntax Codebeispiele.

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

Unsere Builder-Syntax Codebeispiele verwenden dieses Paket. Mit diesem Paket können Sie Benachrichtigungen erstellen app , ohne XML zu verwenden.

Schritt 2: Hinzufügen von Namespacedeklarationen

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

Schritt 3: Senden einer app Benachrichtigung

In Windows 10 und Windows 11 wird Der app Benachrichtigungsinhalt mithilfe einer adaptiven Sprache beschrieben, die eine hohe Flexibilität bei der Darstellung Ihrer Benachrichtigung ermöglicht. Weitere Informationen finden Sie in der App Dokumentation zu Benachrichtigungsinhalten .

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 Microsoft.Toolkit.Uwp.Notificationsist.

einfache Textbenachrichtigung

Wenn Sie die Syntax des WCT-Benachrichtigungsbibliotheks-Generators nicht verwenden, erstellen Sie stattdessen die XML-Benachrichtigungsvorlage app , füllen Sie sie mit Text und Werten auf, erstellen Sie die Benachrichtigung, und zeigen Sie 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: Aktivierung durchführen

Wenn der Benutzer auf Ihre Benachrichtigung klickt (oder auf eine Schaltfläche auf der Benachrichtigung mit Vordergrundaktivierung), wird die app.xaml.cppAppOnActivated 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
    }
}

Important

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

Aktivierung im Detail

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

// 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überschreibung) hinzu.

Note

Bilder können aus dem app-Paket, dem app-speicher 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 Webbilder nicht größer als 200 KB sein.

Toast 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 gestalten. Schaltflächen können Ihren 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 toast Benachrichtigung 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 wie der Hauptbenachrichtigungstext behandelt (Ihr App.xaml.cpp OnActivated wird aufgerufen).

Behandeln der Hintergrundaktivierung

Wenn Sie die Hintergrundaktivierung für Ihre app Benachrichtigung (oder auf einer Schaltfläche innerhalb der Benachrichtigung) angeben, wird die Hintergrundaufgabe ausgeführt, anstatt den Vordergrund appzu aktivieren.

Weitere Informationen zu Hintergrundaufgaben finden Sie unter Unterstützen Sie Ihre app mit Hintergrundaufgaben.

Wenn Sie auf Build 14393 oder höher abzielen, können Sie In-Prozess-Hintergrundaufgaben verwenden, die die Dinge erheblich vereinfachen. Beachten Sie, dass In-Process-Hintergrundaufgaben bei älteren Versionen von Windows nicht ausgeführt werden können. In diesem Codebeispiel verwenden wir eine Hintergrundaufgabe im Prozess.

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 Ihrem 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 app Benachrichtigungen im Info-Center angezeigt, nachdem sie vom Benutzer geschlossen oder ignoriert wurden, sodass Benutzer Ihre Benachrichtigung sehen 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 app Benachrichtigung festlegen, damit die Benutzer veraltete Informationen von Ihrer appBenachrichtigung nicht sehen. Wenn eine Aktion 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.

Note

Die Standard- und maximale Ablaufzeit für lokale app Benachrichtigungen 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 Ihre app Benachrichtigung

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 Informationen zum Ersetzen/Entfernen bereits übermittelter app Benachrichtigungen finden Sie in der Schnellstartanleitung: Verwalten von toast Benachrichtigungen im Info-Center (XAML).

Tag und Gruppe fungieren kombiniert als zusammengesetzter Primärschlüssel. "Gruppe" ist der allgemeinere Bezeichner, bei dem Gruppen wie „wallPosts“, „messages“, „friendRequests“ usw. zugewiesen werden können. Anschließend sollte „Tag“ die Benachrichtigung selbst innerhalb der Gruppe eindeutig identifizieren. Mithilfe einer generischen Gruppe können Sie dann alle Benachrichtigungen aus dieser Gruppe mithilfe der RemoveGroup-APIentfernen.

// 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 Ihr app gestartet wird, werden Ihre Benachrichtigungen NICHT automatisch gelöscht.

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

Hier ist ein Beispiel dafür, was eine Messaging-Komponente app tun sollte...

  1. Der Benutzer empfängt mehrere app Benachrichtigungen zu neuen Nachrichten in einer Unterhaltung.
  2. Der Benutzer tippt auf eine dieser Benachrichtigungen, um die Unterhaltung zu öffnen.
  3. Die app öffnet die Unterhaltung und löscht anschließend alle Benachrichtigungen für diese Unterhaltung (mithilfe von RemoveGroup auf der von app bereitgestellten Gruppe der Unterhaltung)
  4. Das Info-Center des Benutzers zeigt jetzt den korrekten Benachrichtigungsstatus an, da keine veralteten Benachrichtigungen für diese Unterhaltung im Info-Center verbleiben.

Informationen zum Löschen aller Benachrichtigungen oder zum Entfernen bestimmter Benachrichtigungen finden Sie in der Schnellstartanleitung: Verwalten von toast Benachrichtigungen im Info-Center (XAML).

ToastNotificationManagerCompat::History->Clear();

Resources

  • Last updated on