Freigeben über

Schnellstart: Pushbenachrichtigungen im Windows App SDK

In dieser Schnellstartanleitung erstellen Sie eine Windows-Desktopanwendung, die Pushbenachrichtigungen mithilfe des Windows App SDK sendet und empfängt.

Voraussetzungen

Beispiel-App

Diese Schnellstartanleitung zeigt Ihnen, wie Sie Ihrem Programm Unterstützung für Push-Benachrichtigungen hinzufügen. Sehen Sie sich im Kontext den Beispielcode aus dieser Schnellstartanleitung in den Beispiel-Apps an, die auf GitHubzu finden sind.

Beispiel-App-Code

API-Referenz

Api-Referenzdokumentation für Pushbenachrichtigungen finden Sie unter Microsoft.Windows.PushNotifications Namespace.

Konfigurieren der Identität Ihrer App in Azure Active Directory (AAD)

Pushbenachrichtigungen im Windows App SDK verwenden Identitäten aus Azure Active Directory (AAD). Azure-Anmeldeinformationen sind beim Anfordern eines WNS-Kanal-URI und beim Anfordern von Zugriffstoken erforderlich, um Pushbenachrichtigungen zu senden. Hinweis: Wir bieten KEINE Unterstützung für die Verwendung von Windows App SDK-Pushbenachrichtigungen mit Microsoft Partner Center an.

Schritt 1: Erstellen einer AAD-App-Registrierung

Melden Sie sich bei Ihrem Azure-Konto an und erstellen Sie eine neue Ressource für die AAD-App-Registrierung. Wählen Sie Neue Registrierung aus.

Schritt 2: Geben Sie einen Namen ein, und wählen Sie eine Option für mehrere Mandanten aus.

  1. Geben Sie einen App-Namen an.

  2. Pushbenachrichtigungen erfordern die Option für mehrere Mandanten. Wählen Sie dies also aus.

    1. Weitere Informationen zu Benutzern finden Sie unter Wer kann sich in Ihrer App anmelden?.

  3. Wählen Sie Registrieren aus.

  4. Notieren Sie sich Ihre Anwendungs-ID (Client-ID), da dies Ihre Azure AppId ist, die Sie während der Aktivierungsregistrierung und Zugriffstokenanforderung verwenden.

  5. Notieren Sie sich Ihre Verzeichnis-ID (Mandanten-ID), da dies Ihre Azure-Mandanten-ID ist, die Sie bei der Anforderung eines Zugriffstokens verwenden.

    Von Bedeutung

    AAD-App-Registrierungsmandant Merken Sie sich die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Mandanten-ID) .

  6. Notieren Sie sich Ihre Objekt-ID, da dies Ihre Azure ObjectId ist, die Sie bei einer Kanalanfrage verwenden werden. Beachten Sie, dass dies NICHT die Objekt-ID ist, die auf der Essentials-Seite aufgeführt ist. Um die richtige Objekt-IDzu finden, klicken Sie stattdessen im Feld der verwalteten Anwendung im lokalen Verzeichnis auf den App-Namen auf der Seite Essentials.

    Screenshot der Option „Verwaltete Anwendung im lokalen Verzeichnis“ auf der Seite „Essentials“

    Screenshot des Felds

    Hinweis

    Ein Dienstprinzipal ist erforderlich, um eine Objekt-ID abzurufen. Falls Ihrer App keine zugeordnet ist, führen Sie die Schritte in einem der folgenden Artikel aus, um eine Objekt-ID im Azure-Portal zu erstellen oder über die Befehlszeile zu erstellen.

    Verwenden des Portals zum Erstellen einer Azure AD-Anwendung und eines Dienstprinzipals, die auf Ressourcen zugreifen

    Verwenden von Azure PowerShell zum Erstellen eines Dienstprinzipals mit einem Zertifikat

Schritt 3: Erstellen eines geheimen Schlüssels für Ihre App-Registrierung

Ihr Geheimer Schlüssel wird zusammen mit Ihrer Azure AppId/ClientId verwendet, wenn Sie ein Zugriffstoken zum Senden von Pushbenachrichtigungen anfordern.

AAD App Secret

Navigieren Sie zu Zertifikate und Geheimnisse und wählen Sie Neues Clientgeheimnis aus.

Von Bedeutung

