Compartilhar via


Enviar uma notificação de aplicativo local de um aplicativo C#

Uma notificação do aplicativo é uma mensagem que seu aplicativo pode construir e entregar ao usuário enquanto ele não estiver no seu aplicativo.

Captura de tela de uma notificação do aplicativo

Este guia de início rápido orienta você pelas etapas para criar, entregar e exibir uma notificação de aplicativo do Windows 10 ou Windows 11 usando conteúdo avançado e ações interativas. Este início rápido usa notificações locais, que são a notificação mais simples a ser implementada. Todos os tipos de aplicativos (WPF, UWP, WinForms, console) podem enviar notificações!

Note

O termo "notificação de brinde" está sendo substituído por "notificação do aplicativo". Esses termos se referem ao mesmo recurso do Windows, mas, com o tempo, eliminaremos gradualmente o uso de "notificação do tipo toast" na documentação.

Important

Se você estiver escrevendo um aplicativo C++, consulte a documentação de UWP do C++ ou a documentação de WRL do C++.

Etapa 1: Instalar o pacote NuGet

Na solução do Visual Studio, clique com o botão direito do mouse no projeto, clique em "Gerenciar pacotes NuGet..." e pesquise e instale o Microsoft.Toolkit.Uwp.Notificationspacote NuGet versão 7.0 ou superior.

Important

Os aplicativos da área de trabalho do .NET Framework que ainda usam packages.config devem migrar para PackageReference, caso contrário, os SDKs do Windows não serão referenciados corretamente. Em seu projeto, clique com o botão direito do mouse em "Referências" e clique em "Migrar packages.config para PackageReference".

Os aplicativos WPF do .NET Core 3.0 devem ser atualizados para o .NET Core 3.1, caso contrário, as APIs estarão ausentes.

Os aplicativos .NET devem usar um dos TFMs do Windows, caso contrário, as APIs de envio e gerenciamento de notificação do aplicativo, como Show() , estarão ausentes. Defina o TFM como net6.0-windows10.0.17763.0 ou posterior.

Nosso exemplo de código usará esse pacote. Esse pacote permite que você crie notificações de aplicativo sem usar XML e também permite que aplicativos da área de trabalho enviem notificações de aplicativo.

Etapa 2: Enviar uma notificação do aplicativo

No Windows 10 e no Windows 11, o conteúdo da notificação do aplicativo é descrito usando uma linguagem adaptável que permite grande flexibilidade com a aparência da notificação. Para obter mais informações, consulte a documentação do conteúdo da notificação do aplicativo.

Começaremos com uma notificação simples baseada em texto. Construa o conteúdo da notificação (usando a biblioteca de notificações) e mostre a notificação! Observe que o namespace está Microsoft.Toolkit.Uwp.Notifications.

Notificação de texto simples
// 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

Tente executar este código e você verá a notificação aparecer!

Etapa 3: Manipular a ativação

Depois de mostrar uma notificação, você provavelmente precisará lidar com o usuário que clica na notificação (seja exibindo conteúdo específico depois que o usuário clica nele, abrindo seu aplicativo em geral ou executando uma ação quando o usuário clica na notificação).

As etapas para lidar com a ativação diferem para UWP e para aplicativos de área de trabalho empacotados e não empacotados.

Primeiro, no seu Package.appxmanifest, adicione:

  1. Declaração para xmlns:com
  2. Declaração para xmlns:desktop
  3. No atributo IgnorableNamespaces, com e desktop
  4. desktop:Extensão para windows.toastNotificationActivation para declarar o CLSID do ativador de notificação (usando um novo GUID de sua escolha).
  5. Somente MSIX: com:Extension para o ativador COM, utilizando o GUID da etapa nº 4. Certifique-se de incluir o Arguments="-ToastActivated" para que você saiba que seu lançamento foi de uma notificação

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>

Em seguida, no código de inicialização do aplicativo (App.xaml.cs OnStartup para WPF), assine o 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);
    });
};

Quando o usuário clicar em qualquer uma de suas notificações (ou um botão na notificação), o seguinte ocorrerá...

Se o seu aplicativo estiver em execução no momento...

  1. O evento ToastNotificationManagerCompat.OnActivated será invocado em um thread em segundo plano.

Se o seu aplicativo estiver fechado no momento...

  1. O EXE do aplicativo será iniciado e ToastNotificationManagerCompat.WasCurrentProcessToastActivated() retornará true para indicar que o processo foi iniciado devido a uma ativação moderna e que o manipulador de eventos será invocado em breve.
  2. Em seguida, o evento ToastNotificationManagerCompat.OnActivated será invocado em um thread em segundo plano.

Etapa 4: Manipular a desinstalação

