Démarrage rapide : Notifications Push dans le SDK d'application Windows

Dans ce guide de démarrage rapide, vous allez créer une application de bureau Windows qui envoie et reçoit des notifications Push à l’aide du SDK d'application Windows.

Prerequisites

• Commencez à développer des applications Windows
• Soit Créer un nouveau projet qui utilise le SDK d'application Windows OR Utiliser le SDK d'application Windows dans un projet existant
• Un compte Azure est nécessaire pour utiliser SDK d'application Windows notifications Push.
• Lire Aperçu des Notifications Push

Configuration requise pour l’empaquetage

Les notifications Push dans le SDK d'application Windows prennent en charge les applications de bureau empaquetées et réellement non empaquetées. Toutefois, l’identité de package est requise pour l’exécution en arrière-plan et l’activation COM, le scénario de production le plus courant. Le tableau suivant récapitule ce qui est requis en fonction de votre modèle d’empaquetage :

Exemple d’application

Ce guide de démarrage rapide vous guide tout au long de l’ajout de la prise en charge des notifications Push à votre application sur SDK d'application Windows 1.7. Consultez le code similaire à ce guide de démarrage rapide dans les exemples d’applications trouvés sur GitHub. Veillez à consulter la branche contenant votre version préférée de SDK d'application Windows pour les exemples les mieux adaptés à votre projet.

Vous trouverez également des exemples pour chaque version de SDK d'application Windows en élection d’une branche de version dans le référentiel d’exemples.

Référence d’API

Pour obtenir la documentation de référence sur les API pour les notifications push, consultez Microsoft.Windows.PushNotifications Namespace.

Configurer l'identité de votre application dans Azure Active Directory (AAD)

Les notifications Push dans SDK d'application Windows utilisent des identités à partir de Azure Active Directory (AAD). Les informations d'identification Azure sont requises lors de la demande d’un URI de canal de notifications WNS et lors de la demande de jetons d’accès pour envoyer des notifications push. Note : Nous ne prenons PAS en charge l’utilisation des notifications Push du SDK d'applications Windows avec Microsoft Partner Center.

Étape 1 : Créer une inscription d’application AAD

Connectez-vous à votre compte Azure et créez une ressource AAD App Registration. Sélectionnez Nouvelle inscription.

Étape 2 : Fournir un nom et sélectionner une option multi-locataire

1. Fournissez un nom d’application.

2. Les notifications Push nécessitent l’option multilocataire. Veuillez la sélectionner.

   1. Pour plus d’informations sur les locataires, consultez Qui peut se connecter à votre application ?.

3. Sélectionnez Inscrire

