Freigeben über

Senden einer lokalen Popupbenachrichtigung aus einer C#-App

  • Artikel

Eine Popupbenachrichtigung ist eine Meldung, dass Ihre App ihren Benutzer erstellen und übermitteln kann, während sie sich derzeit nicht in Ihrer App befinden.

Screenshot einer Popupbenachrichtigung

Diese Schnellstartanleitung führt Sie durch die Schritte zum Erstellen, Bereitstellen und Anzeigen einer Windows 10- oder Windows 11-Popupbenachrichtigung 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!

Wichtig

Wenn Sie eine C++-App schreiben, lesen Sie die C++-UWP - oder C++-WRL-Dokumentation .

Schritt 1: Installieren des NuGet-Pakets

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

Wichtig

.NET Framework-Desktop-Apps, die weiterhin packages.config verwenden, müssen zu PackageReference migrieren, andernfalls werden die Windows-SDKs nicht ordnungsgemäß referenziert. Klicken Sie in Ihrem Projekt mit der rechten Maustaste auf "Verweise", und klicken Sie auf "Packages.config zu PackageReference migrieren".

.NET Core 3.0 WPF-Apps müssen auf .NET Core 3.1 aktualisiert werden, andernfalls fehlen die APIs.

.NET-Apps müssen eine der Windows TFMs verwenden, andernfalls fehlen die Popup-Sende- und Verwaltungs-APIs Show() . Legen Sie Ihr TFM auf oder höher fest net6.0-windows10.0.17763.0 .

Unser Codebeispiel verwendet dieses Paket. Mit diesem Paket können Sie Popupbenachrichtigungen erstellen, ohne XML zu verwenden. Außerdem können Desktop-Apps Popups senden.

Schritt 2: Senden eines Popups

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

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.Notifications

Einfache Textbenachrichtigung 
// Requires Microsoft.Toolkit.Uwp.Notifications NuGet package version 7.0 or greater
new ToastContentBuilder()
    .AddArgument("action", "viewConversation")
    .AddArgument("conversationId", 9813)
    .AddText("Andrew sent you a picture")
    .AddText("Check this out, The Enchantments in Washington!")
    .Show(); // Not seeing the Show() method? Make sure you have version 7.0, and if you're using .NET 6 (or later), then your TFM must be net6.0-windows10.0.17763.0 or greater

Versuchen Sie, diesen Code auszuführen, und die Benachrichtigung sollte angezeigt werden!

Schritt 3: Behandeln der Aktivierung

Nach dem Anzeigen einer Benachrichtigung müssen Sie wahrscheinlich den Benutzer mit dem Klicken auf die Benachrichtigung behandeln (ob dies bedeutet, dass bestimmte Inhalte angezeigt werden, nachdem der Benutzer darauf geklickt hat, ihre App im Allgemeinen öffnen oder eine Aktion ausführen, wenn der Benutzer auf die Benachrichtigung klickt).

Die Schritte zum Behandeln der Aktivierung unterscheiden sich für UWP und für verpackte und entpackte Desktop-Apps.

Wenn der Benutzer auf Ihre Benachrichtigung klickt (oder auf eine Schaltfläche auf der Benachrichtigung mit Vordergrundaktivierung), wird die App.xaml.cs OnActivated Ihrer App aufgerufen, und die hinzugefügten Argumente werden zurückgegeben.

App.xaml.cs