Stellen Sie sicher, dass Sie Ihren geheimen Schlüssel nach dem Erstellen kopieren und an einem sicheren Speicherort speichern, z. B. Azure Key Vault. Sie kann nur einmal direkt nach der Erstellung angezeigt werden.

Schritt 4: Ordnen Sie den Paketfamiliennamen Ihrer App der Azure App-ID zu.

Wenn Ihre App gepackt ist (einschließlich paketiert mit einem externen Speicherort), können Sie diesen Prozess verwenden, um den Paketfamiliennamen (Package Family Name, PFN) Ihrer App und deren Azure AppId zuzuordnen.

Wenn Ihre App eine gepackte Win32-App ist, erstellen Sie eine PFN-Zuordnungsanforderung (Package Family Name), indem Sie eine E-Mail mit der Betreffzeile "Windows App SDK Push Notifications Mapping Request" und dem Text "PFN: [Your PFN]", AppId: [Your APPId], ObjectId: [your ObjectId] senden Win_App_SDK_Push@microsoft.com . Zuordnungsanfragen werden wöchentlich bearbeitet. Sie werden benachrichtigt, sobald Ihre Mapping-Anfrage abgeschlossen ist.

konfigurieren Sie Ihre App für den Empfang von Pushbenachrichtigungen

Schritt 1: Hinzufügen von Namespacedeklarationen

Fügen Sie den Namespace für Windows App SDK-Pushbenachrichtigungen Microsoft.Windows.PushNotificationshinzu.

#include <winrt/Microsoft.Windows.PushNotifications.h>

using namespace winrt::Microsoft::Windows::PushNotifications;

Schritt 2: Hinzufügen des COM-Aktivators zum Manifest Ihrer App

Von Bedeutung

Wenn Ihre App entpackt ist (d. h., es fehlt die Paketidentität zur Laufzeit), überspringen Sie zu Schritt 3: Registrieren und reagieren Sie auf Pushbenachrichtigungen beim App-Start.

Wenn Ihre App verpackt ist (einschließlich mit externem Speicherort verpackt): Öffnen Sie Ihre Package.appxmanifest. Fügen Sie Folgendes innerhalb des <Application>-Elements hinzu. Ersetzen Sie die Werte Id, Executable und DisplayName durch die für Ihre App spezifischen Werte.

<!--Packaged apps only-->
<!--package.appxmanifest-->

<Package
  ...
  xmlns:com="http://schemas.microsoft.com/appx/manifest/com/windows10"
  ...
  <Applications>
    <Application>
      ...
      <Extensions>

        <!--Register COM activator-->    
        <com:Extension Category="windows.comServer">
          <com:ComServer>
              <com:ExeServer Executable="SampleApp\SampleApp.exe" DisplayName="SampleApp" Arguments="----WindowsAppRuntimePushServer:">
                <com:Class Id="[Your app's Azure AppId]" DisplayName="Windows App SDK Push" />
            </com:ExeServer>
          </com:ComServer>
        </com:Extension>
    
      </Extensions>
    </Application>
  </Applications>
 </Package>

Schritt 3: Registrieren und Reagieren auf Pushbenachrichtigungen beim Starten der App

Aktualisieren Sie die Methode main() Ihrer App, um Folgendes hinzuzufügen:

  1. Registrieren Sie Ihre App, um Pushbenachrichtigungen zu empfangen, indem Sie PushNotificationManager::Default().Register()aufrufen.
  2. Überprüfen Sie die Quelle der Aktivierungsanforderung, indem Sie AppInstance::GetCurrent().GetActivatedEventArgs()aufrufen. Wenn die Aktivierung von einer Pushbenachrichtigung ausgelöst wurde, antworten Sie basierend auf der Nutzlast der Benachrichtigung.

Von Bedeutung

Sie müssen PushNotificationManager::Default().Register aufrufen, bevor Sie AppInstance.GetCurrent.GetActivatedEventArgsaufrufen.

Das folgende Beispiel stammt aus der beispielgepackten App, die auf GitHub-gefunden wurde.

// cpp-console.cpp
#include "pch.h"
#include <iostream>
#include <winrt/Microsoft.Windows.PushNotifications.h>
#include <winrt/Microsoft.Windows.AppLifecycle.h>
#include <winrt/Windows.Foundation.h>
#include <wil/result.h>
#include <wil/cppwinrt.h>


using namespace winrt;
using namespace Windows::Foundation;

