Gyors kezdés: Alkalmazásértesítések használata a Windows App SDK-vel

Ebben a rövid útmutatóban egy WinUI-alkalmazást fog létrehozni, amely a Windows App SDK használatával küld és válaszol a helyi alkalmazásértesítésekre.

Az alkalmazásértesítéseket megvalósító teljes mintaalkalmazásokért tekintse meg a Windows App SDK Minta adattárat GitHub.

Important

Az alkalmazásértesítések nem támogatottak emelt szintű (rendszergazdai) alkalmazások esetében.

Prerequisites

• Visual Studio 2026 telepítése
  • A 2026-os Közösségi verzió letöltése
  • 2026 Professional letöltése
  • 2026 Nagyvállalati verzió letöltése
• A C++ vagy .NET munkaterhelés hozzáadása C++ vagy C# fejlesztéshez.
• Győződjön meg arról, hogy az MSIX Csomagolóeszközök .NET asztali fejlesztés alatt van kiválasztva.
• Győződjön meg arról, hogy Windows alkalmazásfejlesztés van kiválasztva.
• Győződjön meg arról, hogy Windows felhasználói felület alkalmazásfejlesztése ki van választva.

A számítási feladatok Visual Studio történő kezelésével kapcsolatos további információkért lásd: Modify Visual Studio számítási feladatok, összetevők és nyelvi csomagok. A WinUI használatának megkezdéséről további információt a WinUI 3-projekt létrehozása és futtatása című témakörben talál. A Windows App SDK meglévő projekthez való hozzáadásához lásd: Az Windows App SDK egy meglévő projektben.

Új WinUI-alkalmazásprojekt létrehozása a Visual Studio

1. A Visual Studio-ban hozzon létre egy új projektet.
2. Az Új projekt létrehozása párbeszédpanelen állítsa a nyelvi szűrőt "C#" vagy "C++" értékre, a platformszűrőt pedig "WinUI" értékre, majd válassza az "Üres alkalmazás, csomagolt (WinUI 3 az asztalon)" projektsablont.
3. Adja az új projektnek az "AppNotificationsExample" nevet.

Helyi alkalmazásértesítés küldése

Ebben a szakaszban egy gombot fog hozzáadni az alkalmazáshoz, amely kattintáskor helyi alkalmazásértesítést küld. Az értesítés szöveges tartalmat és egy alkalmazás emblémáját tartalmazza. Két írásvédett szövegdobozt is hozzáad, amelyek az aktiválási argumentumokat jelenítik meg, amikor a felhasználó az értesítésre kattint.

Először adjon hozzá egy gombvezérlőt és két TextBox-vezérlőt a következőhöz 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)"/>

Az alkalmazásértesítési API-k a Microsoft.Windows.AppNotifications és Microsoft.Windows.AppNotifications.Builder névterekben találhatók. Adja hozzá a következő hivatkozásokat a projekthez:

C#

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

C++

Adja hozzá az alábbi belefoglalási irányelveket az előre összeállított fejlécfájlhoz (pch.h):

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

Most adja hozzá a következő kódot a gomb kattintáskezelőjéhez. Ez a példa az AppNotificationBuilder használatával hoz létre értesítési tartalmat, beleértve azokat az argumentumokat is, amelyeket a felhasználó az értesítésre, az alkalmazás emblémájának képére és szövegére való kattintáskor ad vissza az alkalmazásnak. Az értesítés tartalmaz egy gombot is, amely az alkalmazás felhasználói felületének elindítása nélkül mutatja be a műveletet. A BuildNotification metódus létrehozza az AppNotification objektumot , és az AppNotificationManager.Show megjeleníti azt a felhasználónak.

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

Ezen a ponton létrehozhatja és futtathatja az alkalmazást. Az értesítés megjelenítéséhez kattintson az Alkalmazásértesítés küldése gombra. Vegye figyelembe, hogy az értesítésre való kattintás még nem hajt végre semmilyen műveletet – a következő szakaszban megtudhatja, hogyan kezelheti az alkalmazás aktiválását, hogy az alkalmazás reagálni tudjon, amikor egy felhasználó az értesítésre kattint.

Note

Az alkalmazásértesítések nem támogatottak, ha az alkalmazás rendszergazdai jogosultságokkal (emelt szintű) fut. A megjelenítés csendesen meghiúsul, és nem jelenik meg értesítés. Az értesítések tesztelése során győződjön meg arról, hogy az alkalmazást jogosultságszint-emelés nélkül futtatja.

Az alkalmazáscsomag jegyzékfájljának frissítése

A Package.appmanifest fájl egy alkalmazás MSIX-csomagjának részleteit tartalmazza. Ahhoz, hogy az alkalmazás elindulhasson, amikor egy felhasználó egy alkalmazásértesítést használ, frissítenie kell az alkalmazáscsomag jegyzékfájlját, hogy az alkalmazás regisztrálva legyen a rendszerben az alkalmazás értesítési aktiválásának célhelyeként. Az alkalmazáscsomag-jegyzékekkel kapcsolatos további információkért tekintse meg az alkalmazáscsomag jegyzékfájlját.

