Schnellstart: App-Benachrichtigungen im Windows App SDK

In dieser Schnellstartanleitung erstellen Sie eine Windows-Desktopanwendung, die mithilfe des Windows App SDK lokale App-Benachrichtigungen, auch als Popupbenachrichtigungen bezeichnet, sendet und empfängt.

Wichtig

Benachrichtigungen für eine App mit erhöhten Rechten (Administrator) werden derzeit nicht unterstützt.

Voraussetzungen

• Erste Schritte mit WinUI
• Erstellen Sie entweder ein neues Projekt, welches das Windows App SDK verwendet oder verwenden Sie das Windows App SDK in einem vorhandenen Projekt

Beispiel-App

Diese Schnellstartanleitung behandelt Code aus den Benachrichtigungsbeispiel-Apps, die auf GitHubgefunden wurden.

Beispiel-App-Code

API-Referenz

API-Referenzdokumentation für App-Benachrichtigungen finden Sie unter Microsoft.Windows.AppNotifications Namespace.

Schritt 1: Hinzufügen von Namespacedeklarationen

Fügen Sie den Namespace für Windows App SDK-App-Benachrichtigungen Microsoft.Windows.AppNotifications hinzu.

using Microsoft.Windows.AppNotifications;

Schritt 2: Aktualisieren des App-Manifests

Wenn Ihre App entpackt ist (d. h., es fehlt die Paketidentität zur Laufzeit), fahren Sie mit Schritt 3: Registrieren, um eine App-Benachrichtigung zu behandeln, fort.

Wenn Ihre App verpackt ist (inklusive mit externem Speicherort paketiert):

1. Öffnen Sie Ihr Package.appxmanifest.
2. Fügen Sie die Namespaces xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" und xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" zu <Package> hinzu
3. Fügen Sie <desktop:Extension> für windows.toastNotificationActivation hinzu, um Ihren COM-Aktivator CLSID zu deklarieren. Sie können eine CLSID abrufen, indem Sie unter Tools in Visual Studio zu GUID erstellen navigieren.
4. Fügen Sie <com:Extension> für den COM-Aktivator mit derselben CLSID hinzu.
   1. Geben Sie Ihre EXE-Datei im Executable Attribut an. Die EXE-Datei muss beim Registrieren Ihrer App für Benachrichtigungen derselbe Prozess Register() sein, der in Schritt 3 beschrieben wird. Im folgenden Beispiel verwenden wir Executable="SampleApp\SampleApp.exe".
   2. Geben Sie Arguments="----AppNotificationActivated:" an, damit das Windows App SDK die Nutzlast Ihrer Benachrichtigung als AppNotification-Art verarbeiten kann.
   3. Geben Sie einen DisplayName an.

Wichtig

Warnung: Wenn Sie einen Erweiterungstyp für Windows.Protocol-Apps in Ihrem Appx-Manifest mit <uap:Protocol> definieren, werden durch Klicken auf Benachrichtigungen neue Prozesse derselben App gestartet, auch wenn Ihre App bereits ausgeführt wird.

<!--Packaged apps only-->
<!--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\SampleApp.exe" DisplayName="SampleApp" Arguments="----AppNotificationActivated:">
              <com:Class Id="replaced-with-your-guid-C173E6ADF0C3" />
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>
    
      </Extensions>
    </Application>
  </Applications>
 </Package>

Schritt 3: Registrieren für die Behandlung einer App-Benachrichtigung

Registrieren Sie Ihre App zum Behandeln von Benachrichtigungen und heben Sie die Registrierung auf, wenn Ihre App beendet wird.

Registrieren Sie sich in Ihrer App.xaml-Datei für AppNotificationManager::Default().NotificationInvoked, dann rufen Sie dann AppNotificationManager::Default().Register auf. Die Reihenfolge dieser Aufrufe ist wichtig.

Wichtig

Sie müssen AppNotificationManager::Default().Register aufrufen, bevor Sie AppInstance.GetCurrent.GetActivatedEventArgs aufrufen.