4. Notez votre ID Application (client, car il s’agit de votre id d’application Azure AppId que vous utiliserez lors de l’inscription de l’activation et de la demande de jeton d’accès.

5. Notez votre ID Directory (locataire, car il s’agit de votre id de locataire Azure TenantId que vous utiliserez lors de la demande d’un jeton d’accès.

   Important

   Prenez note de votre ID d’application (client) et de l’ID d’annuaire (locataire).

6. Notez votre ID Object, car il s’agit de votre id d’objet Azure ObjectId que vous utiliserez lors de la demande d’un canal. Notez qu’il ne s’agit pas de l’ID d’objet répertorié dans la page Essentials . Au lieu de cela, pour rechercher l’ID d’objet approprié, cliquez sur le nom de l’application dans le champ de l’application gérée du répertoire local sur la page Essentials :

   

   

   Note

   Un principal service est nécessaire pour obtenir un ID d’objet, s’il n’en existe pas associé à votre application, suivez les étapes de l’un des articles suivants pour en créer un dans le portail Azure ou à l’aide de la ligne de commande :

   Utilisez le portail pour créer une application et un principal de service AD Azure qui peuvent accéder aux ressources

   Utilisez Azure PowerShell pour créer un principal de service avec un certificat

Étape 3 : Créer un secret pour l’inscription de votre application

Votre secret sera utilisé avec votre Azure AppId/ClientId lors de la demande d’un jeton d’accès pour envoyer des notifications Push.

Accédez à Certificats et secrets et sélectionnez Nouveau secret client.

Étape 4 : Mapper le nom de la famille de packages de votre application à son appId Azure

Si votre application est empaquetée (y compris empaquetée avec un emplacement externe), vous pouvez utiliser ce flux pour mapper le nom de famille de packages (PFN) de votre application et son appId Azure.

Si votre application est une application Win32 empaquetée, créez une demande de mappage pfN (Package Family Name) envoyant un e-mail à Win_App_SDK_Push@microsoft.com avec la ligne d’objet « SDK d'application Windows Push Notifications Mapping Request » et body « PFN : [your PFN] », AppId : [your APPId], ObjectId : [your ObjectId]. Les demandes de mappage sont effectuées toutes les semaines. Vous serez averti une fois votre demande de mappage terminée.

Une fois que vous avez votre Azure AppId, ObjectId et secret, vous pouvez ajouter ces informations d’identification à l’exemple de code ci-dessous.

Configurer votre application pour recevoir des notifications Push

Étape 1 : Ajouter des SDK d'application Windows et des packages NuGet requis

Ensuite, cliquez avec le bouton droit sur la solution dans le Explorateur de solutions, puis sélectionnez Manage NuGet Packages.

Dans le Gestionnaire de package, ajoutez les packages suivants :

• Microsoft. WindowsAppSDK (version minimale 1.1.0)
• Microsoft. Windows. SDK. BuildTools (version minimale 10.0.22000.194)
• Microsoft. Windows. CppWinRT, (version minimale 2.0.210930.14)
• Microsoft. Windows. ImplementationLibrary, (version minimale 1.0.210930.1)

Si c’est la première fois que vous utilisez SDK d'application Windows dans votre projet et qu’il est empaqueté avec un emplacement externe ou non empaqueté, initialisez le SDK d'application Windows en ajoutant la propriété suivante à votre fichier projet :

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

ou utilisez l’API bootstrapper. Pour plus d’informations, consultez Utilisez le runtime de SDK d'application Windows pour les applications empaquetées à l’emplacement externe ou non empaquetées.

Étape 2 : Ajouter des espaces de noms

Ensuite, ajoutez l’espace de noms pour les notifications Push de SDK d'application Windows Microsoft.Windows.PushNotifications.

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

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

Si vous obtenez un message « Impossible de trouver Microsoft.Windows.PushNotifications », cela signifie probablement que les fichiers d’en-tête n’ont pas été générés. Pour résoudre ce problème, vérifiez que les packages ci-dessus sont installés, commentez les instructions include et using à l’origine de l’erreur et régénérez l’application pour générer les fichiers d’en-tête. Une fois la compilation réussie, supprimez les commentaires sur les instructions include et using et reconstruisez le projet. Cela doit résoudre l’erreur.

Étape 3 : Ajouter votre activateur COM au manifeste de votre application

Si votre application est empaquetée (y compris empaquetée avec un emplacement externe) : ouvrez votre Package.appxmanifest. Ajoutez ce qui suit à l’intérieur de l’élément <Application> . Remplacez les valeurs Id, Executable et DisplayName par celles spécifiques à votre application.

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

Étape 4 : S’inscrire et répondre aux notifications Push au démarrage de l’application

Mettez à jour la méthode de main() votre application pour ajouter les éléments suivants :

1. Inscrivez votre application pour recevoir des notifications push en appelant PushNotificationManager::Default().Register().
2. Vérifiez la source de la demande d’activation en appelant AppInstance ::GetCurrent(). GetActivatedEventArgs(). Si l’activation a été déclenchée à partir d’une notification Push, répondez en fonction de la charge utile de la notification.

Ajout de gestionnaires d’événements de premier plan

Pour gérer un événement au premier plan, inscrivez un gestionnaire pour PushNotificationManager.PushReceived.

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

Ajouter la vérification PushNotificationManager ::IsSupported()

Ensuite, ajoutez une vérification si les API PushNotification sont prises en charge avec PushNotificationManager.IsSupported(). Si ce n’est pas le cas, nous vous recommandons d’utiliser le sondage ou votre propre implémentation de socket personnalisée.

Maintenant qu’il existe une prise en charge confirmée des notifications Push, ajoutez un comportement basé sur PushNotificationReceivedEventArgs.

Étape 5 : Demander un URI de canal WNS et l’inscrire auprès du serveur WNS

Les URI de canal WNS sont les points de terminaison HTTP pour l’envoi de notifications Push. Chaque client doit demander un URI de canal et l’inscrire auprès du serveur WNS pour recevoir des notifications Push.

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

Si vous suivez le code du didacticiel, ajoutez votre ID d'objet Azure ici :

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

PushNotificationManager tentera de créer un URI de canal, réessayant automatiquement pendant pas plus de 15 minutes. Créez un gestionnaire d’événements pour attendre la fin de l’appel. Une fois l’appel terminé, s’il a réussi, inscrivez l’URI auprès du serveur WNS.

Exemple de code

#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://dotnet.territoriali.olinfo.it/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;
    }
}