using namespace winrt::Microsoft::Windows::PushNotifications;
using namespace winrt::Microsoft::Windows::AppLifecycle;

winrt::guid remoteId{ "7edfab6c-25ae-4678-b406-d1848f97919a" }; // Replace this with your own Azure ObjectId



void SubscribeForegroundEventHandler()
{
    winrt::event_token token{ PushNotificationManager::Default().PushReceived([](auto const&, PushNotificationReceivedEventArgs const& args)
    {
        auto payload{ args.Payload() };

        std::string payloadString(payload.begin(), payload.end());
        std::cout << "\nPush notification content received in the FOREGROUND: " << payloadString << std::endl;
    }) };
}

int main()
{
    // Setup an event handler, so we can receive notifications in the foreground while the app is running.
    SubscribeForegroundEventHandler();

    PushNotificationManager::Default().Register();

    auto args{ AppInstance::GetCurrent().GetActivatedEventArgs() };
    switch (args.Kind())
    {
        // When it is launched normally (by the users, or from the debugger), the sample requests a WNS Channel URI and
        // displays it, then waits for notifications. This user can take a copy of the WNS Channel URI and use it to send
        // notifications to the sample
        case ExtendedActivationKind::Launch:
        {
            // Checks to see if push notifications are supported. Certain self-contained apps may not support push notifications by design
            if (PushNotificationManager::IsSupported())
            {
                // Request a WNS Channel URI which can be passed off to an external app to send notifications to.
                // The WNS Channel URI uniquely identifies this app for this user and device.
                PushNotificationChannel channel{ RequestChannel() };
                if (!channel)
                {
                    std::cout << "\nThere was an error obtaining the WNS Channel URI" << std::endl;
    
                    if (remoteId == winrt::guid { "00000000-0000-0000-0000-000000000000" })
                    {
                        std::cout << "\nThe ObjectID has not been set. Refer to the readme file accompanying this sample\nfor the instructions on how to obtain and setup an ObjectID" << std::endl;
                    }
                }
    
                std::cout << "\nPress 'Enter' at any time to exit App." << std::endl;
                std::cin.ignore();
            }
            else
            {
                // App implements its own custom socket here to receive messages from the cloud since Push APIs are unsupported.
            }
        }
        break;

        // When it is activated from a push notification, the sample only displays the notification.
        // It doesn’t register for foreground activation of perform any other actions
        // because background activation is meant to let app perform only small tasks in order to preserve battery life.
        case ExtendedActivationKind::Push:
        {
            PushNotificationReceivedEventArgs pushArgs{ args.Data().as<PushNotificationReceivedEventArgs>() };

            // Call GetDeferral to ensure that code runs in low power
            auto deferral{ pushArgs.GetDeferral() };

            auto payload{ pushArgs.Payload() } ;

            // Do stuff to process the raw notification payload
            std::string payloadString(payload.begin(), payload.end());
            std::cout << "\nPush notification content received in the BACKGROUND: " << payloadString.c_str() << std::endl;
            std::cout << "\nPress 'Enter' to exit the App." << std::endl;

            // Call Complete on the deferral when finished processing the payload.
            // This removes the override that kept the app running even when the system was in a low power mode.
            deferral.Complete();
            std::cin.ignore();
        }
        break;

        default:
            std::cout << "\nUnexpected activation type" << std::endl;
            std::cout << "\nPress 'Enter' to exit the App." << std::endl;
            std::cin.ignore();
            break;
    }

    // We do not call PushNotificationManager::UnregisterActivator
    // because then we wouldn't be able to receive background activations, once the app has closed.
    // Call UnregisterActivator once you don't want to receive push notifications anymore.
}

Schritt 4: Anfordern einer WNS-Kanal-URI und Registrieren beim WNS-Server

WNS-Kanal-URIs sind die HTTP-Endpunkte zum Senden von Pushbenachrichtigungen. Jeder Client muss einen Kanal-URI anfordern und mit dem WNS-Server registrieren, um Pushbenachrichtigungen zu empfangen.

Hinweis

WNS-Kanal-URIs laufen nach 30 Tagen ab.

auto channelOperation{ PushNotificationManager::Default().CreateChannelAsync(winrt::guid("[Your app's Azure ObjectID]")) };