Rufen Sie beim Beenden Ihrer App AppNotificationManager::Default().Unregister() auf, um den COM-Server freizugeben und nachfolgende Aufrufe zum Starten neuer Prozesse zuzulassen.

C#

// App.xaml.cs
namespace CsUnpackagedAppNotifications
{

    public partial class App : Application
    {
        private Window mainWindow;
        private NotificationManager notificationManager;
        
        public App()
        {
            this.InitializeComponent();
            notificationManager = new NotificationManager();
            AppDomain.CurrentDomain.ProcessExit += new EventHandler(OnProcessExit);
        }

        protected override void OnLaunched(LaunchActivatedEventArgs args)
        {
            mainWindow = new MainWindow();

            notificationManager.Init();
            
            // Complete in Step 5
            
            mainWindow.Activate();
        }

        void OnProcessExit(object sender, EventArgs e)
        {
            notificationManager.Unregister();
        }
    }
}


// NotificationManager.cs
namespace CsUnpackagedAppNotifications
{
    internal class NotificationManager
    {
        private bool m_isRegistered;

        private Dictionary<int, Action<AppNotificationActivatedEventArgs>> c_map;

        public NotificationManager()
        {
            m_isRegistered = false;

            // When adding new a scenario, be sure to add its notification handler here.
            c_map = new Dictionary<int, Action<AppNotificationActivatedEventArgs>>();
            c_map.Add(ToastWithAvatar.ScenarioId, ToastWithAvatar.NotificationReceived);
            c_map.Add(ToastWithTextBox.ScenarioId, ToastWithTextBox.NotificationReceived);
        }

        ~NotificationManager()
        {
            Unregister();
        }

        public void Init()
        {
            // To ensure all Notification handling happens in this process instance, register for
            // NotificationInvoked before calling Register(). Without this a new process will
            // be launched to handle the notification.
            AppNotificationManager notificationManager = AppNotificationManager.Default;

            notificationManager.NotificationInvoked += OnNotificationInvoked;

            notificationManager.Register();
            m_isRegistered = true;
        }

        public void Unregister()
        {
            if (m_isRegistered)
            {
                AppNotificationManager.Default.Unregister();
                m_isRegistered = false;
            }
        }

        public void ProcessLaunchActivationArgs(AppNotificationActivatedEventArgs notificationActivatedEventArgs)
        {
            // Complete in Step 5
        }

    }
}       

C++

// App.xaml.cpp

// NotificationManager is responsible for registering and unregistering the Sample for App Notifications as well as
// dispatching actioned notifications to the appropriate scenario.
// Registration will happen when Init() is called and Unregistration will happen when this
// instance variable goes out of scope, i.e.: when the App is terminated.
static NotificationManager g_notificationManager;

namespace winrt::CppUnpackagedAppNotifications::implementation
{
    App::App()
    {
        InitializeComponent();
    }

    std::wstring App::GetFullPathToExe()
    {
        TCHAR buffer[MAX_PATH] = { 0 };
        GetModuleFileName(NULL, buffer, MAX_PATH);
        std::wstring::size_type pos = std::wstring(buffer).find_last_of(L"\\/");
        return std::wstring(buffer).substr(0, pos);
    }

    std::wstring App::GetFullPathToAsset(std::wstring const& assetName)
    {
        return GetFullPathToExe() + L"\\Assets\\" + assetName;
    }

    void App::OnLaunched(winrt::Microsoft::UI::Xaml::LaunchActivatedEventArgs const& /*args*/)
    {
        window = make<MainWindow>();

        g_notificationManager.Init();

        // Complete in Step 5
        
        window.Activate();
    }
}

// NotificationManager.cpp
static const std::map<unsigned, std::function<void (winrt::AppNotificationActivatedEventArgs const&)>> c_map
{
    // When adding new a scenario, be sure to add its notification handler here.
    { ToastWithAvatar::ScenarioId, ToastWithAvatar::NotificationReceived },
    { ToastWithTextBox::ScenarioId, ToastWithTextBox::NotificationReceived }
};

