Mulai cepat: Menggunakan pemberitahuan aplikasi dengan SDK Aplikasi Windows

Dalam mulai cepat ini, Anda akan membuat aplikasi WinUI yang mengirim dan merespons pemberitahuan aplikasi lokal menggunakan SDK Aplikasi Windows.

Untuk contoh lengkap aplikasi yang menerapkan pemberitahuan aplikasi, lihat repositori SDK Aplikasi Windows Sampel pada GitHub.

Important

Pemberitahuan aplikasi tidak didukung untuk aplikasi dengan hak admin.

Prerequisites

• Menginstal Visual Studio 2026
  • Unduh Komunitas 2026
  • Unduh 2026 Professional
  • Unduh 2026 Enterprise
• Sertakan beban kerja C++ atau beban kerja .NET untuk pengembangan C#.
• Pastikan bahwa MSIX Packaging Tools dalam pengembangan desktop .NET sudah dipilih.
• Pastikan Pengembangan Aplikasi Windows dipilih.
• Pastikan Pengembangan Aplikasi UI Windows dipilih.

Untuk informasi selengkapnya tentang mengelola beban kerja di Visual Studio, lihat Modify Visual Studio beban kerja, komponen, dan paket bahasa. Untuk informasi selengkapnya tentang mulai menggunakan WinUI, lihat Mulai menggunakan WinUI. Untuk menambahkan SDK Aplikasi Windows ke proyek yang sudah ada, lihat Gunakan SDK Aplikasi Windows dalam proyek yang sudah ada.

Membuat proyek aplikasi WinUI baru di Visual Studio

1. Di Visual Studio, buat proyek baru.
2. Dalam dialog Buat proyek baru , atur filter bahasa ke "C#" atau "C++" dan filter platform ke "WinUI", lalu pilih templat proyek "Aplikasi Kosong, Dipaketkan (WinUI 3 di Desktop)".
3. Beri nama proyek baru "AppNotificationsExample".

Mengirim pemberitahuan aplikasi lokal

Di bagian ini, Anda akan menambahkan tombol ke aplikasi yang mengirim pemberitahuan aplikasi lokal saat diklik. Pemberitahuan akan menyertakan konten teks dan gambar logo aplikasi. Anda juga akan menambahkan dua kotak teks baca-saja yang akan menampilkan argumen aktivasi saat pengguna mengklik pemberitahuan.

Pertama, tambahkan kontrol Tombol dan dua kontrol TextBox ke 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)"/>

API pemberitahuan aplikasi berada di Microsoft.Windows. AppNotifications dan Microsoft.Windows. AppNotifications.Builder namespace. Tambahkan referensi berikut ke proyek Anda:

C#

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

C++

Tambahkan direktif berikut ini ke file header yang telah dikommpilasikan sebelumnya (pch.h):

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

Sekarang, tambahkan kode berikut ke handler klik tombol Anda. Contoh ini menggunakan AppNotificationBuilder untuk membuat konten pemberitahuan, termasuk argumen yang akan diteruskan kembali ke aplikasi saat pengguna mengklik pemberitahuan, gambar logo aplikasi, dan teks. Pemberitahuan juga menyertakan tombol yang menunjukkan melakukan tindakan tanpa meluncurkan UI aplikasi. Metode BuildNotification membuat objek AppNotification , dan AppNotificationManager.Show menampilkannya kepada pengguna.

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

Pada titik ini, Anda dapat membuat dan menjalankan aplikasi Anda. Klik tombol Kirim Pemberitahuan Aplikasi untuk menampilkan pemberitahuan. Perhatikan bahwa mengklik pemberitahuan belum akan melakukan tindakan apa pun — di bagian berikutnya, Anda akan mempelajari cara menangani aktivasi aplikasi sehingga aplikasi Anda dapat merespons saat pengguna mengklik pemberitahuan.

Note

Pemberitahuan aplikasi tidak didukung saat aplikasi Anda berjalan dengan hak istimewa administrator (ditinggikan). Tampilkan akan gagal secara diam-diam dan tidak ada pemberitahuan yang akan ditampilkan. Pastikan Anda menjalankan aplikasi tanpa elevasi saat menguji pemberitahuan.

Memperbarui file manifes paket aplikasi

File Package.appmanifest ini menyediakan rincian tentang paket MSIX untuk sebuah aplikasi. Untuk memungkinkan aplikasi diluncurkan saat pengguna berinteraksi dengan pemberitahuan aplikasi, Anda harus memperbarui file manifes paket aplikasi sehingga aplikasi Anda terdaftar di sistem sebagai target untuk aktivasi pemberitahuan aplikasi. Untuk informasi selengkapnya tentang manifes paket aplikasi, lihat Manifes paket aplikasi.

