Quickstart: Pushmeldingen in de Windows App SDK

In deze quickstart maakt u een bureaublad-Windows-toepassing waarmee pushmeldingen worden verzonden en ontvangen met behulp van de Windows App SDK.

Prerequisites

• Start met het ontwikkelen van Windows-apps
• Maak Maak een nieuw project dat gebruikmaakt van het Windows App SDK OF Gebruik de Windows App SDK in een bestaand project
• Een Azure-account is vereist om Windows App SDK pushmeldingen te kunnen gebruiken.
• Overzicht van pushmeldingen lezen

Verpakkingsvereisten

Pushmeldingen in de Windows App SDK ondersteunen zowel verpakte als echt uitgepakte desktop-apps. Pakketidentiteit is echter vereist voor levering op de achtergrond en COM-activering, het meest voorkomende productiescenario. De volgende tabel bevat een overzicht van wat er nodig is op basis van uw verpakkingsmodel:

Voorbeeld-app

In deze quickstart wordt uitgelegd hoe u ondersteuning voor pushmeldingen toevoegt aan uw app op Windows App SDK 1.7. Zie vergelijkbare code als in deze quickstart in de voorbeeld-apps die zijn gevonden op GitHub. Bekijk de branch met de gewenste versie van de Windows App SDK voor de voorbeelden die het beste bij uw project passen.

U kunt ook voorbeelden vinden voor elke versie van Windows App SDK door selecteren van een versievertakking in de opslagplaats met voorbeelden.

API-referentie

Raadpleeg de API-referentiedocumentatie voor pushmeldingen in de Microsoft.Windows.PushNotifications Namespace.

De identiteit van uw app configureren in Azure Active Directory (AAD)

Pushmeldingen in Windows App SDK identiteiten van Azure Active Directory (AAD) gebruiken. Azure referenties zijn vereist bij het aanvragen van een WNS-kanaal-URI en bij het aanvragen van toegangstokens om pushmeldingen te verzenden. Opmerking: Wij ondersteunen het gebruik van Windows App SDK-pushmeldingen met Microsoft Partnercentrum NIET.

Stap 1: Een AAD-app-registratie maken

Meld u aan bij uw Azure-account en maak een nieuwe AAD App Registration resource. Selecteer Nieuwe registratie.

Stap 2: Geef een naam op en selecteer een optie voor meerdere tenants

1. Geef de naam van een app op.

2. Voor pushmeldingen is de optie voor meerdere tenants vereist, dus selecteer dat.

   1. Zie Wie kan zich aanmelden bij uw app voor meer informatie over tenants.

3. Selecteer Registreren

4. Noteer uw Application-id (client)-id, omdat dit uw Azure AppId is die u tijdens de activeringsregistratie en toegangstokenaanvraag gaat gebruiken.

5. Noteer uw Directory-id (tenant)-id, omdat dit uw Azure TenantId is die u gaat gebruiken bij het aanvragen van een toegangstoken.

   Important

   noteer uw toepassings-id (client)-id en directory-id (tenant)-id.

6. Noteer uw Object-id, omdat dit uw Azure ObjectId is die u gaat gebruiken bij het aanvragen van een kanaalaanvraag. Houd er rekening mee dat dit niet de object-id is die wordt vermeld op de pagina Essentials . Als u in plaats daarvan de juiste object-id wilt vinden, klikt u op de naam van de app in de beheerde toepassing in het veld Lokale map op de pagina Essentials :

   

   

   Note

   Een service-principal is vereist om een object-id op te halen, als er geen object-id aan uw app is gekoppeld, volgt u de stappen in een van de volgende artikelen om er een te maken in de Azure-portal of met behulp van de opdrachtregel:

   De portal gebruiken om een Azure AD-toepassing en service-principal te maken die toegang heeft tot resources

   Gebruik Azure PowerShell om een service-principal te maken met een certificaat

Stap 3: Een geheim maken voor uw app-registratie

Uw geheim wordt samen met uw Azure AppId/ClientId gebruikt wanneer u een toegangstoken aanvraagt om pushmeldingen te verzenden.

Navigeer naar Certificaten en geheimen en selecteer Nieuw clientgeheim.

Stap 4: de familienaam van uw app toewijzen aan de bijbehorende Azure AppId

Als uw app verpakt is (ook in een extern pakket), kunt u dit proces gebruiken om de Package Family Name (PFN) en de bijbehorende Azure AppId van uw app toe te wijzen.

Als uw app een verpakte Win32-app is, maakt u een PFN-toewijzingsaanvraag (Package Family Name) door een e-mail te sturen naar Win_App_SDK_Push@microsoft.com met de onderwerpregel 'Windows App SDK Toewijzingsaanvraag voor pushmeldingen' en 'PFN: [uw PFN]', AppId: [uw APPId], ObjectId: [uw ObjectId]. Kaartaanvragen worden wekelijks voltooid. U ontvangt een melding zodra uw koppelingsverzoek is voltooid.