NotificationManager::NotificationManager():m_isRegistered(false){}

NotificationManager::~NotificationManager()
{
    if (m_isRegistered)
    {
        winrt::AppNotificationManager::Default().Unregister();
    }
}

void NotificationManager::Init()
{
    auto notificationManager{ winrt::AppNotificationManager::Default() };

    // Always setup the notification hanlder before registering your App, otherwise notifications may get lost.
    const auto token{ notificationManager.NotificationInvoked([&](const auto&, winrt::AppNotificationActivatedEventArgs  const& notificationActivatedEventArgs)
        {
            NotifyUser::NotificationReceived();

            if (!DispatchNotification(notificationActivatedEventArgs))
            {
                NotifyUser::UnrecognizedToastOriginator();
            }
        }) };

    winrt::AppNotificationManager::Default().Register();
    m_isRegistered = true;
}

void NotificationManager::ProcessLaunchActivationArgs(winrt::AppNotificationActivatedEventArgs const& notificationActivatedEventArgs)
{
    // Complete in Step 5
}

Schritt 4: Anzeigen einer App-Benachrichtigung

Sie MÜSSEN Schritt 3: Registrieren, um eine App-Benachrichtigung zu behandeln, ausführen, bevor Sie fortfahren.

Jetzt zeigen Sie eine einfache App-Benachrichtigung mit einem appLogoOverride-Bild und einer Schaltfläche an.

Erstellen Sie Ihre App-Benachrichtigung mithilfe der AppNotificationBuilder-Klasse und rufen Sie dann Show auf. Weitere Informationen zum Erstellen der App-Benachrichtigung mithilfe von XML finden Sie in den Beispielen unter Popupinhalte und im XML-Benachrichtigungsschema.

Hinweis

Wenn Ihre App verpackt ist (inklusive mit externem Speicherort paketiert), wird das Symbol Ihrer App in der oberen linken Ecke der Benachrichtigung aus package.manifest bezogen. Wenn Ihre App entpackt wird, wird das Symbol zuerst durch einen Blick auf die Verknüpfung erstellt, und dann wird die Ressourcendatei im App-Prozess betrachtet. Wenn alle Versuche fehlschlagen, wird das Windows-Standard-App-Symbol verwendet. Die unterstützten Symboldateitypen sind .jpg, .png, .bmp und .ico.

C#

// ToastWithAvatar.cs
class ToastWithAvatar
{
    public const int ScenarioId = 1;
    public const string ScenarioName = "Local Toast with Avatar Image";

    public static bool SendToast()
    {
        var appNotification = new AppNotificationBuilder()
            .AddArgument("action", "ToastClick")
            .AddArgument(Common.scenarioTag, ScenarioId.ToString())
            .SetAppLogoOverride(new System.Uri("file://" + App.GetFullPathToAsset("Square150x150Logo.png")), AppNotificationImageCrop.Circle)
            .AddText(ScenarioName)
            .AddText("This is an example message using XML")
            .AddButton(new AppNotificationButton("Open App")
                .AddArgument("action", "OpenApp")
                .AddArgument(Common.scenarioTag, ScenarioId.ToString()))
            .BuildNotification();

        AppNotificationManager.Default.Show(appNotification);

        return appNotification.Id != 0; // return true (indicating success) if the toast was sent (if it has an Id)
    }

    public static void NotificationReceived(AppNotificationActivatedEventArgs notificationActivatedEventArgs)
    {
        // Complete in Step 5   
    }
}

// Call SendToast() to send a notification. 

C++

// ToastWithAvatar.cpp

bool ToastWithAvatar::SendToast()
{
    auto appNotification{ winrt::AppNotificationBuilder()
        .AddArgument(L"action", L"ToastClick")
        .AddArgument(Common::scenarioTag, std::to_wstring(ToastWithAvatar::ScenarioId))
        .SetAppLogoOverride(winrt::Windows::Foundation::Uri(L"file://" + winrt::App::GetFullPathToAsset(L"Square150x150Logo.png")), winrt::AppNotificationImageCrop::Circle)
        .AddText(ScenarioName)
        .AddText(L"This is an example message using XML")
        .AddButton(winrt::AppNotificationButton(L"Open App")
            .AddArgument(L"action", L"OpenApp")
            .AddArgument(Common::scenarioTag, std::to_wstring(ToastWithAvatar::ScenarioId)))
        .BuildNotification() };

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

    return appNotification.Id() != 0; // return true (indicating success) if the toast was sent (if it has an Id)
}

