Enviar uma notificação de bloco localSend a local tile notification

Os blocos dos aplicativos primários no Windows 10 são definidos no manifesto do aplicativo, e os blocos secundários são criados e definidos programaticamente pelo código do aplicativo.Primary app tiles in Windows 10 are defined in your app manifest, while secondary tiles are programmatically created and defined by your app code. Este artigo descreve como enviar uma notificação de bloco local para um bloco primário e um bloco secundário usando modelos de bloco adaptável.This article describes how to send a local tile notification to a primary tile and a secondary tile using adaptive tile templates. (Notificação local é aquela que é enviada pelo código do app, e não uma enviada por push ou obtida em um servidor Web.)(A local notification is one that's sent from app code as opposed to one that's pushed or pulled from a web server.)

bloco padrão e bloco com notificação

 

Instalar o pacote NuGetInstall the NuGet package

Recomendamos instalar o Pacote NuGet Biblioteca de notificações, que simplifica as coisas pois gera cargas de bloco com objetos, em vez de XML bruto.We recommend installing the Notifications library NuGet package, which simplifies things by generating tile payloads with objects instead of raw XML.

Os exemplos de código embutido neste artigo são para a linguagem C# usando a biblioteca de notificações.The inline code examples in this article are for C# using the Notifications library. (Caso prefira criar o próprio XML, você pode encontrar exemplos de código sem o uso da biblioteca de notificações ao final do artigo.)(If you'd prefer to create your own XML, you can find code examples without the Notifications library toward the end of the article.)

Adicionar declarações do namespaceAdd namespace declarations

Para acessar as APIs de bloco, inclua o namespace Windows.UI.Notifications.To access the tile APIs, include the Windows.UI.Notifications namespace. Também recomendamos incluir o namespace Microsoft.Toolkit.Uwp.Notifications de maneira que seja possível usufruir de nossas APIs auxiliares de bloco (você deve instalar o pacote NuGet Biblioteca de notificações para acessar essas APIs).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

Criar o conteúdo da notificaçãoCreate the notification content

No Windows 10, as cargas de bloco são definidas usando-se modelos de bloco adaptável, que permitem criar layouts visuais personalizados para as notificações.In Windows 10, tile payloads are defined using adaptive tile templates, which allow you to create custom visual layouts for your notifications. (Para saber o que é possível com blocos adaptáveis, consulte Criar blocos adaptáveis.)(To learn what's possible with adaptive tiles, see Create adaptive tiles.)

Este exemplo de código cria conteúdo de bloco adaptável para blocos médios e largos.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
                    }
                }
            }
        }
    }
};

O conteúdo da notificação se parece com o seguinte quando exibido em um bloco médio:The notification content looks like the following when displayed on a medium tile:

conteúdo de notificação em um bloco médio

Criar a notificaçãoCreate the notification

Depois de ter o conteúdo da notificação, você precisará criar um novo TileNotification.Once you have your notification content, you'll need to create a new TileNotification. O construtor TileNotification utiliza um objeto XmlDocument do Windows Runtime, que você pode obter do método TileContent.GetXml caso você esteja usando a Biblioteca de notificações.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.

Este exemplo de código cria uma notificação para um novo bloco.This code example creates a notification for a new tile.

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

Definir um prazo de expiração para a notificação (opcional)Set an expiration time for the notification (optional)

Por padrão, as notificações locais de bloco e selo não expiram, enquanto as notificações por push, periódicas e agendadas expiram após três dias.By default, local tile and badge notifications don't expire, while push, periodic, and scheduled notifications expire after three days. Como o conteúdo do bloco não deve persistir por mais tempo do que o necessário, é melhor prática definir um prazo de expiração que faça sentido para o aplicativo, especialmente em notificações de bloco e selo locais.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.

Este exemplo de código cria uma notificação que expira e será removida do bloco após dez minutos.This code example creates a notification that expires and will be removed from the tile after ten minutes.

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

Enviar a notificaçãoSend the notification

Embora o envio local de uma notificação de bloco seja simples, enviar a notificação para um bloco primário ou secundário é um pouco diferente.Although locally sending a tile notification is simple, sending the notification to a primary or secondary tile is a bit different.

Bloco primárioPrimary tile

