Поделиться через


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

Уведомление о приложении — это сообщение о том, что приложение может создавать и доставлять пользователю, пока они не находятся в вашем приложении.

Снимок экрана: уведомление о приложении

В этом кратком руководстве описаны шаги по созданию, доставке и отображению уведомления приложения Windows 10 или Windows 11 с использованием богатого контента и интерактивных действий. В этой краткой инструкции используются локальные уведомления, которые являются наиболее простыми для реализации. Все типы приложений (WPF, UWP, WinForms, консоль) могут отправлять уведомления!

Note

Термин "тост-уведомление" заменяется на "уведомление приложения". Эти термины относятся к одной и той же функции Windows, но со временем мы будем постепенно отказываться от использования термина «всплывающее уведомление» в документации.

Important

Если вы пишете приложение на C++, ознакомьтесь с документацией по C++ UWP или C++ WRL.

Шаг 1. Установка пакета NuGet

В решении Visual Studio щелкните проект правой кнопкой мыши, щелкните "Управление пакетами NuGet..." и найдите и установите Microsoft.Toolkit.Uwp.Notificationsпакет NuGet версии 7.0 или выше.

Important

Классические приложения .NET Framework, которые по-прежнему используют packages.config должны перенестися в PackageReference, в противном случае пакеты SDK для Windows не будут ссылаться правильно. В проекте щелкните правой кнопкой мыши ссылку "Ссылки" и выберите "Перенести пакеты.config в PackageReference".

Приложения WPF .NET Core 3.0 должны обновляться до .NET Core 3.1, в противном случае API будут отсутствуют.

Приложения .NET должны использовать одну из целевых платформ Windows, в противном случае API для отправки и управления уведомлениями в приложениях, как Show(), будут недоступны. Задайте для TFM значение net6.0-windows10.0.17763.0 или позже.

В нашем примере кода будет использоваться этот пакет. Этот пакет позволяет создавать уведомления приложений без использования XML, а также позволяет настольным приложениям отправлять уведомления приложений.

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

В Windows 10 и Windows 11 содержимое уведомления о приложении описывается с помощью адаптивного языка, который обеспечивает большую гибкость при просмотре уведомлений. Дополнительные сведения см. в документации по содержимому уведомлений о приложении .

Начнем с простого текстового уведомления. Создайте содержимое уведомления (с помощью библиотеки уведомлений) и покажите уведомление! Обратите внимание, что пространство имен Microsoft.Toolkit.Uwp.Notifications.

Простое текстовое уведомление
// 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

Попробуйте запустить этот код, и появится уведомление!

Шаг 3: Выполнение активации

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

Шаги по обработке активации отличаются для UWP и для упакованных и распакованных настольных приложений.

Сначала в Package.appxmanifestдобавьте:

  1. Объявление для xmlns:com
  2. Декларация для xmlns:desktop
  3. В атрибуте IgnorableNamespaces, com и desktop
  4. desktop:Extension для windows.toastNotificationActivation, чтобы объявить идентификатор CLSID активатора уведомлений (с использованием нового GUID по вашему выбору).
  5. Только для MSIX: com:Extension для COM-активатора с использованием GUID из шага №4. Обязательно включите Arguments="-ToastActivated", чтобы вы знали, что ваш запуск произошёл из уведомления.

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>

Затем в коде инициализации вашего приложения (App.xaml.cs OnStartup для WPF) подпишитесь на событие 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);
    });
};

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

Если ваше приложение в настоящее время работает...

  1. Событие ToastNotificationManagerCompat.OnActivated будет вызываться в фоновом потоке.

Если ваше приложение в настоящее время закрыто...

  1. EXE приложения будет запущен и ToastNotificationManagerCompat.WasCurrentProcessToastActivated() вернет значение true, чтобы указать, что процесс был запущен из-за современной активации и что обработчик событий скоро будет вызван.
  2. Затем событие ToastNotificationManagerCompat.OnActivated будет вызвано в фоновом потоке.