protected override void OnActivated(IActivatedEventArgs e)
{
    // Handle notification activation
    if (e is ToastNotificationActivatedEventArgs toastActivationArgs)
    {
        // Obtain the arguments from the notification
        ToastArguments args = ToastArguments.Parse(toastActivationArgs.Argument);

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

Wichtig

Sie müssen den Frame initialisieren und Das Fenster genauso aktivieren wie Der OnLaunched-Code . OnLaunched wird NICHT aufgerufen, wenn der Benutzer auf Ihr Popup klickt, auch wenn Die App geschlossen und zum ersten Mal gestartet wird. Es wird häufig empfohlen, OnLaunched und OnActivated in Ihre eigene OnLaunchedOrActivated Methode zu kombinieren, da in beiden Fällen dieselbe Initialisierung erfolgen muss.

Schritt 4: Behandeln der Deinstallation

Sie müssen nichts tun! Wenn UWP-Apps deinstalliert werden, werden alle Benachrichtigungen und alle anderen zugehörigen Ressourcen automatisch bereinigt.

Hinzufügen von Bildern

Sie können Benachrichtigungen umfangreiche Inhalte hinzufügen. Wir fügen ein Inlinebild und ein Profilbild (App-Logoüberschreibung) 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 Web-Bilder eine Größe von bis zu 3 MB bei normalen Verbindungen und 1 MB bei gebührenpflichtigen Verbindungen haben. Auf Geräten, auf denen das Fall Creators Update noch nicht ausgeführt wird, dürfen Webbilder nicht größer als 200 KB sein.

Wichtig

HTTP-Bilder werden nur in gepackten Apps unterstützt, die eine Internetfunktion in ihrem Manifest haben. Gepackte Apps unterstützen keine HTTP-Bilder; Sie müssen das Bild in Ihre lokalen App-Daten herunterladen und lokal darauf verweisen.

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

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

    // Profile (app logo override) image
    .AddAppLogoOverride(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 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 
int conversationId = 384928;

// Construct the content
new ToastContentBuilder()
    .AddArgument("conversationId", conversationId)
    ...

    // Text box for replying
    .AddInputTextBox("tbReply", placeHolderContent: "Type a response")

    // Buttons
    .AddButton(new ToastButton()
        .SetContent("Reply")
        .AddArgument("action", "reply")
        .SetBackgroundActivation())

    .AddButton(new ToastButton()
        .SetContent("Like")
        .AddArgument("action", "like")
        .SetBackgroundActivation())

    .AddButton(new ToastButton()
        .SetContent("View")
        .AddArgument("action", "viewImage")
        .AddArgument("imageUrl", image.ToString()))
    
    .Show();

Die Aktivierung von Vordergrundschaltflächen wird auf die gleiche Weise wie der Haupttext des Popups behandelt (Ihr App.xaml.cs OnActivated wird aufgerufen).

Beachten Sie, dass Argumente, die dem Popup auf oberster Ebene (z. B. Unterhaltungs-ID) hinzugefügt werden, auch zurückgegeben werden, wenn auf die Schaltflächen geklickt werden, sofern Schaltflächen die AddArgument-API wie oben dargestellt verwenden (wenn Sie benutzerdefinierte Argumente auf einer Schaltfläche zuweisen, werden die Argumente der obersten Ebene nicht eingeschlossen).

Behandeln der Hintergrundaktivierung

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

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

Wenn Sie auf Build 14393 oder höher abzielen, können Sie Hintergrundaufgaben in Prozessen 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 In-Process-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 Ihrem App.xaml.cs die OnBackgroundActivated-Methode. Anschließend können Sie die vordefinierten Argumente und Benutzereingaben abrufen, ähnlich 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)
            {
                ToastArguments arguments = ToastArguments.Parse(details.Argument);
                var userInput = details.UserInput;

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

Eine Ablaufuhrzeit festlegen

In Windows 10 werden alle Popupbenachrichtigungen 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 Popupbenachrichtigung festlegen, damit die Benutzer veraltete Informationen aus Ihrer App 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.

Hinweis

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

// Create toast content and show the toast!
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 Informationen zum Ersetzen/Entfernen bereits übermittelter Popupbenachrichtigungen finden Sie in der Schnellstartanleitung: Verwalten von Popupbenachrichtigungen im Info-Center (XAML).

Tag und Gruppe kombiniert fungieren als zusammengesetzter Primärschlüssel. "Gruppe" ist der allgemeinere Bezeichner, bei dem Sie Gruppen wie "wallPosts", "messages", "friendRequests" usw. zuweisen 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-API entfernen.

// Create toast content and show the toast!
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, 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-App tun sollte...

  1. Der Benutzer empfängt mehrere Popups zu neuen Nachrichten in einer Unterhaltung.
  2. Der Benutzer tippt auf eine 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 den Status der Benachrichtigung ordnungsgemäß wider, da im Info-Center keine veralteten Benachrichtigungen für diese Unterhaltung vorhanden sind.

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