Você não precisa fazer nada! Quando os aplicativos MSIX são desinstalados, todas as notificações e quaisquer outros recursos relacionados são limpos automaticamente.

Adicionar imagens

Você pode adicionar conteúdo avançado a notificações. Adicionaremos uma imagem inline e uma imagem de perfil (que substitui o logotipo do aplicativo).

Note

As imagens podem ser usadas no pacote do aplicativo, no armazenamento local do aplicativo ou na Web. A partir do Fall Creators Update, as imagens da Web podem ter até 3 MB em conexões normais e 1 MB em conexões limitadas. Em dispositivos que ainda não executam o Fall Creators Update, as imagens da Web não devem ter mais de 200 KB.

Important

Há suporte para imagens http somente em aplicativos empacotados que têm a funcionalidade da Internet em seu manifesto. Aplicativos não empacotados não suportam imagens http; você deve baixar a imagem para os dados locais do aplicativo e referenciá-la localmente.

Toast com imagens
// 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();

Adicionar botões e entradas

Você pode adicionar botões e entradas para tornar suas notificações interativas. Os botões podem iniciar seu aplicativo em primeiro plano, um protocolo ou sua tarefa em segundo plano. Adicionaremos uma caixa de texto de resposta, um botão "Curtir" e um botão "Exibir" que abre a imagem.

Captura de tela de uma notificação de aplicativo com entradas e botões
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();

A ativação dos botões de primeiro plano é tratada da mesma maneira que o corpo principal da notificação (o método OnActivated do seu App.xaml.cs será chamado).

Observe que os argumentos adicionados à notificação de aplicativo de nível superior (como a ID de conversa) também serão retornados quando os botões forem clicados, desde que os botões usem a API addArgument como visto acima (se você personalizar atribuir argumentos em um botão, os argumentos de nível superior não serão incluídos).

Gerenciar a ativação em segundo plano

Para aplicativos de desktop, as ativações em segundo plano são tratadas da mesma forma que as ativações em primeiro plano (o manipulador de eventos OnActivated será acionado). Você pode optar por não mostrar nenhuma interface do usuário e fechar seu aplicativo depois de lidar com a ativação.

Definir um tempo de expiração

No Windows 10, todas as notificações do aplicativo entram na Central de Ações depois de serem dispensadas ou ignoradas pelo usuário, para que os usuários possam examinar as notificações depois que o pop-up desaparece.

No entanto, se a mensagem em sua notificação for relevante apenas por um período de tempo, você deverá definir um tempo de expiração na notificação do aplicativo para que os usuários não vejam informações obsoletas do seu aplicativo. Por exemplo, se uma promoção for válida apenas por 12 horas, defina o tempo de expiração como 12 horas. No código abaixo, definimos o tempo de expiração como 2 dias.

Note

O tempo de expiração padrão e máximo para notificações de aplicativo local é de 3 dias.

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

Fornecer uma chave primária para sua notificação

Se você quiser remover ou substituir programaticamente a notificação enviada, precisará usar a propriedade Tag (e, opcionalmente, a propriedade Group) para fornecer uma chave primária para sua notificação. Em seguida, você pode usar essa chave primária no futuro para remover ou substituir a notificação.

Para ver mais detalhes sobre como substituir/remover notificações de aplicativo já entregues, consulte Início Rápido: Gerenciando notificações do sistema na central de ações (XAML).

A tag e o grupo combinados funcionam como uma chave primária composta. O grupo é o identificador mais genérico, onde você pode criar grupos como "wallPosts", "messages", "friendRequests" etc. Em seguida, a tag deve identificar exclusivamente a notificação propriamente dita dentro do grupo. Usando um grupo genérico, você pode remover todas as notificações desse grupo usando a 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";
    });

Limpar suas notificações

Os aplicativos são responsáveis por remover e limpar suas próprias notificações. Quando seu aplicativo é iniciado, NÃO limpamos automaticamente suas notificações.

O Windows só removerá automaticamente uma notificação se o usuário clicar explicitamente na notificação.

Aqui está um exemplo do que um aplicativo de mensagens deve fazer...

  1. O usuário recebe várias notificações de aplicativo sobre novas mensagens em uma conversa.
  2. O usuário toca em uma dessas notificações para abrir a conversa.
  3. O aplicativo abre a conversa e limpa todas as notificações dessa conversa (usando RemoveGroup no grupo fornecido pelo aplicativo para essa conversa).
  4. A Central de Ações do usuário agora reflete corretamente o estado de notificação, já que não há notificações obsoletas para essa conversa deixada na Central de Ações.

Para saber mais sobre como limpar todas as notificações ou remover notificações específicas, consulte Início Rápido: Gerenciamento de notificações toast na central de ações (XAML).

ToastNotificationManagerCompat.History.Clear();

Resources