Шаг 4: Обработка деинсталляции

Вам ничего не нужно делать! При удалении приложений MSIX все уведомления и любые другие связанные ресурсы автоматически очищаются.

Add images

Вы можете добавить богатый контент в уведомления. Мы добавим встроенное изображение и изображение профиля (замена логотипа приложения).

Note

Изображения можно использовать из пакета приложения, локального хранилища приложения или из Интернета. Начиная с Fall Creators Update, изображения в Интернете могут составлять до 3 МБ при обычных подключениях и 1 МБ при лимитных подключениях. На устройствах, ещё не работающих под управлением Fall Creators Update, веб-изображения не должны превышать 200 КБ.

Important

Поддержка HTTP-изображений осуществляется только в упакованных приложениях, имеющих доступ к Интернету в их манифесте. Неупакованные приложения не поддерживают http-образы; Необходимо скачать образ в данные локального приложения и ссылаться на него локально.

Тост с изображениями
// 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();

Добавление кнопок и входных данных

Вы можете добавить кнопки и входные данные, чтобы сделать уведомления интерактивными. Кнопки могут запускать приложение переднего плана, протокол или фоновую задачу. Мы добавим текстовое поле ответа, кнопку "Нравится" и кнопку "Вид", которая открывает изображение.

Снимок экрана уведомления приложения с вводами и кнопками
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();

Активация кнопок переднего плана обрабатывается так же, как основной текст уведомления (будет вызываться App.xaml.cs OnActivated).

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

Обработка фоновой активации

Для настольных приложений фоновые активации обрабатываются так же, как активации переднего плана (ваш обработчик событий OnActivated будет вызван). Вы можете не отображать пользовательский интерфейс и закрыть приложение после обработки активации.

Установка срока действия

В Windows 10 все уведомления приложений отправляются в Центр действий после того, как они удалены или игнорируются пользователем, чтобы пользователи могли просматривать уведомления после исчезновения всплывающего окна.

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

Note

Срок действия по умолчанию и максимальный срок действия для уведомлений локального приложения составляет 3 дня.

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

Укажите первичный ключ для уведомления

Если вы хотите программно удалить или заменить отправленное уведомление, необходимо использовать свойство Tag (и необязательно свойство Group), чтобы предоставить первичный ключ для уведомления. Затем вы можете использовать этот первичный ключ в будущем для удаления или замены уведомления.

См. краткое руководство: Управление всплывающими уведомлениями в центре уведомлений (XAML) для получения дополнительных сведений о замене и удалении уже отправленных уведомлений приложений.

Тег и группа объединяются в качестве составного первичного ключа. Группа — это более универсальный идентификатор, где можно назначать такие группы, как wallPosts, "messages", "friendRequests" и т. д. А затем тег должен однозначно идентифицировать уведомление из группы. С помощью универсальной группы можно удалить все уведомления из этой группы с помощью 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";
    });

Очистка уведомлений

Приложения отвечают за удаление и очистку собственных уведомлений. При запуске приложения мы не очищаем уведомления автоматически.

Windows автоматически удаляет уведомление, если пользователь явно щелкает уведомление.

Ниже приведен пример того, что должно сделать приложение для обмена сообщениями...

  1. Пользователь получает несколько уведомлений о новых сообщениях в переписке.
  2. Пользователь нажимает одно из этих уведомлений, чтобы открыть беседу.
  3. Приложение открывает беседу, а затем очищает все уведомления для этой беседы (с помощью RemoveGroup в группе, предоставленной приложением для этой беседы).
  4. Центр уведомлений пользователя теперь корректно отображает состояние уведомлений, поскольку в нем больше нет неактуальных сообщений для этого разговора.

Чтобы узнать об очистке всех уведомлений или удалении определенных уведомлений, см. Краткое руководство по управлению уведомлениями в центре уведомлений(XAML).

ToastNotificationManagerCompat.History.Clear();

Resources