Partilhar via


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

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

Captura de ecrã de uma notificação de aplicação

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 guia de início rápido usa notificações locais, que são a notificação mais simples de implementar. Todos os tipos de aplicativos (WPF, UWP, WinForms, console) podem enviar notificações!

Note

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

Important

Caso esteja a escrever uma aplicação C++, consulte a documentação do C++ UWP ou do C++ WRL.

Etapa 1: Instalar o pacote NuGet

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

Important

Os aplicativos de á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. No seu projeto, clique com o botão direito 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.

As aplicações .NET devem usar um dos TFMs do Windows, caso contrário, as APIs de envio e gestão de notificações da aplicação estarão Show() ausentes. Defina o seu TFM como net6.0-windows10.0.17763.0 ou posterior.

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

Etapa 2: enviar uma notificação de aplicativo

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

Começaremos com uma simples notificação 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 é 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: Gerir a ativação

Depois de mostrar uma notificação, você provavelmente precisará lidar com o usuário clicando na notificação (quer isso signifique exibir conteúdo específico depois que o usuário clica nele, abrir seu aplicativo em geral ou executar uma ação quando o usuário clica na notificação).

As etapas para lidar com a ativação diferem para aplicações da Plataforma Universal do Windows (UWP) e para aplicações de área de trabalho empacotadas e não empacotadas.

Primeiro, no seu Package.appxmanifest, adicione:

  1. Declaração para xmlns:com
  2. Declaração para xmlns:desktop
  3. No atributo IgnorableNamespaces, com e área de trabalho
  4. desktop:Extensão para windows.toastNotificationActivation de forma a declarar o seu CLSID de ativador de notificação toast (usando um novo GUID à sua escolha).
  5. Apenas MSIX: com:Extension para o ativador COM usando o GUID da etapa #4. Certifique-se de incluir o Arguments="-ToastActivated" para que você saiba que seu lançamento foi a partir 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 de código de inicialização do seu aplicativo (App.xaml.cs OnStartup para WPF), inscreva-se no 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 clica em qualquer uma das suas notificações (ou em um botão na notificação), o seguinte acontecerá...

Se a sua aplicação estiver atualmente a ser executada...

  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 seu 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 numa thread em segundo plano.

Etapa 4: Manipular a desinstalação

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

Adicionar imagens

Você pode adicionar conteúdo avançado às notificações. Adicionaremos uma imagem embutida e uma imagem de perfil (substituição do logotipo do aplicativo).

Note

As imagens podem ser usadas a partir do pacote do aplicativo, do armazenamento local do aplicativo ou da Web. A partir da 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 a Atualização para Criadores de Outono, as imagens na web não devem ter mais de 200 KB.

Important

As imagens http são suportadas apenas em aplicações em pacote que têm acesso à internet no seu manifesto. As aplicações não empacotadas não suportam imagens http; você deve descarregar a imagem para os dados locais da aplicação e fazer referência a ela localmente.

Brinde 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 "Gosto" e um botão "Ver" que abre a imagem.

Captura de ecrã de uma notificação de aplicação 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 forma que o corpo da notificação principal (o método OnActivated do seu App.xaml.cs será chamado).

Observe que os argumentos adicionados à notificação do aplicativo de nível superior (como 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ê atribuir argumentos personalizados em um botão, os argumentos de nível superior não serão incluídos).

Manipular a ativação em segundo plano

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

Definir um tempo de expiração

No Windows 10, todas as notificações de aplicativos vão para a Central de Ações depois de serem descartadas ou ignoradas pelo usuário, para que os usuários possam ver sua notificação depois que o pop-up desaparecer.

No entanto, se a mensagem na sua notificação for relevante apenas por um período de tempo, você deve 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 para 12 horas. No código abaixo, definimos o tempo de expiração para ser de 2 dias.

Note

O tempo de expiração padrão e máximo para notificações de aplicativos locais é 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);
    });

Forneça uma chave primária para sua notificação

Se quiser remover ou substituir programaticamente a notificação enviada, você 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 aplicativos já entregues, consulte Guia de início rápido: gerenciando notificações do sistema na central de ações (XAML).

Tag e Grupo combinados atuam como uma chave primária composta. Grupo é o identificador mais genérico, onde você pode atribuir grupos como "wallPosts", "mensagens", "friendRequests", etc. E, em seguida, a Tag deve identificar exclusivamente a própria notificação 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 as notificações

As aplicações são responsáveis por remover e limpar as 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 utilizador 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 do 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, em seguida, 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, uma vez que não há notificações obsoletas para essa conversa deixadas na Central de Ações.

Para saber mais sobre como limpar todas as notificações ou remover notificações específicas, consulte Guia de início rápido: gerenciando notificações do sistema na central de ações (XAML).

ToastNotificationManagerCompat.History.Clear();

Resources