Průvodce rychlým spuštěním: Použití notifikací aplikací s Windows App SDK

V tomto rychlém startu vytvoříte aplikaci WinUI, která pomocí Windows App SDK odesílá oznámení místních aplikací a reaguje na ně.

Kompletní ukázkové aplikace, které implementují oznámení aplikací, najdete v úložišti Windows App SDK Samples v GitHub.

Important

U aplikací se zvýšenými oprávněními (správce) se nepodporují oznámení aplikací.

Prerequisites

• Instalace Visual Studio 2022 (v17.6+)
  • Stažení 2022 Community
  • Download 2022 Professional
  • Download 2022 Enterprise
• Zahrňte zátěž C++ pro vývoj v jazyce C++ nebo zátěž .NET pro vývoj v jazyce C#.
• Ujistěte se, že jsou vybrané nástroje MSIX Packaging Tools v části .NET vývoj desktopů.
• Ujistěte se, že je vybrán vývoj aplikací pro Windows.
• Ujistěte se, že je vybrána možnost Vývoj aplikace uživatelského rozhraní pro Windows.

Další informace o správě úloh ve Visual Studio najdete v tématu Modify Visual Studio workloads, components, and language packs. Další informace o tom, jak začít s WinUI, najdete v tématu Začínáme s WinUI. Pokud chcete přidat Windows App SDK do existujícího projektu, přečtěte si téma Použití Windows App SDK v existujícím projektu.

Vytvoření nového projektu aplikace WinUI v Visual Studio

1. V Visual Studio vytvořte nový projekt.
2. V dialogovém okně Vytvořit nový projekt nastavte filtr jazyka na C# nebo C++ a filtr platformy na WinUI a pak vyberte šablonu projektu Prázdná aplikace, zabalená (WinUI 3 v desktopové verzi).
3. Pojmenujte nový projekt AppNotificationsExample.

Odeslání oznámení místní aplikace

V této části přidáte do aplikace tlačítko, které po kliknutí odešle oznámení místní aplikace. Oznámení bude obsahovat textový obsah a obrázek loga aplikace. Přidáte také dvě textová pole jen pro čtení, která zobrazí aktivační argumenty, když uživatel klikne na oznámení.

Nejprve přidejte ovládací prvek Button a dva ovládací prvky TextBox do složky 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)"/>

Rozhraní API pro oznámení aplikace jsou v Microsoft.Windows.AppNotifications a Microsoft.Windows.AppNotifications.Builder obory názvů. Do projektu přidejte následující odkazy:

C#

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

C++

Do souboru předkompilované hlavičky přidejte následující direktivy include (pch.h):

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

Nyní do obslužné rutiny kliknutí na tlačítko přidejte následující kód. Tento příklad používá AppNotificationBuilder k vytvoření obsahu oznámení, včetně argumentů, které budou předány zpět do aplikace, když uživatel klikne na oznámení, obrázek loga aplikace a text. Oznámení obsahuje také tlačítko, které předvádí provedení akce bez spuštění uživatelského rozhraní aplikace. Metoda BuildNotification vytvoří Objekt AppNotification a AppNotificationManager.Show jej zobrazí uživateli.

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

V tuto chvíli můžete sestavit a spustit aplikaci. Kliknutím na tlačítko Odeslat oznámení aplikace zobrazíte oznámení. Všimněte si, že kliknutí na oznámení ještě neprovede žádnou akci – v další části se dozvíte, jak zpracovat aktivaci aplikace, aby aplikace reagovala, když uživatel klikne na oznámení.

Note

Oznámení aplikací se nepodporují, když je vaše aplikace spuštěná s oprávněními správce (se zvýšenými oprávněními). Zobrazení selže bezobslužně a nezobrazí se žádné oznámení. Při testování oznámení se ujistěte, že aplikaci spouštíte bez zvýšení oprávnění.

Aktualizace souboru manifestu balíčku aplikace

Soubor Package.appmanifest obsahuje podrobnosti o balíčku MSIX pro aplikaci. Pokud chcete aplikaci spustit, když uživatel komunikuje s oznámením aplikace, musíte aktualizovat soubor manifestu balíčku aplikace tak, aby byla aplikace zaregistrovaná v systému jako cíl aktivace oznámení aplikace. Další informace o manifestech balíčků aplikací najdete v tématu Manifest balíčku aplikace.

