Enviar una notificación de icono local

  • Artículo

Los iconos de la aplicación principal de Windows 10 se definen en el manifiesto de la aplicación, mientras que los iconos secundarios se crean mediante programación y se definen mediante el código de la aplicación. En este artículo se describe cómo enviar una notificación de icono local a un icono principal y un icono secundario con el uso de plantillas de iconos adaptables. (Una notificación local es aquella que se envía desde el código de la aplicación frente a la que se envía o extrae de un servidor web).

icono predeterminado e icono con notificación

Nota:

Obtenga información sobre cómo crear iconos adaptables y esquema de contenido de iconos.

 

Instalación del paquete NuGet.

Recomendamos instalar el paquete de NuGet de la librería de notificaciones, que simplifica las cosas al generar cargas de iconos con objetos en lugar de XML sin formato.

Los ejemplos de código en línea de este artículo son para C# usando la biblioteca de notificaciones. (Si prefieres crear tu propio XML, puedes encontrar ejemplos de código sin la librería de notificaciones al final del artículo.)

Incorporación de declaraciones de espacio de nombres

Para acceder a las API del icono, incluye el espacio de nombres Windows.UI.Notifications. También se recomienda incluir el espacio de nombres Microsoft.Toolkit.Uwp.Notifications para que pueda aprovechar nuestras API auxiliares de iconos (debe instalar el paquete NuGet de la biblioteca de notificaciones para acceder a estas API).

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

Crear el contenido de la notificación

En Windows 10, las cargas de iconos se definen mediante plantillas de iconos adaptables, que te permiten crear diseños visuales personalizados para tus notificaciones. (Para obtener información sobre lo que es posible con iconos adaptables, consulte Creación de iconos adaptables).

Este ejemplo de código crea el contenido de iconos adaptables para iconos medianos y anchos.

// 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
                    }
                }
            }
        }
    }
};

El contenido de las notificaciones es similar al siguiente cuando se muestra en un icono mediano:

contenido de las notificaciones en un icono mediano

Crear la notificación

Una vez que dispongas del contenido de la notificación, debes crear un nuevo TileNotification. El constructor TileNotification toma un objeto XmlDocument de Windows Runtime, que puedes obtener del método TileContent.GetXml si estás usando la librería de notificaciones.

Este ejemplo de código crea una notificación para un icono nuevo.

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

Establecer una fecha de expiración para la notificación (opcional)

De manera predeterminada, las notificaciones de iconos y distintivos locales no expiran, mientras que las notificaciones programadas, periódicas y de inserción expiran al cabo de de tres días. El contenido de los iconos no debe persistir más de lo necesario, por lo que se considera una buena práctica establecer una fecha de caducidad apropiada para la aplicación, especialmente en las notificaciones de iconos y distintivos locales.

Este ejemplo de código crea una notificación que expira y se eliminará del icono después de diez minutos.

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

Enviar la notificación

Aunque el envío local de una notificación de iconos es sencillo, enviar la notificación a un icono principal o secundario es un poco diferente.

Icono principal

Para enviar una notificación a un icono principal, usa TileUpdateManager para crear un actualizador de iconos para el icono principal y envía la notificación llamando a "Update". Independientemente de si es visible, el icono principal de tu aplicación siempre existe, por lo que puedes enviarle notificaciones aunque no esté anclado. Si el usuario ancla tu icono principal más adelante, las notificaciones que enviaste aparecerán entonces.

Este ejemplo de código envía una notificación a un icono principal.

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

Icono secundario

Para enviar una notificación a un icono secundario, asegúrate primero de que el icono secundario existe. Si intentas crear un actualizador de iconos para un icono secundario que no existe (por ejemplo, si el usuario ha desanclado el icono secundario), se generará una excepción. Puedes usar SecondaryTile.Exists (tileId) para averiguar si tu icono secundario está anclado después crear un actualizador para el icono secundario y enviar la notificación.

Este ejemplo de código envía una notificación a un icono secundario.

// 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);
}

icono predeterminado e icono con notificación

Borrar las notificaciones en el icono (opcional)

En la mayoría de los casos, debes borrar una notificación cuando el usuario haya interactuado con ese contenido. Por ejemplo, cuando el usuario inicia tu aplicación, es posible que quieras borrar todas las notificaciones del icono. Si tus notificaciones están controladas por tiempo, te recomendamos que establezcas una fecha de caducidad en la notificación en lugar de borrarla explícitamente.

Este ejemplo de código borra la notificación de icono para el icono principal. Se puede hacer lo mismo para los iconos secundarios creando un actualizador para el icono secundario.

TileUpdateManager.CreateTileUpdaterForApplication().Clear();

En un icono con la cola de notificaciones habilitada y con notificaciones en cola, la cola se vacía cuando se llama al método Clear. Sin embargo, no puedes borrar una notificación a través del servidor de la aplicación; solo el código de la aplicación local puede borrar las notificaciones.

Las notificaciones de inserción o periódicas solo pueden agregar nuevas notificaciones o reemplazar las notificaciones existentes. Una llamada local al método Clear borrará el icono independientemente de si las notificaciones fueron de inserción, periódicas o locales. Este método no borra las notificaciones programadas que aún no han aparecido.

icono con notificación e icono después de ser borrado

Pasos siguientes

Uso de la cola de notificaciones

Ahora que has realizado tu primera actualización de iconos, puedes habilitar una cola de notificaciones para expandir la funcionalidad del icono.

Otros métodos de entrega de notificaciones

Este artículo te muestra cómo enviar la actualización de iconos como una notificación. Para explorar otros métodos de entrega de notificaciones, incluidos los programados, periódicos y de inserción, consulta Entrega de notificaciones.

Método de entrega XmlEncode

Si no estás usando la librería de notificaciones, este método de entrega de notificaciones es otra alternativa.

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

    return builder.ToString();
}

Ejemplos de código sin librería de notificaciones

Si prefieres trabajar con XML sin formato en lugar del paquete NuGet de la librería de notificaciones, usa estos ejemplos de código alternativos para los tres primeros ejemplos proporcionados en este artículo. El resto de los ejemplos de código se puede usar o bien con la librería de notificaciones o bien con XML sin formato.

Incorporación de declaraciones de espacio de nombres

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

Crear el contenido de la notificación

// 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>";

Crear la notificación

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