Zodra u uw Azure AppId, ObjectId en clientsleutel hebt, kunt u deze referenties toevoegen aan de voorbeeldcode hieronder.

Uw app configureren voor het ontvangen van pushmeldingen

Stap 1: Voeg Windows App SDK en vereiste NuGet-pakketten toe

Klik vervolgens met de rechtermuisknop op de oplossing in de Solution Explorer en selecteer Manage NuGet-pakketten.

Voeg in de Pakketbeheer de volgende pakketten toe:

• Microsoft. WindowsAppSDK (minimaal versie 1.1.0)
• Microsoft. Windows. SDK. BuildTools (minimaal versie 10.0.22000.194)
• Microsoft. Windows. CppWinRT ( minimaal versie 2.0.210930.14)
• Microsoft. Windows. ImplementationLibrary (minimaal versie 1.0.210930.1)

Als dit de eerste keer is dat u Windows App SDK in uw project gebruikt en het wordt verpakt met een externe locatie of uitgepakt, initialiseert u de Windows App SDK door de volgende eigenschap toe te voegen aan uw projectbestand:

<!-- your .vcxproj or .proj file -->
<PropertyGroup Label="Globals">
    <!-- Other properties -->
    <WindowsPackageType>None</WindowsPackageType>
</PropertyGroup>

of gebruik de bootstrapper-API. Zie Gebruik de Windows App SDK runtime voor apps die zijn verpakt met externe locatie of uitgepakt voor meer informatie.

Stap 2: Naamruimten toevoegen

Voeg vervolgens de naamruimte toe voor Windows App SDK pushmeldingen Microsoft.Windows.PushNotifications.

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

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

Als u de foutmelding "Kan Microsoft.Windows.PushNotifications niet vinden" krijgt, betekent dat waarschijnlijk dat de headerbestanden niet zijn gegenereerd. U kunt dit oplossen door ervoor te zorgen dat de bovenstaande pakketten zijn geïnstalleerd, de insluitings- en gebruiksinstructies commentaar geven die de fout veroorzaken en de toepassing opnieuw opbouwen om de headerbestanden te genereren. Zodra de build is geslaagd, haalt u de opmerkingen weg bij de include- en using-statements en bouwt u het project opnieuw. Hiermee wordt de fout opgelost.

Stap 3: Uw COM-activator toevoegen aan het manifest van uw app

Als uw app is gebundeld (inclusief gebundeld op een externe locatie): Open uw Package.appxmanifest. Voeg het volgende toe in het <Application> element. Vervang de Id, Executableen DisplayName waarden door de waarden die specifiek zijn voor uw app.

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

Stap 4: Registreren voor en reageren op pushmeldingen bij het opstarten van de app

Werk de methode van uw app main() bij om het volgende toe te voegen:

1. Registreer uw app om pushmeldingen te ontvangen door PushNotificationManager::D efault() aan te roepen. Register().
2. Controleer de bron van de activeringsaanvraag door AppInstance::GetCurrent() aan te roepen. GetActivatedEventArgs(). Als de activering is geactiveerd vanuit een pushmelding, reageert u op basis van de nettolading van de melding.

Event handlers op de voorgrond toevoegen

Als u een gebeurtenis op de voorgrond wilt afhandelen, registreert u een handler voor PushNotificationManager.PushReceived.

System.Runtime.InteropServices.COMException: Element not found. Must register event handlers before calling Register().

De pushNotificationManager::IsSupported() controle toevoegen

Voeg vervolgens een controle toe of de PushNotification-API's worden ondersteund met PushNotificationManager.IsSupported(). Zo niet, dan raden we u aan polling of uw eigen aangepaste socket-implementatie te gebruiken.

Nu er ondersteuning voor pushmeldingen is bevestigd, voegt u gedrag toe op basis van PushNotificationReceivedEventArgs.

Stap 5: een WNS-kanaal-URI aanvragen en registreren bij de WNS-server

WNS-kanaal-URI's zijn de HTTP-eindpunten voor het verzenden van pushmeldingen. Elke client moet een kanaal-URI aanvragen en deze registreren bij de WNS-server om pushmeldingen te ontvangen.

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

Als u de zelfstudiecode volgt, voegt u hier uw Azure object-id toe:

// To obtain an AAD RemoteIdentifier for your app,
// follow the instructions on https://dori-uw-1.kuma-moon.com/azure/active-directory/develop/quickstart-register-app
winrt::guid remoteId{ "00000000-0000-0000-0000-000000000000" }; // Replace this with your own Azure ObjectId

De PushNotificationManager zal proberen een kanaal-URI te maken en automatisch opnieuw proberen gedurende maximaal 15 minuten. Maak een gebeurtenis-handler om te wachten tot de aanroep is voltooid. Zodra de aanroep is voltooid, registreert u de URI bij de WNS-server als deze is geslaagd.

Voorbeeldcode

