Snabbstart: Använda appaviseringar med Windows App SDK

I den här snabbstarten skapar du en WinUI-app som skickar och svarar på lokala appmeddelanden med hjälp av Windows App SDK.

Fullständiga exempelappar som implementerar appmeddelanden finns i lagringsplatsen Windows App SDK Samples på GitHub.

Important

Appaviseringar stöds inte för förhöjda appar (administratör).

Prerequisites

• Installera Visual Studio 2022 (v17.6+)
  • Download 2022 Community
  • Download 2022 Professional
  • Download 2022 Enterprise
• Inkludera C++-arbetsbelastning för C++ eller .NET arbetsbelastningar för C#-utveckling.
• Kontrollera att MSIX-paketeringsverktyg under .NET skrivbordsutveckling har valts.
• Kontrollera att Windows Programutveckling har valts.
• Kontrollera att Windows UI Application Development har valts.

Mer information om hur du hanterar arbetsbelastningar i Visual Studio finns i Modify Visual Studio arbetsbelastningar, komponenter och språkpaket. Mer information om hur du kommer igång med WinUI finns i Komma igång med WinUI. Information om hur du lägger till Windows App SDK i ett befintligt projekt finns i Använd Windows App SDK i ett befintligt projekt.

Skapa ett nytt WinUI-appprojekt i Visual Studio

1. Skapa ett nytt projekt i Visual Studio.
2. I dialogrutan Skapa ett nytt projekt anger du språkfiltret till "C#" eller "C++" och plattformsfiltret till "WinUI" och väljer sedan projektmallen "Tom app, paketerad (WinUI 3 i Desktop)".
3. Ge det nya projektet namnet "AppNotificationsExample".

Skicka ett meddelande om lokal app

I det här avsnittet lägger du till en knapp i din app som skickar ett lokalt appmeddelande när du klickar. Meddelandet innehåller textinnehåll och en applogotypbild. Du lägger också till två skrivskyddade textrutor som visar aktiveringsargumenten när användaren klickar på meddelandet.

Lägg först till en knappkontroll och två TextBox-kontroller i :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:erna för appmeddelanden finns i Microsoft.Windows. AppNotifications och Microsoft.Windows. AppNotifications.Builder namnområden. Lägg till följande referenser till projektet:

C#

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

C++

Lägg till följande inkluderingsdirektiv i den förkompilerade huvudfilen (pch.h):

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

Lägg nu till följande kod i knappklickshanteraren. I det här exemplet används AppNotificationBuilder för att skapa meddelandeinnehåll, inklusive argument som skickas tillbaka till appen när användaren klickar på meddelandet, en applogotypbild och text. Meddelandet innehåller också en knapp som visar hur du utför en åtgärd utan att starta appens användargränssnitt. Metoden BuildNotification skapar AppNotification-objektet och AppNotificationManager.Show visar det för användaren.

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

Nu kan du skapa och köra din app. Klicka på knappen Skicka appavisering för att visa meddelandet. Observera att om du klickar på meddelandet utförs ingen åtgärd ännu – i nästa avsnitt får du lära dig hur du hanterar appaktivering så att appen kan svara när en användare klickar på meddelandet.

Note

Appmeddelanden stöds inte när din app körs med administratörsbehörighet (upphöjd). Visa kommer att misslyckas tyst, och inget meddelande kommer att visas. Se till att du kör din app utan utökade privilegier när du testar meddelanden.

Uppdatera apppaketets manifestfil

Filen Package.appmanifest innehåller information om MSIX-paketet för en app. Om du vill att appen ska startas när en användare interagerar med ett appmeddelande måste du uppdatera manifestfilen för apppaketet så att appen registreras med systemet som mål för aktivering av appmeddelanden. Mer information om apppaketmanifest finns i Apppaketmanifest.

