Senden einer lokalen KachelbenachrichtigungSend a local tile notification

Primäre App-Kacheln in Windows 10 werden im App-Manifest definiert, sekundäre Kacheln werden dagegen programmgesteuert erstellt und vom App-Code definiert.Primary app tiles in Windows 10 are defined in your app manifest, while secondary tiles are programmatically created and defined by your app code. In diesem Artikel wird beschrieben, wie Sie mit adaptiven Kachelvorlagen eine lokale Benachrichtigung an eine primäre Kachel und an eine sekundäre Kachel senden.This article describes how to send a local tile notification to a primary tile and a secondary tile using adaptive tile templates. (Eine lokale Benachrichtigung wird vom App-Code gesendet, im Gegensatz zu Benachrichtigungen, die ein Webserver per Push oder Pull sendet.)(A local notification is one that's sent from app code as opposed to one that's pushed or pulled from a web server.)

Standardkachel und Kachel mit Benachrichtigung

 

Installieren des NuGet-PaketsInstall the NuGet package

Wir empfehlen die Installation des NuGet-Pakets aus der Benachrichtigungsbibliothek, das Kachelnutzlasten mit Objekten anstelle von unformatiertem XML generiert und damit vieles vereinfacht.We recommend installing the Notifications library NuGet package, which simplifies things by generating tile payloads with objects instead of raw XML.

Die Inlinecodebeispiele in diesem Artikel beziehen sich auf C# unter Verwendung der Benachrichtigungsbibliothek.The inline code examples in this article are for C# using the Notifications library. (Wenn Sie eigenen XML-Code erstellen möchten, finden Sie am Ende des Artikels Codebeispiele ohne Benachrichtigungsbibliothek.)(If you'd prefer to create your own XML, you can find code examples without the Notifications library toward the end of the article.)

Hinzufügen von Namespace-DeklarationenAdd namespace declarations

Um auf die Kachel-APIs zuzugreifen, beziehen Sie den Windows.UI.Notifications-Namespace ein.To access the tile APIs, include the Windows.UI.Notifications namespace. Außerdem wird empfohlen, den Namespace " Microsoft. Toolkit. UWP. Benachrichtigungen " zu verwenden, damit Sie unsere Kachel-Hilfsobjekte nutzen können (Sie müssen das nuget-Paket für Benachrichtigungs Bibliotheken installieren, um auf diese APIs zuzugreifen).We also recommend including the Microsoft.Toolkit.Uwp.Notifications namespace so that you can take advantage of our tile helper APIs (you must install the Notifications library NuGet package to access these APIs).

using Windows.UI.Notifications;
using Microsoft.Toolkit.Uwp.Notifications; // Notifications library

Erstellen des BenachrichtigungsinhaltsCreate the notification content

In Windows 10 werden Kachelnutzlasten mit adaptiven Kachelvorlagen definiert, mit denen Sie benutzerdefinierte visuelle Layouts für Ihre Benachrichtigungen erstellen können.In Windows 10, tile payloads are defined using adaptive tile templates, which allow you to create custom visual layouts for your notifications. (Informationen zu den Möglichkeiten von adaptiven Kacheln finden Sie unter Erstellen von adaptiven Kacheln.)(To learn what's possible with adaptive tiles, see Create adaptive tiles.)

Dieses Codebeispiel erstellt adaptive Kachelinhalte für mittelgroße und breite Kacheln.This code example creates adaptive tile content for medium and wide tiles.

// In a real app, these would be initialized with actual data
string from = "Jennifer Parker";
string subject = "Photos from our trip";
string body = "Check out these awesome photos I took while in New Zealand!";
 
 
// Construct the tile content
TileContent content = new TileContent()
{
    Visual = new TileVisual()
    {
        TileMedium = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = from
                    },

                    new AdaptiveText()
                    {
                        Text = subject,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    },

                    new AdaptiveText()
                    {
                        Text = body,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            }
        },

        TileWide = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveText()
                    {
                        Text = from,
                        HintStyle = AdaptiveTextStyle.Subtitle
                    },

                    new AdaptiveText()
                    {
                        Text = subject,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    },

                    new AdaptiveText()
                    {
                        Text = body,
                        HintStyle = AdaptiveTextStyle.CaptionSubtle
                    }
                }
            }
        }
    }
};

Auf einer mittelgroßen Kachel wird der Inhalt der Benachrichtigung wie folgt angezeigt:The notification content looks like the following when displayed on a medium tile:

Inhalt der Benachrichtigung auf einer mittelgroßen Kachel

Erstellen der BenachrichtigungCreate the notification

Wenn Sie den Inhalt der Benachrichtigung erstellt haben, müssen Sie eine neue TileNotification-Klasse erstellen.Once you have your notification content, you'll need to create a new TileNotification. Der TileNotification-Konstruktor akzeptiert ein Windows-Runtime-XmlDocument-Objekt, das Sie aus der TileContent.GetXml-Methode abrufen können, wenn Sie die Benachrichtigungsbibliothek verwenden.The TileNotification constructor takes a Windows Runtime XmlDocument object, which you can obtain from the TileContent.GetXml method if you're using the Notifications library.