#include <iostream>
#include <winrt/Microsoft.Windows.PushNotifications.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Microsoft.Windows.AppLifecycle.h>
#include <winrt/Windows.ApplicationModel.Background.h>
#include <wil/cppwinrt.h>
#include <wil/result.h>

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

// To obtain an AAD RemoteIdentifier for your app,
// follow the instructions on https://dori-uw-1.kuma-moon.com/azure/active-directory/develop/quickstart-register-app
winrt::guid remoteId{ "00000000-0000-0000-0000-000000000000" }; // Replace this with your own Azure ObjectId

winrt::Windows::Foundation::IAsyncOperation<PushNotificationChannel> RequestChannelAsync()
{
    auto channelOperation = PushNotificationManager::Default().CreateChannelAsync(remoteId);

    // Set up the in-progress 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;
}

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

    std::cout << "Push notification foreground event handler registered." << std::endl;
}

int main()
{
    // Set up an event handler, so we can receive notifications in the foreground while the app is running.
    // You must register notification event handlers before calling Register(). Otherwise, the following runtime
    // exception will be thrown: System.Runtime.InteropServices.COMException: 'Element not found. Must register
    // event handlers before calling Register().'
    SubscribeForegroundEventHandler();

    // Register the app for push notifications.
    PushNotificationManager::Default().Register();

    auto args{ AppInstance::GetCurrent().GetActivatedEventArgs() };
    switch (args.Kind())
    {
        case ExtendedActivationKind::Launch:
        {
            std::cout << "App launched by user or from the debugger." << std::endl;
            if (PushNotificationManager::IsSupported())
            {
                std::cout << "Push notifications are supported on this device." << std::endl;

                // 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
            {
                std::cout << "Push notifications are NOT supported on this device." << std::endl;
                std::cout << "App implements its own custom socket here to receive messages from the cloud since Push APIs are unsupported." << std::endl;
                std::cin.ignore();
            }
        }
        break;

        case ExtendedActivationKind::Push:
        {
            std::cout << "App activated via push notification." << std::endl;
            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;
    }
}

Stap 6: uw app bouwen en installeren

Gebruik Visual Studio om uw app te bouwen en te installeren. Klik met de rechtermuisknop op het oplossingsbestand in de Solution Explorer en selecteer Deploy. Visual Studio bouwt uw app en installeert deze op uw computer. U kunt de app uitvoeren door deze te starten via het startmenu of het Visual Studio foutopsporingsprogramma.

De console van de zelfstudiecode ziet er als volgt uit:

U hebt het token nodig om een pushmelding naar uw app te verzenden.

Een pushmelding verzenden naar uw app

Op dit moment is alle configuratie voltooid en kan de WNS-server pushmeldingen verzenden naar client-apps. Raadpleeg in de volgende stappen de aanvraag- en antwoordheaders van de pushmeldingsserver en voor meer gedetailleerde informatie.

Stap 1: Een toegangstoken aanvragen

Als u een pushmelding wilt verzenden, moet de WNS-server eerst een toegangstoken aanvragen. Verzend een HTTP POST-aanvraag met uw Azure TenantId, Azure AppId en geheim. Zie Get tenant and app ID values for signing in voor meer informatie over het ophalen van de Azure TenantId en de Azure AppId.

HTTP-voorbeeldaanvraag:

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#-voorbeeldaanvraag:

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

Als uw aanvraag is geslaagd, ontvangt u een antwoord dat uw token bevat in het veld access_token .

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

Stap 2. Een onbewerkte melding verzenden

Maak een HTTP POST-aanvraag die het toegangstoken bevat dat u in de vorige stap hebt verkregen en de inhoud van de pushmelding die u wilt verzenden. De inhoud van de pushmelding wordt aan de app geleverd.

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

Stap 3: Een app-melding in de cloud verzenden

Als u alleen onbewerkte meldingen wilt verzenden, negeert u deze stap. Volg eerst Quickstart: App-meldingen in de Windows App SDK om een app-melding in de cloud te verzenden, ook wel een push-toastmelding genoemd. App-meldingen kunnen worden gepusht (verzonden vanuit de cloud) of lokaal worden verzonden. Het verzenden van een app-melding in de cloud is vergelijkbaar met het verzenden van een onbewerkte melding in stap 2, met uitzondering van de X-WNS-type header is toast, inhoudstype is text/xmlen de inhoud bevat de XML-nettolading voor app-meldingen. Zie XML-schema voor meldingen voor meer informatie over hoe u uw XML-payload kunt maken.

Maak een HTTP POST-aanvraag die uw toegangstoken bevat en de inhoud van de app-melding in de cloud die u wilt verzenden. De inhoud van de pushmelding wordt aan de app geleverd.

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

Resources

• Windows Push Notification Service (WNS)
• voorbeeldcode voor Pushmeldingen op GitHub
• Microsoft.Windows.PushNotifications API details
• Pushmeldingenspecificatie op GitHub
• Meldinginhoud
• XML-schema voor meldingen