Início Rápido: Usar notificações de aplicativo com o SDK do Aplicativo Windows

Neste início rápido, você criará um aplicativo WinUI que envia e responde às notificações de aplicativo local usando o SDK do Aplicativo Windows.

Para obter aplicativos de exemplo completos que implementam notificações de aplicativo, consulte o repositório SDK do Aplicativo Windows Samples no GitHub.

Important

Não há suporte para notificações de aplicativo para aplicativos com privilégios elevados (administrador).

Prerequisites

• Instalar Visual Studio 2022 (v17.6+)
  • Download 2022 Community
  • Download 2022 Professional
  • Download 2022 Enterprise
• Inclua cargas de trabalho C++ para desenvolvimento em C++ ou .NET para desenvolvimento em C#.
• Verifique se as ferramentas de empacotamento MSIX no desenvolvimento de aplicativos para área de trabalho .NET estão selecionadas.
• Verifique se Windows Desenvolvimento de Aplicativos está selecionado.
• Certifique-se de que Desenvolvimento de Aplicativos de Interface do Usuário do Windows está selecionado.

Para obter mais informações sobre como gerenciar cargas de trabalho em Visual Studio, consulte Modify Visual Studio cargas de trabalho, componentes e pacotes de idiomas. Para obter mais informações sobre como começar a usar o WinUI, consulte Introdução ao WinUI. Para adicionar o SDK do Aplicativo Windows a um projeto existente, consulte Use o SDK do Aplicativo Windows em um projeto existente.

Criar um novo projeto de aplicativo WinUI no Visual Studio

1. Em Visual Studio, crie um novo projeto.
2. Na caixa de diálogo Criar um novo projeto , defina o filtro de idioma como "C#" ou "C++" e o filtro de plataforma como "WinUI" e selecione o modelo de projeto "Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho)".
3. Nomeie o novo projeto como "AppNotificationsExample".

Enviar uma notificação de aplicativo local

Nesta seção, você adicionará um botão ao aplicativo que envia uma notificação de aplicativo local quando clicado. A notificação incluirá conteúdo de texto e uma imagem de logotipo do aplicativo. Você também adicionará duas caixas de texto somente leitura que exibirão os argumentos de ativação quando o usuário clicar na notificação.

Primeiro, adicione um controle Button e dois controles TextBox ao seu MainWindow.xaml:

C#

<!-- MainWindow.xaml -->
<Button x:Name="SendNotificationButton" Content="Send App Notification" Click="SendNotificationButton_Click"/>

<TextBlock Text="Activation arguments:" FontWeight="SemiBold" Margin="0,12,0,0"/>
<TextBox x:Name="ActionTextBox" Header="action" IsReadOnly="True" PlaceholderText="(none)"/>
<TextBox x:Name="ExampleEventIdTextBox" Header="exampleEventId" IsReadOnly="True" PlaceholderText="(none)"/>

C++

<!-- MainWindow.xaml -->
<Button x:Name="SendNotificationButton" Content="Send App Notification" Click="SendNotificationButton_Click"/>

<TextBlock Text="Activation arguments:" FontWeight="SemiBold" Margin="0,12,0,0"/>
<TextBox x:Name="ActionTextBox" Header="action" IsReadOnly="True" PlaceholderText="(none)"/>
<TextBox x:Name="ExampleEventIdTextBox" Header="exampleEventId" IsReadOnly="True" PlaceholderText="(none)"/>

As APIs de notificação do aplicativo estão nos namespaces Microsoft.Windows.AppNotifications e Microsoft.Windows.AppNotifications.Builder. Adicione as seguintes referências ao seu projeto:

C#

// MainWindow.xaml.cs
using Microsoft.Windows.AppNotifications;
using Microsoft.Windows.AppNotifications.Builder;

C++

Adicione as seguintes diretivas de inclusão ao arquivo de cabeçalho pré-compilado (pch.h):

// pch.h
#include <winrt/Microsoft.Windows.AppNotifications.h>
#include <winrt/Microsoft.Windows.AppNotifications.Builder.h>

Agora, adicione o código a seguir ao manipulador de cliques do botão. Este exemplo usa AppNotificationBuilder para construir conteúdo de notificação, incluindo argumentos que serão passados de volta para o aplicativo quando o usuário clicar na notificação, em uma imagem de logotipo do aplicativo e no texto. A notificação também inclui um botão que demonstra a execução de uma ação sem iniciar a interface do usuário do aplicativo. O método BuildNotification cria o objeto AppNotification e AppNotificationManager.Show o exibe para o usuário.