void ToastWithAvatar::NotificationReceived(winrt::Microsoft::Windows::AppNotifications::AppNotificationActivatedEventArgs const& notificationActivatedEventArgs)
{
    // Complete in Step 5 
}

// Call SendToast() to send a notification. 

Schritt 5: Verarbeiten eines Benutzers, der eine Benachrichtigung auswählt

Benutzer können den Text oder die Schaltfläche Ihrer Benachrichtigung auswählen. Ihre App muss den Aufruf als Reaktion darauf verarbeiten, dass ein Benutzer mit Ihrer Benachrichtigung interagiert.

Es gibt zwei gängige Möglichkeiten, dies zu verarbeiten:

1. Sie entscheiden, dass Ihre App in einem bestimmten UI-Kontext gestartet werden soll ODER
2. Sie entscheiden, dass Ihre App ein aktionsspezifisches Verhalten auswertet (z. B. ein Schaltflächendruck im Benachrichtigungstext), ohne eine Benutzeroberfläche zu rendern. Auch bekannt als Hintergrundaktion.

Im folgenden Codebeispiel, das nicht aus der Beispiel-App stammt, wird die Verarbeitung einer vom Benutzer generierten Aktion veranschaulicht. Fügen Sie einen launch-Wert (entspricht dem Benutzer, der auf den Benachrichtigungstext klickt), ein input-Element (Textfeld für schnelle Antwort) und eine Schaltfläche mit einem arguments-Wert (entspricht dem Benutzer, der auf die Schaltfläche klickt) zur XML-Nutzlast Ihrer Benachrichtigung hinzu. In Ihrem ProcessLaunchActivationArgs-Fall für jedes Argument.

Wichtig

Die Einstellung activationType="background" in der XML-Nutzlast der Benachrichtigung wird für Desktop-Apps ignoriert. Sie müssen stattdessen die Aktivierungsargumente verarbeiten und entscheiden, ob ein Fenster angezeigt werden soll, wie in diesem Schritt angegeben.

// Example of how to process a user either selecting the notification body or inputting a quick reply in the text box. 

// Notification XML payload
//<toast launch="action=openThread&amp;threadId=92187">
//  <visual>
//      <binding template="ToastGeneric">
//          <image placement="appLogoOverride" hint-crop="circle" src="C:\<fullpath>\Logo.png"/>
//          <text>Local Toast with Avatar and Text box</text>
//          <text>This is an example message using</text>
//      </binding>
//  </visual>
//  <actions>
//      <input id="replyBox" type="text" placeHolderContent="Reply" />
//      <action
//          content="Send"
//          hint-inputId="replyBox"
//          arguments="action=reply&amp;threadId=92187" />
//  </actions>
//</toast>

void ProcessLaunchActivationArgs(const winrt::AppNotificationActivatedEventArgs& notificationActivatedEventArgs)
{
    // If the user clicks on the notification body, your app needs to launch the chat thread window
    if (std::wstring(notificationActivatedEventArgs.Argument().c_str()).find(L"openThread") != std::wstring::npos)
    {
        GenerateChatThreadWindow();
    }
    else // If the user responds to a message by clicking a button in the notification, your app needs to reply back to the other user with no window launched
    if (std::wstring(notificationActivatedEventArgs.Argument().c_str()).find(L"reply") != std::wstring::npos)
    {
        auto input = notificationActivatedEventArgs.UserInput();
        auto replyBoxText = input.Lookup(L"replyBox");

        // Process the reply text
        SendReplyToUser(replyBoxText);
    }
}

Befolgen Sie die folgenden Richtlinien:

