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

  • Artigo

Uma notificação do sistema é 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 sistema

Este início rápido orienta você pelas etapas para criar, entregar e exibir uma notificação do Sistema 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!

Importante

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

Etapa 1: Instalar o pacote NuGet

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

Importante

.NET Framework aplicativos da área de trabalho que ainda usam packages.config devem migrar para PackageReference; caso contrário, os SDKs do Windows não serão referenciados corretamente. No 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 do sistema, 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 do sistema sem usar XML e também permite que aplicativos da área de trabalho enviem notificações do sistema.

Etapa 2: Enviar uma notificação do sistema

No Windows 10 e Windows 11, seu conteúdo de notificação do sistema é 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 do sistema.

Começaremos com uma notificação simples baseada em texto. Construa o conteúdo da notificação (usando a biblioteca 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 esse código e você verá a notificação aparecer!

Etapa 3: Manipulando a ativação

Depois de mostrar uma notificação, você provavelmente precisará lidar com o usuário clicando na notificação (se isso significa abrir conteúdo específico depois que o usuário clicar nele, abrir seu aplicativo em geral ou executar uma ação quando o usuário clicar 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.

Quando o usuário clica na notificação (ou em um botão na notificação com ativação em primeiro plano), o App.xaml.csOnActivated do aplicativo será invocado e os argumentos adicionados serão retornados.

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

Você deve inicializar seu quadro e ativar a janela como no código OnLaunched. OnLaunched não será chamada se o usuário clicar na notificação do sistema, mesmo se o aplicativo estava fechado e está sendo iniciado pela primeira vez. Em geral, é recomendável combinar OnLaunched e OnActivated em seu próprio método OnLaunchedOrActivated, pois a mesma inicialização deve ocorrer em ambos.

Etapa 4: Manipulando a desinstalação

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

Adição de 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).

Observação

As imagens podem ser usadas do pacote do aplicativo, do armazenamento local do aplicativo ou da Web. Na the 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 Fall Creators Update, as imagens da Web devem ser maiores do que 200 KB.

Importante

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

Notificação do sistema 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();

Adicionando 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 do sistema 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 de botões de primeiro plano é tratada da mesma forma que o main corpo da notificação do sistema (seu App.xaml.cs OnActivated será chamado).

Observe que os argumentos adicionados ao sistema de nível superior (como a ID da 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 a atribuição de argumentos em um botão, os argumentos de nível superior não serão incluídos).

Manipulação de ativação em segundo plano

Quando você especifica a ativação em segundo plano na notificação do sistema (ou em um botão de notificação do sistema), a tarefa em segundo plano será executada em vez de ativar o aplicativo em primeiro plano.

Para saber mais sobre tarefas em segundo plano, consulte Suporte ao aplicativo com tarefas em segundo plano.

Se você estiver direcionando o build 14393 ou posterior, poderá usar tarefas em segundo plano no processo, o que simplifica muito as coisas. Observe que tarefas em segundo plano em processamento não são executadas em versões mais antigas do Windows. Vamos usar uma tarefa em segundo plano em processamento nesse exemplo 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();

Em seguida, em seu App.xaml.cs, substitua o método OnBackgroundActivated. Em seguida, você pode recuperar os argumentos predefinidos e a entrada do usuário, semelhante à ativação em primeiro 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();
}

Definir um tempo de expiração

No Windows 10, todas as notificações do sistema vão para a Central de Ações depois que são descartadas ou ignorados pelo usuário para que possam visualizar a notificação depois que o pop-up some.

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

Observação

O tempo de expiração máximo e padrão para notificações do sistema local é de três 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 a notificação do sistema

Se você quiser remover ou substituir a notificação enviada por meio de programação, é necessário usar a propriedade Tag (e, opcionalmente, a propriedade Group) a fim de fornecer uma chave primária para a 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 do sistema disponibilizadas, consulte Guia de início rápido: gerenciamento de notificações do sistema na central de ações (XAML).

Tag e Group combinadas atuam como uma chave primária composta. Group é o identificador mais genérico, no qual você pode atribuir a grupos como "wallPosts", "messages", "friendRequests" etc. Tag deve identificar exclusivamente a notificação dentro do grupo. Ao usar um grupo genérico, você pode remover todas as notificações dele 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

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

O Windows removerá uma notificação automaticamente apenas se o usuário clicar explicitamente nela.

Veja um exemplo do que um aplicativo de mensagens deve fazer...

  1. O usuário recebe várias notificações do sistema sobre novas mensagens em uma conversa
  2. O usuário toca em um dessas notificações do sistema para abrir a conversa
  3. O aplicativo abre a conversa e, em seguida, apaga todas as notificações do sistema relativas a ela (usando RemoveGroup no grupo fornecido pelo aplicativo para a conversa)
  4. Agora, a Central de Ações do usuário reflete adequadamente o estado da notificação, pois não há notificações obsoletas dessa conversa na Central de Ações.

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

ToastNotificationManagerCompat.History.Clear();

Recursos