Краткое руководство: Использование уведомлений приложений с Windows App SDK

В этом кратком руководстве вы создадите приложение WinUI, которое отправляет и отвечает на уведомления локального приложения с помощью Windows App SDK.

Полные примеры приложений, реализующих уведомления о приложениях, см. в репозитории Windows App SDK Samples в GitHub.

Important

Уведомления приложений не поддерживаются для приложений с повышенными привилегиями (администратором).

Prerequisites

• Установка Visual Studio 2022 (версия 17.6+)
  • Download 2022 Community
  • Скачать Professional 2022
  • Download 2022 Enterprise
• Включите рабочую нагрузку C++ для разработки на C++ или .NET для разработки на C#.
• Убедитесь, что средства упаковки MSIX выбраны в разделе .NET разработки настольных приложений.
• Убедитесь, что выбрана разработка приложений для Windows.
• Убедитесь, что выбрана разработка приложений пользовательского интерфейса Windows.

Дополнительные сведения об управлении рабочими нагрузками в Visual Studio см. в разделе Изменить рабочие нагрузки Visual Studio, компоненты и языковые пакеты. Дополнительные сведения о начале работы с WinUI см. в статье "Начало работы с WinUI". Чтобы добавить Windows App SDK в существующий проект, см. раздел Использовать Windows App SDK в существующем проекте.

Создание проекта приложения WinUI в Visual Studio

1. В Visual Studio создайте проект.
2. В диалоговом окне "Создание проекта " задайте для фильтра языка значение "C#" или "C++", а фильтр платформы — "WinUI", а затем выберите шаблон проекта "Пустое приложение, упакованое (WinUI 3 в desktop)".
3. Назовите новый проект AppNotificationsExample.

Отправка уведомления локального приложения

В этом разделе вы добавите кнопку в приложение, которое отправляет уведомление локального приложения при нажатии кнопки. Уведомление будет содержать текстовое содержимое и изображение логотипа приложения. Вы также добавите два текстовых поля только для чтения, которые будут отображать аргументы активации, когда пользователь щелкает уведомление.

Сначала добавьте элемент управления Button и два элемента управления TextBox: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)"/>

API-интерфейсы уведомлений приложения находятся в Майкрософт.Windows. AppNotifications и Майкрософт.Windows. AppNotifications.Builder пространства имен. Добавьте в проект следующие ссылки:

C#

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

C++

Добавьте следующие директивы включения в предварительно скомпилированный заголовочный файл (pch.h):

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

Теперь добавьте следующий код в обработчик нажатия кнопки. В этом примере используется AppNotificationBuilder для создания содержимого уведомлений, включая аргументы, которые будут переданы в приложение, когда пользователь щелкает уведомление, изображение логотипа приложения и текст. Уведомление также включает кнопку, демонстрирующую выполнение действия без запуска пользовательского интерфейса приложения. Метод BuildNotification создает объект AppNotification, а AppNotificationManager.Show отображает его пользователю.

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);
}

На этом этапе вы можете создать и запустить приложение. Нажмите кнопку "Отправить уведомление приложения ", чтобы отобразить уведомление. Обратите внимание, что нажатие на уведомление еще не вызовет никаких действий — в следующем разделе вы узнаете, как обрабатывать активацию приложения, чтобы ваше приложение могло реагировать, когда пользователь нажимает на уведомление.

Note

Уведомления о приложениях не поддерживаются при запуске приложения с правами администратора (повышенными привилегиями). Отображение завершится без каких-либо сообщений об ошибке и уведомление не будет отображаться. Убедитесь, что приложение запущено без повышения прав при тестировании уведомлений.

Обновление файла манифеста пакета приложения

Файл Package.appmanifest содержит сведения о пакете MSIX для приложения. Чтобы разрешить запуск приложения при взаимодействии пользователя с уведомлением о приложении, необходимо обновить файл манифеста пакета приложения, чтобы приложение зарегистрировано в системе в качестве целевого объекта для активации уведомления приложения. Дополнительные сведения о манифестах пакета приложения см. в разделе "Манифест пакета приложения".

