Hızlı Başlangıç: Windows Uygulama SDK'sı ile uygulama bildirimlerini kullanma

Bu hızlı başlangıçta, Windows Uygulama SDK'sı kullanarak yerel uygulama bildirimlerini gönderen ve yanıtlayan bir WinUI uygulaması oluşturacaksınız.

Uygulama bildirimleri uygulayan tüm örnek uygulamalar için GitHub üzerindeki Windows Uygulama SDK'sı Samples deposuna bakın.

Important

Yükseltilmiş (yönetici) uygulamalar için uygulama bildirimleri desteklenmez.

Prerequisites

• Visual Studio 2022'yi yükleme (v17.6+)
  • 2022 Community
  • 2022 Professional
  • 2022 Enterprise
• C++ için C++ iş yükünü veya C# geliştirme için .NET iş yüklerini ekleyin.
• Masaüstü geliştirme .NET altındaki MSIX Paketleme Araçları'nın seçili olduğundan emin olun.
• Windows Uygulama Geliştirme'nin seçili olduğundan emin olun.
• Windows Kullanıcı Arabirimi Uygulama Geliştirme'nin seçili olduğundan emin olun.

Visual Studio iş yüklerini yönetme hakkında daha fazla bilgi için bkz. >Visual Studio iş yüklerini, bileşenlerini ve dil paketlerini değiştirme. WinUI'yi kullanmaya başlama hakkında daha fazla bilgi için bkz. WinUI'yi kullanmaya başlama. Windows Uygulama SDK'sı var olan bir projeye eklemek için bkz. Var olan bir projede Windows Uygulama SDK'sı kullanma.

Visual Studio'da yeni bir WinUI uygulama projesi oluşturma

1. Visual Studio'da yeni bir proje oluşturun.
2. Yeni proje oluştur iletişim kutusunda dil filtresini "C#" veya "C++" ve platform filtresini "WinUI" olarak ayarlayın, ardından "Boş Uygulama, Paketlenmiş (Masaüstünde WinUI 3)" proje şablonunu seçin.
3. Yeni projeyi "AppNotificationsExample" olarak adlandırın.

Yerel uygulama bildirimi gönderme

Bu bölümde, uygulamanıza tıklandığında yerel uygulama bildirimi gönderen bir düğme ekleyeceksiniz. Bildirimde metin içeriği ve bir uygulama logosu resmi yer alır. Kullanıcı bildirime tıkladığında etkinleştirme bağımsız değişkenlerini görüntüleyen iki salt okunur metin kutusu da ekleyeceksiniz.

İlk olarak, bir Button denetimi ve iki TextBox denetimi ekleyin:

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)"/>

Uygulama bildirimi API'leri Microsoft.Windows. AppNotifications ve Microsoft.Windows. AppNotifications.Builder ad alanları. Projenize aşağıdaki referansları ekleyin:

C#

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

C++

Aşağıdaki include yönergelerini önceden derlenmiş üst bilgi dosyanıza (pch.h) ekleyin:

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

Şimdi düğme tıklama işleyicinize aşağıdaki kodu ekleyin. Bu örnekte, kullanıcı bildirime tıkladığında uygulamaya geri geçirilecek bağımsız değişkenler, bir uygulama logosu resmi ve metin de dahil olmak üzere bildirim içeriği oluşturmak için AppNotificationBuilder kullanılır. Bildirim, uygulamanın kullanıcı arabirimini başlatmadan eylem gerçekleştirmeyi gösteren bir düğme de içerir. BuildNotification yöntemi AppNotification nesnesini oluşturur ve AppNotificationManager.Show bunu kullanıcıya görüntüler.

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

Bu noktada uygulamanızı derleyebilir ve çalıştırabilirsiniz. Bildirimi görüntülemek için Uygulama Bildirimi Gönder düğmesine tıklayın. Bildirime tıklandığında henüz herhangi bir işlem yapılmayacağını unutmayın; sonraki bölümde, kullanıcı bildirime tıkladığında uygulamanızın yanıt verebilmesi için uygulama etkinleştirmeyi nasıl işleyebileceğinizi öğreneceksiniz.

Note

Uygulamanız yönetici ayrıcalıklarıyla (yükseltilmiş) çalışırken uygulama bildirimleri desteklenmez. Göster sessizce başarısız olur ve hiçbir bildirim görüntülenmez. Bildirimleri test ederken uygulamanızı yükseltme olmadan çalıştırdığınızdan emin olun.

Uygulama paketi bildirim dosyasını güncelleştirme

Dosya, Package.appmanifest bir uygulama için MSIX paketinin ayrıntılarını sağlar. Kullanıcı bir uygulama bildirimiyle etkileşime geçtiğinde uygulamanızın başlatılmasını sağlamak için, uygulamanızın uygulama bildirimi etkinleştirme hedefi olarak sisteme kaydedilmesi için uygulama paketi bildirim dosyanızı güncelleştirmeniz gerekir. Uygulama paketi bildirimleri hakkında daha fazla bilgi için bkz. Uygulama paketi bildirimi.