1. Upravte soubor Package.appxmanifest tak, že kliknete pravým tlačítkem na soubor v Průzkumník řešení a vyberete View Code.
2. Přidat xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" a xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" obory názvů do <Package>.
3. <desktop:Extension> Přidejte prvek pod <Extensions>. Nastavte atribut Category na "windows.toastNotificationActivation", abyste deklarovali, že aplikace může být aktivována oznámeními aplikace.
   • Přidejte podřízený prvek <desktop:ToastNotificationActivation> a nastavte ToastActivatorCLSID na identifikátor GUID, který jednoznačně identifikuje vaši aplikaci.
   • Identifikátor GUID v Visual Studio můžete vygenerovat tak, že přejdete na Tools > Vytvořit identifikátor GUID.
4. <com:Extension> Přidejte prvek pod <Extensions> a nastavte Category atribut na "windows.comServer". Příklad souboru manifestu uvedeného níže ukazuje syntaxi tohoto prvku.
   • Aktualizujte atribut Executable elementu <com:ExeServer> názvem vašeho spustitelného souboru. V tomto příkladu bude název "AppNotificationsExample.exe".
   • Zadejte Arguments="----AppNotificationActivated:", abyste zajistili, že Windows App SDK může zpracovat obsah vašeho oznámení jako typ AppNotification.
   • Nastavte atribut prvku <com:Class> na stejný identifikátor GUID, který jste použili pro atribut 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>

Zpracování aktivace z notifikace aplikace

Když uživatel klikne na oznámení aplikace nebo na tlačítko v oznámení, musí vaše aplikace správně reagovat. Existují dva běžné scénáře aktivace:

1. Spustit s uživatelským rozhraním – Uživatel klikne na text oznámení a vaše aplikace by se měla spustit nebo se dostat do popředí a zobrazit relevantní obsah.
2. Akce na pozadí – Uživatel klikne na tlačítko v oznámení, které aktivuje akci (například odeslání odpovědi), aniž by se zobrazilo uživatelské rozhraní aplikace.

Aby bylo možné podporovat oba scénáře, měl by tok aktivace vaší aplikace vytvořit hlavní okno, OnLaunched ale ne aktivovat ho okamžitě. Místo toho zaregistrujte událost AppNotificationManager.NotificationInvoked , zavolejte AppNotificationManager.Register a pak zkontrolujte AppInstance.GetActivatedEventArgs , abyste zjistili, jestli byla aplikace spuštěna z oznámení nebo z normálního spuštění. Pokud se spuštění aktivovalo oznámením, může váš kód zkontrolovat argumenty oznámení a rozhodnout se, jestli se má zobrazit okno nebo zpracovat akci bezobslužně a ukončit.

Událost NotificationInvoked zpracovává kliknutí, ke kterým dochází, když je aplikace už spuštěná. Pokud aplikace není spuštěná, Windows aplikaci spustí prostřednictvím aktivace modelu COM a typ aktivace se ohlásí jako Launch, nikoli AppNotification. Argumenty oznámení se pak doručí prostřednictvím NotificationInvoked události.

Important

Před voláním AppInstance.GetActivatedEventArgs musíte volat AppNotificationManager.Register.

Important

Nastavení activationType="background" v datové části XML oznámení se pro desktopové aplikace ignoruje. Musíte zpracovat aktivační argumenty v kódu a rozhodnout, jestli se má zobrazit okno, nebo ne.

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

Přidejte deklaraci HandleNotification do třídy App v 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);
    };
}

Aktualizujte App.xaml.cpp tok aktivace. Do #include <winrt/Microsoft.Windows.AppLifecycle.h> přidejte 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);
            }
        });
    }
}

Přidejte metodu UpdateNotificationUI do MainWindow pro zobrazení argumentů oznámení v textových polích přidaných dříve.

C#

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

C++

Přidejte deklaraci do MainWindow.xaml.h:

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

Implementujte metodu v 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);
    });
}

Další kroky

• Obsah oznámení aplikace – naučte se do oznámení přidávat obrázky, tlačítka, vstupy a další prvky uživatelského rozhraní.
• Odebrání oznámení aplikace – zjistěte, jak u oznámení označit, odebrat a nastavit vypršení platnosti.

Viz také

• Přehled oznámení aplikací
• Indikátor průběhu oznámení aplikace
• ukázka kódu Notifications na GitHub
• Microsoft.Windows. Referenční informace k rozhraní API AppNotifications
• XML schéma oznámení