1. Измените файл Package.appxmanifest, щелкнув правой кнопкой мыши файл в Обозреватель решений и выбрав View Code.
2. Добавьте пространства имен xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" и xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" в <Package>.
3. Добавьте элемент <desktop:Extension> под <Extensions>. Установите атрибут Category в "windows.toastNotificationActivation", чтобы объявить, что ваше приложение может быть активировано уведомлениями приложения.
   • Добавьте дочерний <desktop:ToastNotificationActivation> элемент и задайте ToastActivatorCLSID идентификатор GUID, который будет однозначно идентифицировать приложение.
   • Вы можете создать GUID в Visual Studio, перейдя к Tools > Create GUID.
4. Добавьте элемент <com:Extension> под <Extensions> и задайте атрибуту Category значение "windows.comServer". В примере файла манифеста ниже показан синтаксис этого элемента.
   • Обновите атрибут Executable элемента <com:ExeServer> на имя вашего исполняемого файла. В этом примере имя будет "AppNotificationsExample.exe".
   • Укажите Arguments="----AppNotificationActivated:", чтобы убедиться, что Windows App SDK может обрабатывать содержимое уведомления как тип AppNotification.
   • Id Присвойте атрибуту <com:Class> элемента тот же GUID, который использовался для атрибутаToastActivatorCLSID.

<!--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>

Обработка активации из уведомления приложения

Когда пользователь щелкает уведомление приложения или кнопку в уведомлении, приложение должно реагировать соответствующим образом. Существует два распространенных сценария активации:

1. Запуск с помощью пользовательского интерфейса — пользователь щелкает текст уведомления, и приложение должно запустить или перейти на передний план, отображая соответствующее содержимое.
2. Фоновое действие — пользователь нажимает кнопку в уведомлении, которое активирует действие (например, отправка ответа) без отображения пользовательского интерфейса приложения.

Для поддержки обоих сценариев процесс активации приложения должен создать главное окно, OnLaunched но не активировать его немедленно. Вместо этого зарегистрируйте событие AppNotificationManager.NotificationInvoked , вызовите AppNotificationManager.Register, а затем проверьте AppInstance.GetActivatedEventArgs , чтобы определить, было ли приложение запущено из уведомления или с обычного запуска. Если запуск был активирован уведомлением, код может проверить аргументы уведомлений и решить, следует ли отображать окно или обрабатывать действие автоматически и выйти.

Событие NotificationInvoked обрабатывает щелчки, которые происходят, пока приложение уже запущено. Если приложение не запущено, Windows запускает приложение с помощью com-активации и тип активации сообщается как Launch, а не AppNotification. Затем аргументы уведомления доставляются через NotificationInvoked событие.

Important

Перед вызовом AppInstance.GetActivatedEventArgs необходимо вызвать AppNotificationManager.Register.

Important

Параметр activationType="background" в полезных данных XML уведомления игнорируется для настольных приложений. Необходимо обработать аргументы активации в коде и решить, следует ли отображать окно или нет.

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++

Добавьте декларацию HandleNotification в класс App в 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);
    };
}

Обновите App.xaml.cpp поток активации. Добавьте #include <winrt/Майкрософт.Windows.AppLifecycle.h> в 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);
            }
        });
    }
}

Добавьте метод UpdateNotificationUI в MainWindow для отображения аргументов уведомления в ранее добавленных текстовых полях.

C#

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

C++

Добавьте объявление в MainWindow.xaml.h:

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

Реализация метода в 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);
    });
}

Дальнейшие действия

• Содержимое уведомления приложения — узнайте, как добавлять изображения, кнопки, входные данные и другие элементы пользовательского интерфейса в уведомления.
• Удаление уведомлений приложения — узнайте, как тегировать, удалять и устанавливать срок действия уведомлений.

См. также

• Общие сведения о уведомлениях приложений
• Индикатор хода выполнения уведомления приложения
• пример кода Notifications в GitHub
• Майкрософт.Windows.AppNotifications Справочник по API
• XML-схема уведомлений