1. Wenn eine Benachrichtigung vom Benutzer ausgewählt wird und Ihre App nicht ausgeführt wird, wird erwartet, dass Ihre App gestartet wird und der Benutzer das Vordergrundfenster im Kontext der Benachrichtigung sehen kann.
2. Wenn eine Benachrichtigung vom Benutzer ausgewählt wird und Ihre App minimiert ist, wird erwartet, dass Ihre App in den Vordergrund verschoben wird und ein neues Fenster im Kontext der Benachrichtigung gerendert wird.
3. Wenn eine Hintergrundaktion für Benachrichtigungen vom Benutzer aufgerufen wird (z. B. reagiert der Benutzer auf eine Benachrichtigung, indem er in das Textfeld der Benachrichtigung eingibt und antwortet), verarbeitet Ihre App die Nutzlast, ohne ein Vordergrundfenster zu rendern.

Ein ausführlicheres Beispiel finden Sie im Beispiel-App-Code auf GitHub.

Schritt 6: Entfernen von Benachrichtigungen

Entfernen Sie Benachrichtigungen, wenn sie für den Benutzer nicht mehr relevant sind.

In diesem Beispiel hat der Benutzer alle Nachrichten aus einem Gruppenchat in Ihrer App gesehen, sodass Sie alle Benachrichtigungen aus dem Gruppenchat löschen. Anschließend schaltet der Benutzer einen Freund stumm, sodass Sie alle Benachrichtigungen des Freundes löschen. Sie haben die Eigenschaften Gruppe und Tag zuerst den Benachrichtigungen hinzugefügt, bevor sie angezeigt werden, um sie jetzt zu identifizieren.

void SendNotification(winrt::hstring const& payload, winrt::hstring const& friendId, winrt::hstring const& groupChatId)
{
    winrt::AppNotification notification(payload);

    // Setting Group Id here allows clearing notifications from a specific chat group later
    notification.Group(groupChatId);

    // Setting Tag Id here allows clearing notifications from a specific friend later
    notification.Tag(friendId);

    winrt::AppNotificationManager::Default().Show(notification);
}

winrt::Windows::Foundation::IAsyncAction RemoveAllNotificationsFromGroupChat(const std::wstring groupChatId)
{
    winrt::AppNotificationManager manager = winrt::AppNotificationManager::Default();
    co_await manager.RemoveByGroupAsync(groupChatId);    
}

winrt::Windows::Foundation::IAsyncAction RemoveAllNotificationsFromFriend(const std::wstring friendId)
{
    winrt::AppNotificationManager manager = winrt::AppNotificationManager::Default();
    co_await manager.RemoveByTagAsync(friendId);    
}

Zusätzliche Funktionen

Senden einer cloudbasierten App-Benachrichtigung

Um eine App-Benachrichtigung aus der Cloud zu senden, folgen Sie Senden einer cloudbasierten App-Benachrichtigung unter Schnellstart: Pushbenachrichtigungen im Windows App SDK.

Eine Ablaufuhrzeit festlegen

Legen Sie eine Ablaufzeit für Ihre App-Benachrichtigung mithilfe der Expiration-Eigenschaft fest, wenn die Nachricht in Ihrer Benachrichtigung nur für einen bestimmten Zeitraum relevant ist. Wenn Sie beispielsweise eine Kalenderereigniserinnerung senden, legen Sie die Ablaufzeit auf das Ende des Kalenderereignisses fest.

Hinweis

Die Standard- und maximale Ablaufzeit beträgt 3 Tage.

class ToastWithAvatar
{
    public static bool SendToast()
    {

        var appNotification = new AppNotificationBuilder()
            .SetAppLogoOverride(new System.Uri("ms-appx:///images/logo.png"), AppNotificationImageCrop.Circle)
            .AddText("Example expiring notification")
            .AddText("This is an example message")
            .BuildNotification();


        appNotification.Expiration = DateTime.Now.AddDays(1);
        AppNotificationManager.Default.Show(appNotification);

        return appNotification.Id != 0; // return true (indicating success) if the toast was sent (if it has an Id)
    }
}