1. Edit file Package.appxmanifest dengan mengklik kanan file di Penjelajah Solusi dan memilih Tampilkan Kode.
2. Tambahkan xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" dan xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" namespace ke <Package>.
3. <desktop:Extension> Tambahkan elemen di bawah <Extensions>. Atur Category atribut ke "windows.toastNotificationActivation" untuk menyatakan bahwa aplikasi Anda dapat diaktifkan oleh pemberitahuan aplikasi.
   • <desktop:ToastNotificationActivation> Tambahkan elemen turunan ToastActivatorCLSID dan atur ke GUID yang akan mengidentifikasi aplikasi Anda secara unik.
   • Anda dapat membuat GUID di Visual Studio dengan membuka Tools > Buat GUID.
4. <com:Extension> Tambahkan elemen di bawah <Extensions> dan atur atribut ke Category"windows.comServer". Contoh file manifes yang ditunjukkan di bawah ini menunjukkan sintaks untuk elemen ini.
   • Perbarui atribut Executable dari elemen <com:ExeServer> dengan nama executable Anda. Untuk contoh ini, namanya adalah "AppNotificationsExample.exe".
   • Tentukan Arguments="----AppNotificationActivated:" untuk memastikan bahwa SDK Aplikasi Windows dapat memproses payload pemberitahuan Anda sebagai tipe AppNotification.
   • Atur atribut Id elemen <com:Class> ke GUID yang sama dengan yang Anda gunakan untuk 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>

Penanganan aktivasi melalui pemberitahuan aplikasi

Saat pengguna mengklik pemberitahuan aplikasi atau tombol dalam pemberitahuan, aplikasi Anda perlu merespons dengan tepat. Ada dua skenario aktivasi umum:

1. Luncurkan dengan UI — Pengguna mengklik isi pemberitahuan dan aplikasi Anda harus diluncurkan atau datang ke latar depan, menampilkan konten yang relevan.
2. Tindakan latar belakang — Pengguna mengklik tombol di pemberitahuan yang memicu tindakan (seperti mengirim balasan) tanpa menampilkan UI aplikasi apa pun.

Untuk mendukung kedua skenario, alur aktivasi aplikasi Anda harus membuat jendela utama di OnLaunched tetapi tidak segera mengaktifkannya. Sebagai gantinya, daftarkan peristiwa AppNotificationManager.NotificationInvoked , panggil AppNotificationManager.Register, lalu periksa AppInstance.GetActivatedEventArgs untuk menentukan apakah ini adalah peluncuran normal atau jalur aktivasi COM yang harus menunggu NotificationInvoked. Kode Anda kemudian dapat memutuskan apakah akan menampilkan jendela atau menangani tindakan secara diam-diam dan keluar.

Peristiwa NotificationInvoked menangani klik yang terjadi saat aplikasi sudah berjalan. Saat aplikasi tidak berjalan, Windows meluncurkan aplikasi melalui aktivasi COM dan jenis aktivasi dilaporkan sebagai Launch, bukan AppNotification. Argumen pemberitahuan kemudian dikirimkan melalui NotificationInvoked event.

Important

Anda harus memanggil AppNotificationManager.Register sebelum memanggil AppInstance.GetActivatedEventArgs.

Important

Pengaturan activationType="background" dalam payload XML notifikasi diabaikan dalam aplikasi desktop. Anda harus memproses argumen aktivasi dalam kode Anda dan memutuskan apakah akan menampilkan jendela atau tidak.

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

Tambahkan deklarasi HandleNotification ke kelas App di 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);
    };
}

Perbarui App.xaml.cpp dengan alur aktivasi. Tambahkan #include <winrt/Microsoft.Windows.AppLifecycle.h> ke pch.h Anda.

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

UpdateNotificationUI Tambahkan metode untuk MainWindow menampilkan argumen pemberitahuan dalam kotak teks yang ditambahkan sebelumnya.

C#

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

C++

Tambahkan deklarasi ke MainWindow.xaml.h:

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

Terapkan metode dalam 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);
    });
}

Langkah berikutnya

• Konten pemberitahuan aplikasi — pelajari cara menambahkan gambar, tombol, input, dan elemen UI lainnya ke pemberitahuan Anda.
• Hapus pemberitahuan aplikasi — pelajari cara menandai, menghapus, dan mengatur kedaluwarsa pada pemberitahuan Anda.

Baca juga

• Gambaran umum pemberitahuan aplikasi
• Bilah kemajuan pemberitahuan aplikasi
• sampel kode Notifications pada GitHub
• Microsoft.Windows.AppNotifications API Referensi
• Skema XML Pemberitahuan