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

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

  • Статья

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

Снимок экрана: всплывающее уведомление

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

Внимание

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

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

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

Внимание

платформа .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, а также для упакованных и распакованных классических приложений.

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

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

Внимание

Необходимо инициализировать кадр и активировать окно так же, как код OnLaunched . OnLaunched не вызывается, если пользователь щелкает всплывающее уведомление, даже если приложение было закрыто и запускается в первый раз. Мы часто рекомендуем объединить OnLaunched и OnActivated в собственный OnLaunchedOrActivated метод, так как в обоих ситуациях необходимо выполнить одну и ту же инициализацию.

Шаг 4. Обработка удаления

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

Добавление изображений

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

Примечание.

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

Внимание

Образы 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, как показано выше (если вы настраиваете аргументы на кнопке, аргументы верхнего уровня не будут включены).

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

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

Дополнительные сведения о фоновых задачах см. в статье "Поддержка приложения с фоновыми задачами".

Если вы используете сборку 14393 или более поздней версии, можно использовать фоновые задачи в процессе, что значительно упрощает работу. Обратите внимание, что фоновые задачи в процессе не будут выполняться в более ранних версиях Windows. В этом примере кода мы будем использовать фоновую задачу внутри процесса.

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

Затем в App.xaml.cs переопределите метод OnBackgroundActivated. Затем можно получить предварительно определенные аргументы и входные данные пользователя, аналогичные активации переднего плана.

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

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

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

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

Примечание.

По умолчанию и максимальное время окончания срока действия для локальных всплывающих уведомлений составляет 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();

Ресурсы