Compartir a través de


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

Una notificación de aplicación es un mensaje que su aplicación puede construir y entregar a su usuario mientras no está dentro de su aplicación.

Captura de pantalla de una notificación de aplicación

Este inicio rápido le guía por los pasos para crear, entregar y mostrar una notificación de aplicación 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!

Note

El término "notificación emergente" se reemplaza por "notificación de aplicación". Estos términos hacen referencia a la misma característica de Windows, pero con el tiempo eliminaremos gradualmente el uso de "notificación emergente" en la documentación.

Important

Si estás escribiendo una aplicación de C++, consulta la documentación de C++ UWP o de 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.Notificationspaquete NuGet.

Important

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 de notificaciones de la aplicación, 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 de aplicación sin usar XML y también permite a las aplicaciones de escritorio enviar notificaciones de aplicaciones.

Paso 2: Enviar una notificación de aplicación

En Windows 10 y Windows 11, el contenido de notificación de la aplicación 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 de la notificación de la aplicación .

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: Controlar 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.

En primer lugar, agregue lo siguiente en el Package.appxmanifest:

  1. Declaración para xmlns:com
  2. Declaración de xmlns:desktop
  3. En el atributo IgnorableNamespaces, com y desktop.
  4. escritorio:extensión para windows.toastNotificationActivation para declarar el CLSID del activador de notificaciones toast (con un nuevo GUID de su elección).
  5. Solo MSIX: com:Extensión para el activador COM utilizando el GUID del paso 4. Asegúrese de incluir el Arguments="-ToastActivated" para que sepa que el lanzamiento provino de una notificación.

Package.appxmanifest

<!--Add these namespaces-->
<Package
  ...
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  IgnorableNamespaces="... com desktop">
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

        <!--Specify which CLSID to activate when toast clicked-->
        <desktop:Extension Category="windows.toastNotificationActivation">
          <desktop:ToastNotificationActivation ToastActivatorCLSID="replaced-with-your-guid-C173E6ADF0C3" /> 
        </desktop:Extension>

        <!--Register COM CLSID LocalServer32 registry key-->
        <com:Extension Category="windows.comServer">
          <com:ComServer>
            <com:ExeServer Executable="YourProject\YourProject.exe" Arguments="-ToastActivated" DisplayName="Toast activator">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" DisplayName="Toast activator"/>
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>

      </Extensions>
    </Application>
  </Applications>
 </Package>

A continuación, en el código de inicio de la aplicación (App.xaml.cs OnStartup para WPF), suscríbase al evento OnActivated.

// Listen to notification activation
ToastNotificationManagerCompat.OnActivated += toastArgs =>
{
    // Obtain the arguments from the notification
    ToastArguments args = ToastArguments.Parse(toastArgs.Argument);

    // Obtain any user input (text boxes, menu selections) from the notification
    ValueSet userInput = toastArgs.UserInput;

    // Need to dispatch to UI thread if performing UI operations
    Application.Current.Dispatcher.Invoke(delegate
    {
        // TODO: Show the corresponding content
        MessageBox.Show("Toast activated. Args: " + toastArgs.Argument);
    });
};

Cuando el usuario hace clic en cualquiera de las notificaciones (o un botón de la notificación), se producirá lo siguiente...

Si tu aplicación se está ejecutando actualmente...

  1. El evento ToastNotificationManagerCompat.OnActivated se invocará en un hilo en segundo plano.

Si la aplicación está cerrada actualmente...

  1. El EXE de la aplicación se iniciará y ToastNotificationManagerCompat.WasCurrentProcessToastActivated() devolverá true para indicar que el proceso se inició debido a una activación moderna y que pronto se invocará el controlador de eventos.
  2. A continuación, se invocará el evento ToastNotificationManagerCompat.OnActivated en un subproceso en segundo plano.

Paso 4: Controlar la desinstalación

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

Agregar imágenes

Puede agregar contenido enriquecido a las notificaciones. Agregaremos una imagen en línea y una imagen de perfil (sustitución del logotipo de la aplicación).

Note

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

Important

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 referenciarla localmente.

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

Agregar 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 de aplicación 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 los botones de primer plano se gestiona de la misma manera que el cuerpo principal de la notificación (se llamará a su App.xaml.cs OnActivated).

Tenga en cuenta que los argumentos agregados a la notificación de aplicación 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).

Controlar la activación en segundo plano

En el caso de las aplicaciones de escritorio, las activaciones en segundo plano se controlan igual que las activaciones en primer plano (se desencadenará el controlador de eventos OnActivated ). Puedes optar por no mostrar ninguna interfaz de usuario y cerrar la aplicación después de controlar la activación.

Establecer una hora de expiración

En Windows 10, todas las notificaciones de la aplicación 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 haya desaparecido.

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 de la aplicación 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.

Note

El tiempo de expiración predeterminado y máximo para las notificaciones de aplicación 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.

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 de aplicaciones 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", etc. 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 el RemoveGroup API.

// 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 de aplicación sobre los nuevos mensajes de una conversación.
  2. El usuario pulsa una de esas notificaciones para abrir la conversación.
  3. La aplicación abre la conversación y, a continuación, borra todas las notificaciones de esa conversación (mediante RemoveGroup en el grupo proporcionado por la aplicación para esa conversación).
  4. El Centro de actividades ahora refleja correctamente el estado de las notificaciones, ya que no quedan notificaciones obsoletas para esa conversación 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 emergentes en el centro de acciones (XAML).

ToastNotificationManagerCompat.History.Clear();

Resources