C#

// MainWindow.xaml.cs
private void SendNotificationButton_Click(object sender, RoutedEventArgs e)
{
    var appNotification = new AppNotificationBuilder()
        .AddArgument("action", "NotificationClick")
        .AddArgument("exampleEventId", "1234")
        .SetAppLogoOverride(new System.Uri("ms-appx:///Assets/Square150x150Logo.png"), AppNotificationImageCrop.Circle)
        .AddText("This is text content for an app notification.")
        .AddButton(new AppNotificationButton("Perform action without launching app")
            .AddArgument("action", "BackgroundAction"))
        .BuildNotification();

    AppNotificationManager.Default.Show(appNotification);
}

C++

// MainWindow.xaml.cpp
void MainWindow::SendNotificationButton_Click(winrt::Windows::Foundation::IInspectable const&, winrt::Microsoft::UI::Xaml::RoutedEventArgs const&)
{
    auto appNotification{ AppNotificationBuilder()
        .AddArgument(L"action", L"NotificationClick")
        .AddArgument(L"exampleEventId", L"1234")
        .SetAppLogoOverride(winrt::Windows::Foundation::Uri(L"ms-appx:///Assets/Square150x150Logo.png"), AppNotificationImageCrop::Circle)
        .AddText(L"This is text content for an app notification.")
        .AddButton(AppNotificationButton(L"Perform action without launching app")
            .AddArgument(L"action", L"BackgroundAction"))
        .BuildNotification() };

    AppNotificationManager::Default().Show(appNotification);
}

Neste ponto, você pode criar e executar seu aplicativo. Clique no botão Enviar Notificação do Aplicativo para exibir a notificação. Observe que clicar na notificação ainda não executará nenhuma ação – na próxima seção, você aprenderá a lidar com a ativação do aplicativo para que seu aplicativo possa responder quando um usuário clicar na notificação.

Note

Não há suporte para notificações de aplicativo quando seu aplicativo está em execução com privilégios de administrador (elevado). A apresentação falhará silenciosamente e nenhuma notificação será exibida. Certifique-se de executar seu aplicativo sem elevação ao testar notificações.

Atualizar o arquivo de manifesto do pacote do aplicativo

O Package.appmanifest arquivo fornece os detalhes do pacote MSIX para um aplicativo. Para permitir que seu aplicativo seja iniciado quando um usuário interage com uma notificação do aplicativo, você deve atualizar o arquivo de manifesto do pacote do aplicativo para que seu aplicativo seja registrado com o sistema como um destino para a ativação da notificação do aplicativo. Para obter mais informações sobre manifestos do pacote de aplicativos, consulte o manifesto do pacote do aplicativo.

1. Edite o arquivo Package.appxmanifest clicando com o botão direito do mouse no arquivo em Gerenciador de Soluções e selecionando View Code.
2. Adicionar xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" e xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" namespaces a <Package>.
3. Adicionar um <desktop:Extension> elemento em <Extensions>. Defina o atributo Category como "windows.toastNotificationActivation" para declarar que seu aplicativo pode ser ativado por notificações de app.
   • Adicione um elemento filho <desktop:ToastNotificationActivation> e defina o ToastActivatorCLSID como um GUID que identificará exclusivamente seu aplicativo.
   • Você pode gerar um GUID no Visual Studio acessando Tools > Criar GUID.
4. Adicione um <com:Extension> elemento <Extensions> abaixo e defina o Category atributo como "windows.comServer". O arquivo de manifesto de exemplo mostrado abaixo mostra a sintaxe desse elemento.
   • Atualize o atributo do elemento <com:ExeServer> com o nome executável Executable. Para este exemplo, o nome será "AppNotificationsExample.exe".
   • Especifique Arguments="----AppNotificationActivated:" para garantir que SDK do Aplicativo Windows possa processar o conteúdo da notificação como um tipo AppNotification.
   • Defina o Id atributo do <com:Class> elemento como o mesmo GUID usado para o ToastActivatorCLSID atributo.

<!--package.appxmanifest-->

