Compartir a través de

Envío de una notificación del sistema local desde una aplicación de C#

  • Artículo

Una notificación del sistema es un mensaje que indica que la aplicación puede construir y entregar al usuario mientras no están dentro de la aplicación.

Captura de pantalla de una notificación del sistema

Este inicio rápido le guía por los pasos para crear, entregar y mostrar una notificación del sistema de Windows 10 o Windows 11 con contenido enriquecido y acciones interactivas. En este inicio rápido se usan las notificaciones locales, que son las más sencillas de implementar. ¡Todos los tipos de aplicaciones (WPF, UWP, WinForms, consola) pueden enviar notificaciones!

Importante

Si estás escribiendo una aplicación de C++, consulta la documentación de C++ para UWP o C++ WRL .

Paso 1: Instalación del paquete NuGet

En la solución de Visual Studio, haga clic con el botón derecho en el proyecto, haga clic en "Administrar paquetes NuGet..." y busque e instale la versión 7.0 o posterior del Microsoft.Toolkit.Uwp.Notifications paquete NuGet.

Importante

Las aplicaciones de escritorio de .NET Framework que todavía usan packages.config deben migrar a PackageReference; de lo contrario, los SDK de Windows no se harán referencia correctamente. En el proyecto, haga clic con el botón derecho en "Referencias" y haga clic en "Migrar packages.config a PackageReference".

Las aplicaciones WPF de .NET Core 3.0 deben actualizarse a .NET Core 3.1; de lo contrario, las API estarán ausentes.

Las aplicaciones .NET deben usar uno de los TFM de Windows; de lo contrario, faltarán las API de envío y administración del sistema como Show() . Establezca el TFM en net6.0-windows10.0.17763.0 o posterior.

Nuestro ejemplo de código usará este paquete. Este paquete permite crear notificaciones del sistema sin usar XML y también permite que las aplicaciones de escritorio envíen notificaciones del sistema.

Paso 2: Enviar una notificación del sistema

En Windows 10 y Windows 11, el contenido de la notificación del sistema se describe mediante un lenguaje adaptable que permite una gran flexibilidad con el aspecto de la notificación. Para obtener más información, consulte la documentación del contenido del sistema.

Comenzaremos con una notificación sencilla basada en texto. Construya el contenido de la notificación (mediante la biblioteca de notificaciones) y muestre la notificación. Tenga en cuenta que el espacio de nombres es Microsoft.Toolkit.Uwp.Notifications.

Notificación de texto simple 
// 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

Pruebe a ejecutar este código y debería ver que aparece la notificación.

Paso 3: Control de la activación

Después de mostrar una notificación, es probable que tengas que controlar el usuario haciendo clic en la notificación (ya sea que esto significa mostrar contenido específico después de que el usuario lo haga clic, abrir la aplicación en general o realizar una acción cuando el usuario haga clic en la notificación).

Los pasos para controlar la activación difieren para UWP y para aplicaciones de escritorio empaquetadas y sin empaquetar.

Cuando el usuario hace clic en la notificación (o un botón en la notificación con activación en primer plano), se invocará la App.xaml.cs OnActivated de la aplicación y se devolverán los argumentos que agregó.

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

Importante

Debe inicializar el marco y activar la ventana igual que el código OnLaunched . No se llama a OnLaunched si el usuario hace clic en la notificación del sistema, incluso si la aplicación se cerró y se inicia por primera vez. A menudo se recomienda combinar OnLaunched y OnActivated en su propio OnLaunchedOrActivated método, ya que la misma inicialización debe producirse en ambos.

Paso 4: Control de la desinstalación

¡No necesitas hacer nada! Cuando se desinstalan las aplicaciones para UWP, todas las notificaciones y cualquier otro recurso relacionado se limpian automáticamente.

Incorporación de imágenes

Puede agregar contenido enriquecido a las notificaciones. Agregaremos una imagen insertada y una imagen de perfil (invalidación del logotipo de la aplicación).

Nota:

Las imágenes se pueden usar desde el paquete de la aplicación, el almacenamiento local de la aplicación o desde la web. En Fall Creators Update, las imágenes web pueden tener hasta 3 MB en conexiones normales y 1 MB en conexiones de uso medido. En los dispositivos que aún no ejecutan Fall Creators Update, las imágenes web no deben tener más de 200 KB.

Importante

Las imágenes HTTP solo se admiten en aplicaciones empaquetadas que tienen la funcionalidad de Internet en su manifiesto. Las aplicaciones sin empaquetar no admiten imágenes HTTP; debe descargar la imagen en los datos de la aplicación local y hacer referencia a ella localmente.

Notificación del sistema con imágenes 
// 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();

Adición de botones y entradas