Étape 6 : Générer et installer votre application

Utilisez Visual Studio pour générer et installer votre application. Cliquez avec le bouton droit sur le fichier solution dans le Explorateur de solutions, puis sélectionnez Deploy. Visual Studio générerez votre application et l’installerez sur votre ordinateur. Vous pouvez exécuter l’application en la lançant via le menu Démarrer ou le débogueur Visual Studio.

La console du code du tutoriel ressemblera à ceci :

Vous aurez besoin du jeton pour envoyer une notification Push à votre application.

Envoyer une notification Push à votre application

À ce stade, toute la configuration est terminée et le serveur WNS peut envoyer des notifications Push aux applications clientes. Dans les étapes suivantes, reportez-vous aux en-têtes de demande et de réponse du serveur de notification Push pour plus de détails.

Étape 1 : Demander un jeton d’accès

Pour envoyer une notification Push, le serveur WNS doit d’abord demander un jeton d’accès. Envoyez une requête HTTP POST avec votre id de locataire Azure, Azure AppId et secret. Pour plus d’informations sur la récupération de l’ID de locataire Azure et de l’ID d'application Azure, consultez Obtenez les valeurs de locataire et d’ID d'application pour la connexion.

Exemple de requête HTTP :

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/

Exemple de requête C# :

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

Si votre demande réussit, vous recevrez une réponse qui contient votre jeton dans le champ access_token .

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

Étape 2. Envoyer une notification brute

Créez une requête HTTP POST qui contient le jeton d’accès que vous avez obtenu à l’étape précédente et le contenu de la notification Push que vous souhaitez envoyer. Le contenu de la notification Push est remis à l’application.

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

Étape 3 : Envoyer une notification d’application source dans le cloud

Si vous souhaitez uniquement envoyer des notifications brutes, ignorez cette étape. Pour envoyer une notification d’application source dans le cloud, également connue sous le nom de notification push toast, suivez d’abord Quickstart : Notifications d’application dans le SDK d'application Windows. Les notifications d’application peuvent être envoyées (envoyées à partir du cloud) ou envoyées localement. L’envoi d’une notification d’application provenant du cloud est similaire à l’envoi d’une notification brute à l’étape 2, à l’exception de l’en-tête X-WNS-Type est , Content-Type est et le contenu contient la charge utile XML de notification d’application. Consultez schéma XML notifications pour plus d’informations sur la façon de construire votre charge utile XML.

Créez une requête HTTP POST qui contient votre jeton d’accès et le contenu de la notification d’application source dans le cloud que vous souhaitez envoyer. Le contenu de la notification Push est remis à l’application.

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)
• exemple de code pour notifications push sur GitHub
• Microsoft.Windows. Détails de l’API PushNotifications
• spéc des notifications Push sur GitHub
• Contenu toast
• Schéma XML de notifications