Sicherstellen, dass Benachrichtigungen beim Neustart ablaufen

Legen Sie die ExpiresOnReboot-Eigenschaft auf True fest, wenn beim Neustart Benachrichtigungen gelöscht werden sollen.

C#

class ToastWithAvatar
{
    public static bool SendToast()
    {

        var appNotification = new AppNotificationBuilder()
            .SetAppLogoOverride(new System.Uri("ms-appx:///images/logo.png"), AppNotificationImageCrop.Circle)
            .AddText("Example ExpiresOnReboot notification")
            .AddText("This is an example message")
            .BuildNotification();


            appNotification.ExpiresOnReboot = true;
            AppNotificationManager.Default.Show(appNotification);

            return appNotification.Id != 0; // return true (indicating success) if the toast was sent (if it has an Id)
    }
}

C++

bool SendToast()
{

    auto appNotification{ winrt::AppNotificationBuilder()
                .SetAppLogoOverride(winrt::Windows::Foundation::Uri(L"ms-appx:///images/logo.png"), winrt::AppNotificationImageCrop::Circle)
                .AddText(L"Example ExpiresOnReboot notification")
                .AddText(L"This is an example message")
                .BuildNotification() };

    appNotification.ExpiresOnReboot();
    winrt::AppNotificationManager::Default().Show(appNotification);

    return appNotification.Id() != 0; // return true (indicating success) if the toast was sent (if it has an Id)
}

Senden und Aktualisieren einer Statusleistenbenachrichtigung

Sie können statusbezogene Aktualisierungen in einer Benachrichtigung anzeigen:

Verwenden Sie das AppNotificationProgressData-Konstrukt, um die Statusleistenbenachrichtigung zu aktualisieren.

const winrt::hstring c_tag = L"weekly-playlist";
const winrt::hstring c_group = L"downloads";

// Send first Notification Progress Update
void SendUpdatableNotificationWithProgress()
{
    auto notification{ winrt::AppNotificationBuilder()
            .AddText(L"Downloading this week's new music...")
            .AddProgressBar(winrt::AppNotificationProgressBar()
                .BindTitle()
                .BindValue()
                .BindValueStringOverride()
                .BindStatus())
            .BuildNotification() }

    notification.Tag(c_tag);
    notification.Group(c_group);

    // Assign initial values for first notification progress UI
    winrt::AppNotificationProgressData data(1); // Sequence number
    data.Title(L"Weekly playlist"); // Binds to {progressTitle} in xml payload
    data.Value(0.6); // Binds to {progressValue} in xml payload
    data.ValueStringOverride(L"15/26 songs"); // Binds to {progressValueString} in xml payload
    data.Status(L"Downloading..."); // Binds to {progressStatus} in xml payload

    notification.Progress(data);
    winrt::AppNotificationManager::Default().Show(notification);
}

// Send subsequent progress updates
winrt::Windows::Foundation::IAsyncAction UpdateProgressAsync()
{
    // Assign new values
    winrt::AppNotificationProgressData data(2 /* Sequence number */ );
    data.Title(L"Weekly playlist"); // Binds to {progressTitle} in xml payload
    data.Value(0.7); // Binds to {progressValue} in xml payload
    data.ValueStringOverride(L"18/26 songs"); // Binds to {progressValueString} in xml payload
    data.Status(L"Downloading..."); // Binds to {progressStatus} in xml payload

    auto result = co_await winrt::AppNotificationManager::Default().UpdateAsync(data, c_tag, c_group);
    if (result == winrt::AppNotificationProgressResult::AppNotificationNotFound)
    {
        // Progress Update failed since the previous notification update was dismissed by the user! So account for this in your logic by stopping updates or starting a new Progress Update flow.
    }
}

Ressourcen

• Details zur Microsoft.Windows.AppNotifications-API
• Codebeispiel für Benachrichtigungen auf GitHub
• App-Benachrichtigungsspezifikation auf GitHub
• Popupinhalt
• XML-Schema für Benachrichtigungen