Der PushNotificationManager- versucht, einen Kanal-URI zu erstellen, der automatisch für maximal 15 Minuten wiederholt wird. ** Erstellen Sie einen Ereignishandler, um zu warten, bis der Aufruf abgeschlossen ist. Sobald der Aufruf abgeschlossen ist, registrieren Sie den URI bei dem WNS-Server, falls er erfolgreich war.

// cpp-console.cpp

winrt::Windows::Foundation::IAsyncOperation<PushNotificationChannel> RequestChannelAsync()
{
    // To obtain an AAD RemoteIdentifier for your app,
    // follow the instructions on https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
    auto channelOperation = PushNotificationManager::Default().CreateChannelAsync(remoteId);

    // Setup the inprogress event handler
    channelOperation.Progress(
        [](auto&& sender, auto&& args)
        {
            if (args.status == PushNotificationChannelStatus::InProgress)
            {
                // This is basically a noop since it isn't really an error state
                std::cout << "Channel request is in progress." << std::endl << std::endl;
            }
            else if (args.status == PushNotificationChannelStatus::InProgressRetry)
            {
                LOG_HR_MSG(
                    args.extendedError,
                    "The channel request is in back-off retry mode because of a retryable error! Expect delays in acquiring it. RetryCount = %d",
                    args.retryCount);
            }
        });

    auto result = co_await channelOperation;

    if (result.Status() == PushNotificationChannelStatus::CompletedSuccess)
    {
        auto channelUri = result.Channel().Uri();

        std::cout << "channelUri: " << winrt::to_string(channelUri.ToString()) << std::endl << std::endl;

        auto channelExpiry = result.Channel().ExpirationTime();

        // Caller's responsibility to keep the channel alive
        co_return result.Channel();
    }
    else if (result.Status() == PushNotificationChannelStatus::CompletedFailure)
    {
        LOG_HR_MSG(result.ExtendedError(), "We hit a critical non-retryable error with channel request!");
        co_return nullptr;
    }
    else
    {
        LOG_HR_MSG(result.ExtendedError(), "Some other failure occurred.");
        co_return nullptr;
    }

};

PushNotificationChannel RequestChannel()
{
    auto task = RequestChannelAsync();
    if (task.wait_for(std::chrono::seconds(300)) != AsyncStatus::Completed)
    {
        task.Cancel();
        return nullptr;
    }

    auto result = task.GetResults();
    return result;
}

Schritt 5: Erstellen und Installieren Ihrer App

Verwenden Sie Visual Studio, um Ihre App zu erstellen und zu installieren. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Lösungsdatei, und wählen Sie Bereitstellenaus. Visual Studio erstellt Ihre App und installiert sie auf Ihrem Computer. Sie können die App ausführen, indem Sie sie über das Startmenü oder den Visual Studio-Debugger starten.

Senden einer Pushbenachrichtigung an Ihre App

An diesem Punkt ist die gesamte Konfiguration abgeschlossen, und der WNS-Server kann Pushbenachrichtigungen an Client-Apps senden. In den folgenden Schritten finden Sie unter den Anforderungs- und Antwortheader des Pushbenachrichtigungsservers ausführlicher.

Schritt 1: Anfordern eines Zugriffstokens

Zum Senden einer Pushbenachrichtigung muss der WNS-Server zuerst ein Zugriffstoken anfordern. Senden Sie eine HTTP POST-Anforderung mit Ihrer Azure TenantId, Azure AppId und ihrem geheimen Schlüssel. Informationen zum Abrufen der Azure TenantId und Azure AppId finden Sie unter Abrufen von Mandanten- und App-ID-Werten für die Anmeldung in.

HTTP-Beispielanforderung:

POST /{tenantID}/oauth2/v2.0/token Http/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 160

grant_type=client_credentials&client_id=<Azure_App_Registration_AppId_Here>&client_secret=<Azure_App_Registration_Secret_Here>&scope=https://wns.windows.com/.default/

C#-Beispielanforderung:

//Sample C# Access token request
var client = new RestClient("https://login.microsoftonline.com/{tenantID}/oauth2/v2.0");
var request = new RestRequest("/token", Method.Post);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("grant_type", "client_credentials");
request.AddParameter("client_id", "[Your app's Azure AppId]");
request.AddParameter("client_secret", "[Your app's secret]");
request.AddParameter("scope", "https://wns.windows.com/.default");
RestResponse response = await client.ExecutePostAsync(request);
Console.WriteLine(response.Content);

Wenn Ihre Anforderung erfolgreich ist, erhalten Sie eine Antwort, die Ihr Token im Feld access_token enthält.