Puede agregar botones y entradas para que las notificaciones sean interactivas. Los botones pueden iniciar la aplicación en primer plano, un protocolo o la tarea en segundo plano. Agregaremos un cuadro de texto de respuesta, un botón "Like" y un botón "Ver" que abre la imagen.

Captura de pantalla de una notificación del sistema con entradas y botones 
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();

La activación de botones en primer plano se controla de la misma manera que el cuerpo de la notificación del sistema principal (se llamará a su App.xaml.cs OnActivated).

Tenga en cuenta que los argumentos agregados al sistema de nivel superior (como el identificador de conversación) también se devolverán cuando se haga clic en los botones, siempre y cuando los botones usen la API AddArgument como se ha visto anteriormente (si se asignan argumentos personalizados en un botón, no se incluirán los argumentos de nivel superior).

Control de la activación en segundo plano

Al especificar la activación en segundo plano en la notificación del sistema (o en un botón dentro de la notificación del sistema), la tarea en segundo plano se ejecutará en lugar de activar la aplicación en primer plano.

Para obtener más información sobre las tareas en segundo plano, consulta Compatibilidad con la aplicación con tareas en segundo plano.

Si tiene como destino la compilación 14393 o posterior, puede usar tareas en segundo plano en proceso, lo que simplifica considerablemente las cosas. Tenga en cuenta que las tareas en segundo plano en proceso no se ejecutarán en versiones anteriores de Windows. Usaremos una tarea en segundo plano en proceso en este ejemplo de código.

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();

A continuación, en el App.xaml.cs, invalide el método OnBackgroundActivated. A continuación, puede recuperar los argumentos predefinidos y la entrada del usuario, similar a la activación en primer plano.

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

Establecer una hora de expiración

En Windows 10, todas las notificaciones del sistema van en el Centro de actividades una vez descartadas o ignoradas por el usuario, por lo que los usuarios pueden ver la notificación después de que el elemento emergente se haya ido.

Sin embargo, si el mensaje de la notificación solo es relevante durante un período de tiempo, debe establecer una hora de expiración en la notificación del sistema para que los usuarios no vean información obsoleta de la aplicación. Por ejemplo, si una promoción solo es válida durante 12 horas, establezca el tiempo de expiración en 12 horas. En el código siguiente, establecemos el tiempo de expiración en 2 días.

Nota:

El tiempo de expiración predeterminado y máximo para las notificaciones del sistema local es de 3 días.

// Create toast content and show the toast!
new ToastContentBuilder()
    .AddText("Expires in 2 days...")
    .Show(toast =>
    {
        toast.ExpirationTime = DateTime.Now.AddDays(2);
    });

Proporcione una clave principal para la notificación del sistema.

Si desea quitar o reemplazar mediante programación la notificación que envía, debe usar la propiedad Tag (y, opcionalmente, la propiedad Group) para proporcionar una clave principal para la notificación. A continuación, puede usar esta clave principal en el futuro para quitar o reemplazar la notificación.

Para obtener más información sobre cómo reemplazar o quitar notificaciones del sistema ya entregadas, consulta Inicio rápido: Administración de notificaciones del sistema en el centro de actividades (XAML).

La etiqueta y el grupo combinados actúan como una clave principal compuesta. El grupo es el identificador más genérico, donde puede asignar grupos como "wallPosts", "messages", "friendRequests", etcetera. Y, a continuación, Tag debe identificar de forma única la notificación desde dentro del grupo. Mediante el uso de un grupo genérico, puede quitar todas las notificaciones de ese grupo mediante la API RemoveGroup.

// Create toast content and show the toast!
new ToastContentBuilder()
    .AddText("New post on your wall!")
    .Show(toast =>
    {
        toast.Tag = "18365";
        toast.Group = "wallPosts";
    });

Borrar las notificaciones

Las aplicaciones son responsables de quitar y borrar sus propias notificaciones. Cuando se inicia la aplicación, no borramos automáticamente las notificaciones.

Windows solo quitará automáticamente una notificación si el usuario hace clic explícitamente en la notificación.

Este es un ejemplo de lo que debe hacer una aplicación de mensajería...

  1. El usuario recibe varias notificaciones del sistema sobre los nuevos mensajes de una conversación.
  2. El usuario pulsa una de esas notificaciones del sistema para abrir la conversación
  3. La aplicación abre la conversación y, a continuación, borra todas las notificaciones del sistema de esa conversación (mediante RemoveGroup en el grupo proporcionado por la aplicación para esa conversación).
  4. El Centro de actividades del usuario ahora refleja correctamente el estado de notificación, ya que no hay notificaciones obsoletas para esa conversación que queda en el Centro de actividades.

Para obtener información sobre cómo borrar todas las notificaciones o quitar notificaciones específicas, consulta Inicio rápido: Administración de notificaciones del sistema en el centro de actividades (XAML).

ToastNotificationManagerCompat.History.Clear();

Recursos