Mit diesem Codebeispiel wird eine Benachrichtigung für eine neue Kachel erstellt.This code example creates a notification for a new tile.

// Create the tile notification
var notification = new TileNotification(content.GetXml());

Festlegen einer Ablaufzeit für die Benachrichtigung (optional)Set an expiration time for the notification (optional)

Standardmäßig laufen lokale Kachel- und Signalbenachrichtigungen nicht ab, während Pushbenachrichtigungen sowie regelmäßige und geplante Benachrichtigungen nach drei Tagen ablaufen.By default, local tile and badge notifications don't expire, while push, periodic, and scheduled notifications expire after three days. Weil Kachelinhalt nur so lange wie notwendig beibehalten werden soll, sollten Sie, insbesondere für lokale Kachel- und Signalbenachrichtigungen, eine Gültigkeitsdauer festlegen, die für Ihre App sinnvoll ist.Because tile content shouldn't persist longer than necessary, it's a best practice to set an expiration time that makes sense for your app, especially on local tile and badge notifications.

In diesem Codebeispiel wird eine Benachrichtigung erstellt, die nach zehn Minuten abläuft und von der Kachel entfernt wird.This code example creates a notification that expires and will be removed from the tile after ten minutes.

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(10);

Senden der BenachrichtigungSend the notification

Das lokale Senden einer Kachelbenachrichtigung ist einfach, das Senden der Benachrichtigung an eine primäre oder sekundäre Kachel weicht aber etwas davon ab.Although locally sending a tile notification is simple, sending the notification to a primary or secondary tile is a bit different.

Primäre KachelPrimary tile

Verwenden Sie zum Senden einer Benachrichtigung an eine primäre Kachel den TileUpdateManager, um für die primäre Kachel eine Kachelaktualisierung zu erstellen und die Benachrichtigung durch Aufrufen von „Update” zu senden.To send a notification to a primary tile, use the TileUpdateManager to create a tile updater for the primary tile, and send the notification by calling "Update". Die primäre Kachel Ihrer App ist immer vorhanden, selbst wenn sie nicht sichtbar ist. Daher können Sie Benachrichtigungen an die Kachel senden, auch wenn sie nicht angeheftet ist.Regardless of whether it's visible, your app's primary tile always exists, so you can send notifications to it even when it's not pinned. Wenn der Benutzer später die primäre Kachel anheftet, werden die Benachrichtigungen, die Sie gesendet haben, angezeigt.If the user pins your primary tile later, the notifications that you sent will appear then.

Mit diesem Codebeispiel wird eine Benachrichtigung an eine primäre Kachel gesendet.This code example sends a notification to a primary tile.

// Send the notification to the primary tile
TileUpdateManager.CreateTileUpdaterForApplication().Update(notification);

Sekundäre KachelSecondary tile

Um eine Benachrichtigung an eine sekundäre Kachel zu senden, müssen Sie zuerst sicherstellen Sie, dass die sekundäre Kachel vorhanden ist.To send a notification to a secondary tile, first make sure that the secondary tile exists. Wenn Sie versuchen, eine Kachelaktualisierung für eine sekundäre Kachel zu erstellen, die nicht vorhanden ist (z. B. wenn der Benutzer die sekundäre Kachel gelöst hat), wird eine Ausnahme ausgelöst.If you try to create a tile updater for a secondary tile that doesn't exist (for example, if the user unpinned the secondary tile), an exception will be thrown. Sie können mit SecondaryTile.Exists(tileId) ermitteln, ob die sekundäre Kachel angeheftet ist, und dann eine Kachelaktualisierung für eine sekundäre Kachel erstellen und die Benachrichtigung senden.You can use SecondaryTile.Exists(tileId) to discover if your secondary tile is pinned, and then create a tile updater for the secondary tile and send the notification.

Mit diesem Codebeispiel wird eine Benachrichtigung an eine sekundäre Kachel gesendet.This code example sends a notification to a secondary tile.

// If the secondary tile is pinned
if (SecondaryTile.Exists("MySecondaryTile"))
{
    // Get its updater
    var updater = TileUpdateManager.CreateTileUpdaterForSecondaryTile("MySecondaryTile");
 
    // And send the notification
    updater.Update(notification);
}

Standardkachel und Kachel mit Benachrichtigung

Löschen von Benachrichtigungen auf der Kachel (optional)Clear notifications on the tile (optional)

In den meisten Fällen sollten Sie eine Benachrichtigung löschen, sobald der Benutzer mit diesem Inhalt interagiert hat.In most cases, you should clear a notification once the user has interacted with that content. Zum Beispiel sollten Sie alle Benachrichtigungen auf der Kachel löschen, wenn der Benutzer die App startet.For example, when the user launches your app, you might want to clear all the notifications from the tile. Wenn die Benachrichtigungen zeitabhängig sind, sollten Sie eine Ablaufzeit für die Benachrichtigung festlegen, anstatt sie explizit zu löschen.If your notifications are time-bound, we recommend that you set an expiration time on the notification instead of explicitly clearing the notification.