<Package
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

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

        <!--Register COM CLSID-->    
        <com:Extension Category="windows.comServer">
          <com:ComServer>
            <com:ExeServer Executable="SampleApp.exe" DisplayName="SampleApp" Arguments="----AppNotificationActivated:">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" />
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>
    
      </Extensions>
    </Application>
  </Applications>
 </Package>

Manipular a ativação de uma notificação do aplicativo

Quando um usuário clica em uma notificação do aplicativo ou em um botão dentro de uma notificação, seu aplicativo precisa responder adequadamente. Há dois cenários comuns de ativação:

1. Iniciar com a interface do usuário — O usuário clica no corpo da notificação e seu aplicativo deve iniciar ou vir para o primeiro plano, exibindo conteúdo relevante.
2. Ação em segundo plano — O usuário clica em um botão na notificação que dispara uma ação (como enviar uma resposta) sem mostrar nenhuma interface do usuário do aplicativo.

Para dar suporte a ambos os cenários, o fluxo de ativação do aplicativo deve criar a janela principal, OnLaunched mas não ativá-la imediatamente. Em vez disso, registre o evento AppNotificationManager.NotificationInvoked , chame AppNotificationManager.Register e, em seguida, verifique AppInstance.GetActivatedEventArgs para determinar se o aplicativo foi iniciado a partir de uma notificação ou de uma inicialização normal. Se a inicialização foi disparada por uma notificação, seu código pode inspecionar os argumentos de notificação e decidir se deseja mostrar a janela ou manipular a ação silenciosamente e sair.

O NotificationInvoked evento manipula cliques que ocorrem enquanto o aplicativo já está em execução. Quando o aplicativo não está em execução, Windows inicia o aplicativo por meio da ativação COM e o tipo de ativação é relatado como Launch, não AppNotification. Os argumentos de notificação são entregues por meio do NotificationInvoked evento.

Important

Você deve chamar AppNotificationManager.Register antes de chamar AppInstance.GetActivatedEventArgs.

Important

A configuração activationType="background" na carga XML de notificação é ignorada para aplicativos da área de trabalho. Você deve processar os argumentos de ativação em seu código e decidir se deseja exibir uma janela ou não.

C#

// App.xaml.cs
using Microsoft.UI.Xaml;
using Microsoft.Windows.AppLifecycle;
using Microsoft.Windows.AppNotifications;

namespace AppNotificationsExample;

public partial class App : Application
{
    private Window? _window;

    public App()
    {
        InitializeComponent();
    }

    protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
    {
        _window = new MainWindow();

        AppNotificationManager.Default.NotificationInvoked += OnNotificationInvoked;
        AppNotificationManager.Default.Register();

        var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();

        if (activatedArgs.Kind == ExtendedActivationKind.AppNotification)
        {
            // App was launched by clicking a notification
            var notificationArgs = (AppNotificationActivatedEventArgs)activatedArgs.Data;
            HandleNotification(notificationArgs);
        }
        else
        {
            // Normal launch
            _window.Activate();
        }
    }

    private void OnNotificationInvoked(AppNotificationManager sender, AppNotificationActivatedEventArgs args)
    {
        // Notification clicked while app is already running
        HandleNotification(args);
    }

    private void HandleNotification(AppNotificationActivatedEventArgs args)
    {
        var action = args.Arguments.ContainsKey("action") ? args.Arguments["action"] : "(none)";
        var exampleEventId = args.Arguments.ContainsKey("exampleEventId") ? args.Arguments["exampleEventId"] : "(none)";

        _window!.DispatcherQueue.TryEnqueue(() =>
        {
            switch (action)
            {
                case "BackgroundAction":
                    // Handle the action without showing the app window.
                    // If the window was never shown, exit the app.
                    if (!_window.Visible)
                    {
                        Application.Current.Exit();
                    }
                    break;

                default:
                    // Bring the app to the foreground and display the notification arguments.
                    _window.Activate();
                    ((MainWindow)_window).UpdateNotificationUI(action, exampleEventId);
                    break;
            }
        });
    }
}

C++

Adicione a HandleNotification declaração à App classe em App.xaml.h:

// App.xaml.h
#pragma once

#include "App.xaml.g.h"

namespace winrt::AppNotificationsExample::implementation
{
    struct App : AppT<App>
    {
        App();