{
    "token_type":"Bearer",
    "expires_in":"86399",
    "ext_expires_in":"86399",
    "expires_on":"1653771789",
    "not_before":"1653685089",
    "access_token":"[your access token]"
}

Schritt 2. Senden einer unformatierten Benachrichtigung

Erstellen Sie eine HTTP POST-Anforderung, die das Zugriffstoken enthält, das Sie im vorherigen Schritt abgerufen haben, und den Inhalt der Pushbenachrichtigung, die Sie senden möchten. Der Inhalt der Pushbenachrichtigung wird an die App übermittelt.

POST /?token=[The token query string parameter from your channel URL. E.g. AwYAAABa5cJ3...] HTTP/1.1
Host: dm3p.notify.windows.com
Content-Type: application/octet-stream
X-WNS-Type: wns/raw
Authorization: Bearer [your access token]
Content-Length: 46

{ Sync: "Hello from the Contoso App Service" }

var client = new RestClient("[Your channel URL. E.g. https://wns2-by3p.notify.windows.com/?token=AwYAAABa5cJ3...]");
var request = new RestRequest();
request.Method = Method.Post; 
request.AddHeader("Content-Type", "application/octet-stream");
request.AddHeader("X-WNS-Type", "wns/raw");
request.AddHeader("Authorization", "Bearer [your access token]");
request.AddBody("Notification body");
RestResponse response = await client.ExecutePostAsync(request);");

Schritt 3: Senden einer cloudbasierten App-Benachrichtigung

Wenn Sie nur unformatierte Benachrichtigungen senden möchten, ignorieren Sie diesen Schritt. Zum Senden einer Benachrichtigung über eine Cloud-Quell-App, auch als Push-Popupbenachrichtigung bekannt, folgen Sie zuerst Schnellstart: App-Benachrichtigungen im Windows App SDK. App-Benachrichtigungen können entweder per Push (aus der Cloud gesendet) oder lokal gesendet werden. Das Senden einer cloudbasierten App-Benachrichtigung ähnelt dem Senden einer unformatierten Benachrichtigung in Schritt 2, außer dass der X-WNS-Type-Header ist toast, der Content-Type ist text/xmlund der Inhalt die XML-Nutzlast der App-Benachrichtigung enthält. Weitere Informationen zum Erstellen Ihrer XML-Nutzlast finden Sie im Benachrichtigungs-XML-Schema.

Erstellen Sie eine HTTP POST-Anforderung, die Ihr Zugriffstoken und den Inhalt der cloudbasierten App-Benachrichtigung enthält, die Sie senden möchten. Der Inhalt der Pushbenachrichtigung wird an die App übermittelt.

POST /?token=AwYAAAB%2fQAhYEiAESPobjHzQcwGCTjHu%2f%2fP3CCNDcyfyvgbK5xD3kztniW%2bjba1b3aSSun58SA326GMxuzZooJYwtpgzL9AusPDES2alyQ8CHvW94cO5VuxxLDVzrSzdO1ZVgm%2bNSB9BAzOASvHqkMHQhsDy HTTP/1.1
Host: dm3p.notify.windows.com
Content-Type: text/xml
X-WNS-Type: wns/toast
Authorization: Bearer [your access token]
Content-Length: 180

<toast><visual><binding template="ToastGeneric"><text>Example cloud toast notification</text><text>This is an example cloud notification using XML</text></binding></visual></toast>

var client = new RestClient("https://dm3p.notify.windows.com/?token=AwYAAAB%2fQAhYEiAESPobjHzQcwGCTjHu%2f%2fP3CCNDcyfyvgbK5xD3kztniW%2bjba1b3aSSun58SA326GMxuzZooJYwtpgzL9AusPDES2alyQ8CHvW94cO5VuxxLDVzrSzdO1ZVgm%2bNSB9BAzOASvHqkMHQhsDy");
client.Timeout = -1;

var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "text/xml");
request.AddHeader("X-WNS-Type", "wns/toast");
request.AddHeader("Authorization", "Bearer <AccessToken>");
request.AddParameter("text/xml", "<toast><visual><binding template=\"ToastGeneric\"><text>Example cloud toast notification</text><text>This is an example cloud notification using XML</text></binding></visual></toast>",  ParameterType.RequestBody);
Console.WriteLine(response.Content);

Ressourcen