In diesem Codebeispiel wird die Kachelbenachrichtigung für die primäre Kachel gelöscht.This code example clears the tile notification for the primary tile. Sie können diesen Vorgang auf sekundäre Kacheln anwenden, indem Sie für die sekundäre Kachel eine Kachelaktualisierung erstellen.You can do the same for secondary tiles by creating a tile updater for the secondary tile.

TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Bei einer Kachel mit aktivierter Benachrichtigungswarteschlange und Benachrichtigungen in der Warteschlange wird durch Aufrufen der Clear-Methode die Warteschlange gelöscht.For a tile with the notification queue enabled and notifications in the queue, calling the Clear method empties the queue. Es ist aber nicht möglich ist, eine Benachrichtigung über den Server Ihrer App zu löschen; Benachrichtigungen können nur durch lokalen App-Code gelöscht werden.You can't, however, clear a notification via your app's server; only the local app code can clear notifications.

Durch regelmäßige oder Push-Benachrichtigungen können nur neue Benachrichtigungen hinzugefügt oder vorhandene Benachrichtigungen ersetzt werden.Periodic or push notifications can only add new notifications or replace existing notifications. Mit einem lokalen Aufruf der Clear-Methode wird die Kachel gelöscht, unabhängig davon, ob die Benachrichtigungen selbst per Push, regelmäßig oder lokal gesendet wurden.A local call to the Clear method will clear the tile whether or not the notifications themselves came via push, periodic, or local. Geplante Benachrichtigungen, die noch nicht angezeigt wurden, werden durch diese Methode nicht gelöscht.Scheduled notifications that haven't yet appeared are not cleared by this method.

Kachel mit Benachrichtigung und Kachel nach dem Löschen

Nächste SchritteNext steps

Verwenden der BenachrichtigungswarteschlangeUsing the notification queue

Nachdem Sie Ihre erste Kachelaktualisierung ausgeführt haben, können Sie die Funktionalität der Kachel erweitern, indem Sie eine Benachrichtigungswarteschlange aktivieren.Now that you have done your first tile update, you can expand the functionality of the tile by enabling a notification queue.

Andere Methoden für die BenachrichtigungsübermittlungOther notification delivery methods

In diesem Artikel wird erläutert, wie die Kachelaktualisierung als Benachrichtigung gesendet werden kann.This article shows you how to send the tile update as a notification. Informationen zu anderen Methoden der Benachrichtigungsübermittlung, einschließlich geplanter, regelmäßiger und Push-Benachrichtigungen, finden Sie unter Zustellen von Benachrichtigungen.To explore other methods of notification delivery, including scheduled, periodic, and push, see Delivering notifications.

XmlEncode-ÜbermittlungsmethodeXmlEncode delivery method

Wenn Sie die Benachrichtigungsbibliothek nicht verwenden, bietet diese Methode für die Benachrichtigungsübermittlung eine weitere Alternative.If you're not using the Notifications library, this notification delivery method is another alternative.

public string XmlEncode(string text)
{
    StringBuilder builder = new StringBuilder();
    using (var writer = XmlWriter.Create(builder))
    {
        writer.WriteString(text);
    }

    return builder.ToString();
}

Codebeispiele ohne BenachrichtigungsbibliothekCode examples without Notifications library

Wenn Sie mit unformatiertem XML anstatt mit dem NuGet-Paket aus der Benachrichtigungsbibliothek arbeiten möchten, verwenden Sie diese alternativen Codebeispiele für die ersten drei Beispiele in diesem Artikel.If you prefer to work with raw XML instead of the Notifications library NuGet package, use these alternate code examples to first three examples provided in this article. Die restlichen Codebeispiele können entweder mit der Benachrichtigungsbibliothek oder mit unformatiertem XML verwendet werden.The rest of the code examples can be used either with the Notifications library or with raw XML.

Hinzufügen von Namespace-DeklarationenAdd namespace declarations

using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

Erstellen des BenachrichtigungsinhaltsCreate the notification content

// In a real app, these would be initialized with actual data
string from = "Jennifer Parker";
string subject = "Photos from our trip";
string body = "Check out these awesome photos I took while in New Zealand!";
 
 
// TODO - all values need to be XML escaped
 
 
// Construct the tile content as a string
string content = $@"
<tile>
    <visual>
 
        <binding template='TileMedium'>
            <text>{from}</text>
            <text hint-style='captionSubtle'>{subject}</text>
            <text hint-style='captionSubtle'>{body}</text>
        </binding>
 
        <binding template='TileWide'>
            <text hint-style='subtitle'>{from}</text>
            <text hint-style='captionSubtle'>{subject}</text>
            <text hint-style='captionSubtle'>{body}</text>
        </binding>
 
    </visual>
</tile>";

Erstellen der BenachrichtigungCreate the notification

// Load the string into an XmlDocument
XmlDocument doc = new XmlDocument();
doc.LoadXml(content);
 
// Then create the tile notification
var notification = new TileNotification(doc);