Para enviar uma notificação a um bloco primário, use o TileUpdateManager para criar um atualizador de bloco para o bloco primário e envie a notificação chamando "Update".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". Independentemente de estar visível, o bloco primário do aplicativo sempre existe, logo, é possível enviar notificações para ele, mesmo quando não está fixado.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. Se o usuário fixar o bloco primário posteriormente, as notificações que você enviou serão exibidas depois.If the user pins your primary tile later, the notifications that you sent will appear then.

Este exemplo de código envia uma notificação para um bloco primário.This code example sends a notification to a primary tile.

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

Bloco secundárioSecondary tile

Para enviar uma notificação para um bloco secundário, primeiro assegure-se de que o bloco secundário exista.To send a notification to a secondary tile, first make sure that the secondary tile exists. Se você tentar criar um atualizador de bloco para um bloco secundário que não existe (por exemplo, se o usuário desafixou o bloco secundário), uma exceção será acionada.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. É possível usar SecondaryTile.Exists (tileId) para descobrir se o bloco secundário está fixado, criar um atualizador para o bloco secundário e enviar a notificação.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.

Este exemplo de código envia uma notificação para um bloco secundário.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);
}

bloco padrão e bloco com notificação

Limpar notificações no bloco (opcional)Clear notifications on the tile (optional)

Na maioria dos casos, você deverá limpar uma notificação assim que o usuário tiver interagido com esse conteúdo.In most cases, you should clear a notification once the user has interacted with that content. Por exemplo, quando o usuário inicia o aplicativo, convém limpar todas as notificações do bloco.For example, when the user launches your app, you might want to clear all the notifications from the tile. Caso as notificações estejam associadas ao prazo, recomendamos definir um prazo de expiração na notificação, em vez de limpar explicitamente a notificação.If your notifications are time-bound, we recommend that you set an expiration time on the notification instead of explicitly clearing the notification.

Este exemplo de código limpa a notificação de bloco para o bloco primário.This code example clears the tile notification for the primary tile. Você pode fazer o mesmo para os blocos secundários. Basta criar um atualizador de bloco para o bloco secundário.You can do the same for secondary tiles by creating a tile updater for the secondary tile.

TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Em um bloco com a fila de notificação habilitada e notificações na fila, chamar o método Clear esvazia a fila.For a tile with the notification queue enabled and notifications in the queue, calling the Clear method empties the queue. No entanto, você não pode limpar uma notificação por meio do servidor de aplicativos; somente o código do aplicativo local pode limpar notificações.You can't, however, clear a notification via your app's server; only the local app code can clear notifications.

Notificações periódicas ou enviadas por push só podem adicionar novas notificações ou substituir notificações existentes.Periodic or push notifications can only add new notifications or replace existing notifications. Uma chamada local para o método Clear limpará o bloco independentemente das notificações propriamente ditas chegarem via push, serem periódicas ou locais.A local call to the Clear method will clear the tile whether or not the notifications themselves came via push, periodic, or local. Notificações agendadas que ainda não foram exibidas não são apagadas por esse método.Scheduled notifications that haven't yet appeared are not cleared by this method.

bloco com notificação e bloco após ser limpo

Próximas etapasNext steps

Como usar a fila de notificaçõesUsing the notification queue

Agora que concluiu a primeira atualização do bloco, você pode expandir a funcionalidade do título habilitando uma fila de notificação.Now that you have done your first tile update, you can expand the functionality of the tile by enabling a notification queue.

Outros métodos de entrega da notificaçãoOther notification delivery methods

Este artigo mostra como enviar a atualização do bloco como uma notificação.This article shows you how to send the tile update as a notification. Para explorar outros métodos de entrega da notificação, inclusive agendadas, periódicas e enviadas por push, consulte Entrega de notificações.To explore other methods of notification delivery, including scheduled, periodic, and push, see Delivering notifications.

Método de entrega XmlEncodeXmlEncode delivery method

Caso você não esteja usando a Biblioteca de notificações, esse método de entrega de notificação oferece outra alternativa.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();
}

Exemplos de código sem a Biblioteca de notificaçõesCode examples without Notifications library

Caso você prefira trabalhar com o XML bruto, em vez do pacote NuGet Biblioteca de notificações, use esses exemplos de código alternativos para os três primeiros exemplos fornecidos neste artigo.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. O restante dos exemplos de código podem ser usados com a Biblioteca de notificações ou com o XML bruto.The rest of the code examples can be used either with the Notifications library or with raw XML.

Adicionar declarações do namespaceAdd namespace declarations

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

Criar o conteúdo da notificaçãoCreate 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>";

Criar a notificaçãoCreate 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);