1. A Package.appxmanifest fájl szerkesztéséhez kattintson a jobb gombbal a Megoldáskezelő fájlra, és válassza a View Code lehetőséget.
2. Adja hozzá a(z) xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" és xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" névtereket a <Package>.
3. Adjon hozzá egy <desktop:Extension> elemet a <Extensions> alá. Állítsa be az Category attribútumot "windows.toastNotificationActivation" úgy, hogy deklarálja, hogy az alkalmazás aktiválható az alkalmazásértesítések segítségével.
   • Adjon hozzá egy <desktop:ToastNotificationActivation> gyermekelemet, és állítsa be a ToastActivatorCLSID elemet egy GUID-ra, amely egyedileg azonosítja az alkalmazást.
   • Ön egy GUID-azonosítót hozhat létre a Visual Studio-ban a következő úton: Eszközök > GUID létrehozása.
4. Adjon hozzá egy <com:Extension> elemet <Extensions> alá, és állítsa be a Category attribútumot "windows.comServer"-ra. Az alábbi példajegyzékfájl az elem szintaxisát mutatja be.
   • Frissítse a Executable attribútumát a <com:ExeServer> elemnél a futtatható fájl nevével. Ebben a példában a név a következő lesz "AppNotificationsExample.exe": .
   • Adja meg a Arguments="----AppNotificationActivated:", hogy az Windows App SDK appNotification típusúként tudja feldolgozni az értesítés hasznos adatait.
   • Állítsa az Id elem attribútumát <com:Class> ugyanarra a GUID-ra, amelyet az ToastActivatorCLSID attribútumhoz használt.

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

Aktiválás kezelése alkalmazásértesítésből

Amikor egy felhasználó egy alkalmazásértesítésre vagy egy értesítésen belüli gombra kattint, az alkalmazásnak megfelelően kell válaszolnia. Két gyakori aktiválási forgatókönyv létezik:

1. Indítás felhasználói felülettel – A felhasználó az értesítési törzsre kattint, és az alkalmazásnak el kell indulnia vagy előtérbe kell jönnie, megjelenítve a releváns tartalmat.
2. Háttérművelet – A felhasználó egy gombra kattint az értesítésben, amely elindít egy műveletet (például választ küld), anélkül, hogy megjelenítené az alkalmazás felhasználói felületét.

Mindkét forgatókönyv támogatásához az alkalmazás aktiválási folyamatának létre kell hoznia a fő ablakot OnLaunched , de nem kell azonnal aktiválnia. Ehelyett regisztrálja az AppNotificationManager.NotificationInvoked eseményt, hívja meg az AppNotificationManager.Register nevet, majd ellenőrizze az AppInstance.GetActivatedEventArgs elemet annak megállapításához, hogy ez egy normál indítás vagy egy COM-aktiválási útvonal, amelyre NotificationInvokedvárnia kell. A kód ezután eldöntheti, hogy megjeleníti-e az ablakot, vagy csendben kezeli a műveletet, és kilép.

Az NotificationInvoked esemény kezeli azokat a kattintásokat, amelyek akkor fordulnak elő, amikor az alkalmazás már fut. Ha az alkalmazás nem fut, Windows com-aktiválással indítja el az alkalmazást, és az aktiválás típusa Launch, nem pedig AppNotification. Az értesítési argumentumok ezután az NotificationInvoked eseményen keresztül lesznek kézbesítve.

Important

Az AppInstance.GetActivatedEventArgs hívása előtt meg kell hívnia az AppNotificationManager.Register alkalmazást.

Important

Az értesítési XML hasznos adatainak beállítása activationType="background" figyelmen kívül lesz hagyva az asztali alkalmazások esetében. Fel kell dolgoznia az aktiválási argumentumokat a kódban, és el kell döntenie, hogy megjelenít-e egy ablakot.

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

Adja hozzá a HandleNotification deklarációt a App helyen lévő App.xaml.h osztályhoz.

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

Frissítse App.xaml.cpp az aktiválási folyamatot. Adja hozzá #include <winrt/Microsoft.Windows.AppLifecycle.h> a 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);
            }
        });
    }
}

Adjon hozzá egy metódust UpdateNotificationUI az MainWindow értesítési argumentumok megjelenítéséhez a korábban hozzáadott szövegmezőkben.

C#

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

C++

Adja hozzá a deklarációt a következőhöz MainWindow.xaml.h:

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

Implementálja a metódust a következő helyen 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);
    });
}

Következő lépések

• Alkalmazásértesítési tartalom – megtudhatja, hogyan adhat hozzá képeket, gombokat, bemeneteket és egyéb felhasználói felületi elemeket az értesítésekhez.
• Alkalmazásértesítések eltávolítása – megtudhatja, hogyan címkézheti, távolíthatja el és állíthatja be az értesítések lejáratát.

Lásd még

• Alkalmazásértesítések áttekintése
• Alkalmazásértesítés folyamatjelző sávja
• Értesítések kódminta a GitHubon
• Microsoft.Windows. AppNotifications API-referencia
• Értesítések XML-sémája