        void OnLaunched(Microsoft::UI::Xaml::LaunchActivatedEventArgs const&);
        void OnNotificationInvoked(winrt::Microsoft::Windows::AppNotifications::AppNotificationManager const& sender, winrt::Microsoft::Windows::AppNotifications::AppNotificationActivatedEventArgs const& args);

    private:
        winrt::Microsoft::UI::Xaml::Window window{ nullptr };
        void HandleNotification(winrt::Microsoft::Windows::AppNotifications::AppNotificationActivatedEventArgs const& args);
    };
}

Atualize App.xaml.cpp com o fluxo de ativação. Adicione #include <winrt/Microsoft.Windows.AppLifecycle.h> ao pch.h.

// App.xaml.cpp
#include "pch.h"
#include "App.xaml.h"
#include "MainWindow.xaml.h"

using namespace winrt;
using namespace Microsoft::UI::Xaml;
using namespace Microsoft::Windows::AppNotifications;
using namespace Microsoft::Windows::AppLifecycle;

namespace winrt::AppNotificationsExample::implementation
{
    App::App()
    {
        // ...
    }

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make<MainWindow>();

        AppNotificationManager::Default().NotificationInvoked({ this, &App::OnNotificationInvoked });
        AppNotificationManager::Default().Register();

        auto activatedArgs = AppInstance::GetCurrent().GetActivatedEventArgs();

        if (activatedArgs.Kind() == ExtendedActivationKind::AppNotification)
        {
            // App was launched by clicking a notification
            auto notificationArgs = activatedArgs.Data().as<AppNotificationActivatedEventArgs>();
            HandleNotification(notificationArgs);
        }
        else
        {
            // Normal launch
            window.Activate();
        }
    }

    void App::OnNotificationInvoked(AppNotificationManager const&, AppNotificationActivatedEventArgs const& args)
    {
        // Notification clicked while app is already running
        HandleNotification(args);
    }

    void App::HandleNotification(AppNotificationActivatedEventArgs const& args)
    {
        auto userInput = args.Arguments();
        auto action = userInput.HasKey(L"action") ? userInput.Lookup(L"action") : L"(none)";
        auto exampleEventId = userInput.HasKey(L"exampleEventId") ? userInput.Lookup(L"exampleEventId") : L"(none)";

        window.DispatcherQueue().TryEnqueue([this, action, exampleEventId]()
        {
            if (action == L"BackgroundAction")
            {
                // Handle the action without showing the app window.
                // If the window was never shown, exit the app.
                if (!window.Visible())
                {
                    Application::Current().Exit();
                }
            }
            else
            {
                // Bring the app to the foreground and display the notification arguments.
                window.Activate();
                window.as<MainWindow>()->UpdateNotificationUI(action, exampleEventId);
            }
        });
    }
}

Adicione um método UpdateNotificationUI ao MainWindow para exibir os argumentos de notificação nas caixas de texto adicionadas anteriormente.

C#

// MainWindow.xaml.cs
public void UpdateNotificationUI(string action, string exampleEventId)
{
    DispatcherQueue.TryEnqueue(() =>
    {
        ActionTextBox.Text = action;
        ExampleEventIdTextBox.Text = exampleEventId;
    });
}

C++

Adicione a declaração a MainWindow.xaml.h:

// MainWindow.xaml.h
void UpdateNotificationUI(winrt::hstring const& action, winrt::hstring const& exampleEventId);

Implemente o método em MainWindow.xaml.cpp:

// MainWindow.xaml.cpp
void MainWindow::UpdateNotificationUI(winrt::hstring const& action, winrt::hstring const& exampleEventId)
{
    DispatcherQueue().TryEnqueue([this, action, exampleEventId]()
    {
        ActionTextBox().Text(action);
        ExampleEventIdTextBox().Text(exampleEventId);
    });
}

Próximas Etapas 

• Conteúdo de notificação do aplicativo – saiba como adicionar imagens, botões, entradas e outros elementos de interface do usuário às suas notificações.
• Remover notificações do aplicativo — saiba como marcar, remover e definir a expiração em suas notificações.

Consulte também

• Visão geral das notificações do aplicativo
• Barra de progresso da notificação do aplicativo
• exemplo de código de notificações no GitHub
• Microsoft.Windows. Referência da API appNotifications
• Esquema XML de notificações