1. Redigera filen Package.appxmanifest genom att högerklicka på filen i Prieskumník riešení och välja View Code.
2. Lägg till xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10" och xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10" namnområden i <Package>.
3. Lägg till ett <desktop:Extension> element under <Extensions>. Category Ange attributet till "windows.toastNotificationActivation" för att deklarera att din app kan aktiveras av appaviseringar.
   • Lägg till ett <desktop:ToastNotificationActivation>-underelement och ange ToastActivatorCLSID till en GUID som unikt identifierar din app.
   • Du kan generera ett GUID i Visual Studio genom att gå till Tools > Skapa GUID.
4. Lägg till ett <com:Extension> element under <Extensions> och ange Category attributet till "windows.comServer". Exempelmanifestfilen som visas nedan visar syntaxen för det här elementet.
   • Executable Uppdatera attributet för elementet <com:ExeServer> med ditt körbara namn. I det här exemplet kommer namnet att vara "AppNotificationsExample.exe".
   • Ange Arguments="----AppNotificationActivated:" för att säkerställa att Windows App SDK kan bearbeta meddelandets nyttolast som appnotifieringstyp.
   • Id Ange attributet för elementet <com:Class> till samma GUID som du använde för attributetToastActivatorCLSID.

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

Hantera aktivering från ett appmeddelande

När en användare klickar på ett appmeddelande eller en knapp i ett meddelande måste appen svara på rätt sätt. Det finns två vanliga aktiveringsscenarier:

1. Starta med användargränssnittet – Användaren klickar på meddelandetexten och appen bör starta eller komma till förgrunden och visa relevant innehåll.
2. Bakgrundsåtgärd – Användaren klickar på en knapp i meddelandet som utlöser en åtgärd (till exempel att skicka ett svar) utan att visa något appgränssnitt.

För att stödja båda scenarierna bör appens aktiveringsflöde skapa huvudfönstret i OnLaunched men inte aktivera det omedelbart. Registrera i stället händelsen AppNotificationManager.NotificationInvoked , anropa AppNotificationManager.Register och kontrollera sedan AppInstance.GetActivatedEventArgs för att avgöra om appen startades från ett meddelande eller från en normal start. Om starten utlöstes av ett meddelande kan koden granska meddelandeargumenten och bestämma om fönstret ska visas eller hantera åtgärden tyst och avsluta.

Händelsen NotificationInvoked hanterar klick som inträffar medan appen redan körs. När appen inte körs startar Windows appen via COM-aktivering och aktiveringstyp rapporteras som Launch, inte AppNotification. Meddelandeargumenten levereras sedan via NotificationInvoked händelsen.

Important

Du måste anropa AppNotificationManager.Register innan du anropar AppInstance.GetActivatedEventArgs.

Important

Inställningen activationType="background" i xml-nyttolasten för meddelanden ignoreras för skrivbordsappar. Du måste bearbeta aktiveringsargumenten i koden och bestämma om du vill visa ett fönster eller inte.

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

Lägg till deklarationen HandleNotification i App klassen i 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);
    };
}

Uppdatera App.xaml.cpp med aktiveringsflödet. Lägg till #include <winrt/Microsoft.Windows.AppLifecycle.h> i din 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);
            }
        });
    }
}

Lägg till en UpdateNotificationUI metod för MainWindow att visa meddelandeargumenten i textrutorna som lades till tidigare.

C#

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

C++

Lägg till deklarationen i MainWindow.xaml.h:

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

Implementera metoden i 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);
    });
}

Nästa steg

• Appmeddelandeinnehåll – lär dig hur du lägger till bilder, knappar, indata och andra gränssnittselement i dina meddelanden.
• Ta bort appaviseringar – lär dig hur du taggar, tar bort och anger förfallodatum för dina meddelanden.

Se även

• Översikt över appaviseringar
• Förloppsindikator för appmeddelanden
• Notifieringskodexempel på GitHub
• Microsoft.Windows. Api-referens för AppNotifications
• Notifikationer XML-schema