1. Package.appxmanifest dosyasını düzenlemek için Çözüm Gezgini'da dosyaya sağ tıklayın ve View Code öğesini seçin.
2. xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" ve xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" ad alanlarını <Package> öğesine ekleyin.
3. <desktop:Extension> altına bir <Extensions> öğesi ekleyin. Uygulamanızın Category uygulama bildirimleriyle etkinleştirilebileceğini bildirmek için özniteliğini "windows.toastNotificationActivation" olarak ayarlayın.
   • Bir <desktop:ToastNotificationActivation> alt öğe ekleyin ve ToastActivatorCLSID öğesini uygulamanızı benzersiz olarak tanımlayacak bir GUID olarak ayarlayın.
   • Tools > CREATE GUID adresine giderek Visual Studio'da GUID oluşturabilirsiniz.
4. altına <com:Extension> bir <Extensions> öğe ekleyin ve özniteliğini Category olarak "windows.comServer"ayarlayın. Aşağıda gösterilen örnek bildirim dosyası, bu öğenin söz dizimini gösterir.
   • öğesinin Executable<com:ExeServer> özniteliğini yürütülebilir adınız ile güncelleştirin. Bu örnekte ad olacaktır "AppNotificationsExample.exe".
   • Windows Uygulama SDK'sı bildiriminizin yükünü appNotification türü olarak işleyebilmesini sağlamak için Arguments="----AppNotificationActivated:" belirtin.
   • Id öğesinin <com:Class> özniteliğini, ToastActivatorCLSID özniteliği için kullandığınız GUID ile ayarlayın.

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

Uygulama bildiriminden etkinleştirmeyi işleme

Kullanıcı bir uygulama bildirimine veya bildirim içindeki bir düğmeye tıkladığında uygulamanızın uygun şekilde yanıt vermesi gerekir. İki yaygın etkinleştirme senaryosu vardır:

1. Kullanıcı arabirimiyle başlat — Kullanıcı bildirim gövdesine tıklar ve uygulamanız başlatılmalıdır veya ilgili içeriği görüntüleyerek ön plana gelmelidir.
2. Arka plan eylemi — Kullanıcı, herhangi bir uygulama kullanıcı arabirimi göstermeden bir eylemi (yanıt gönderme gibi) tetikleyen bildirimdeki bir düğmeye tıklar.

Her iki senaryoyu da desteklemek için uygulamanızın etkinleştirme akışında OnLaunched ana pencere oluşturulmalıdır ancak hemen etkinleştirilmemelidir . Bunun yerine AppNotificationManager.NotificationInvoked olayını kaydedin, AppNotificationManager.Register'ı çağırın ve ardından bunun normal bir başlatma mı yoksa beklemesi gereken bir COM etkinleştirme yolu mu olduğunu belirlemek için NotificationInvoked denetleyin. Kodunuz daha sonra pencereyi göstermeyi veya eylemi sessizce işleyip çıkmamaya karar verebilir.

Olay, NotificationInvoked uygulama zaten çalışıyorken gerçekleşen tıklamaları işler. Uygulama çalışmadığında, Windows com etkinleştirmesi aracılığıyla uygulamayı başlatır ve etkinleştirme türü Launch olarak değil AppNotification olarak bildirilir. Bildirim bağımsız değişkenleri daha sonra olaya NotificationInvoked aracılığıyla teslim edilir.

Important

AppInstance.GetActivatedEventArgs'ı çağırmadan önce AppNotificationManager.Register'ı çağırmalısınız.

Important

Bildirim XML yüklemesindeki activationType="background" ayarı masaüstü uygulamaları için yoksayılır. Etkinleştirme bağımsız değişkenlerini kodunuzda işlemeli ve bir pencere görüntüleyip görüntülememeye karar vermelisiniz.

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

HandleNotification sınıfına App bildirimini App.xaml.h ekleyin.

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

Etkinleştirme süreciyle App.xaml.cpp güncelleyin. #include <winrt/Microsoft.Windows.AppLifecycle.h> öğesini pch.h'nize ekleyin.

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

Bildirim bağımsız değişkenlerini daha önce eklenen metin kutularında görüntülemek için UpdateNotificationUI öğesine bir MainWindow yöntemi ekleyin.

C#

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

C++

bildirimi MainWindow.xaml.h içine ekleyin.

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

Metodu MainWindow.xaml.cpp içinde uygulayın.

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

Sonraki Adımlar

• Uygulama bildirimi içeriği — Bildirimlerinize görüntü, düğme, giriş ve diğer kullanıcı arabirimi öğelerini eklemeyi öğrenin.
• Uygulama bildirimlerini kaldırma — bildirimlerinizde etiketlemeyi, kaldırmayı ve süre sonunu ayarlamayı öğrenin.

Ayrıca bakınız

• Uygulama bildirimlerine genel bakış
• Uygulama bildirimi ilerleme çubuğu
• GitHub'da Bildirimler kod örneği
• Microsoft.Windows. AppNotifications API başvurusu
• Bildirimleri XML şeması