Partager via

Démarrage rapide : Notifications Push dans le Kit de développement logiciel (SDK) d’application Windows

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

Prerequisites

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 le Kit de développement logiciel (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 avec votre version préférée du Kit de développement logiciel (SDK) de l’application Windows pour obtenir les exemples qui correspondent le mieux à votre projet.

exemple de code d’application

Vous pouvez également trouver des exemples pour chaque version du Kit de développement logiciel (SDK) d’application Windows en sélectionnant une branche de version dans le référentiel d’exemples.

Référence d’API

Pour obtenir la documentation de référence API pour les notifications push, consultez l'espace de noms Microsoft.Windows.PushNotifications.

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

Les notifications Push dans le Kit de développement logiciel (SDK) d’application Windows utilisent des identités à partir d’Azure Active Directory (AAD). Les informations d’identification Azure sont requises lors de la demande d’un URI de canal WNS et lors de la demande de jetons d’accès afin d’envoyer des notifications Push. Remarque: nous ne prenons PAS en charge les notifications push du kit de développement logiciel (SDK) d’application Windows avec l’Espace partenaires Microsoft.

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

Connectez-vous à votre compte Azure et créez une ressource d’inscription d’application AAD . 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 d’application (client), car il s’agit de votre Id d’application Azure 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 Azure TenantId que vous utiliserez lors de la demande d’un jeton d’accès.

    Important

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

  6. Notez votre ID d’objet, car il s’agit de votre Id d’objet Azure 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 :

    Capture d’écran montrant l’option d’application gérée dans le répertoire local sur la page Essentials

    Capture d’écran montrant le champ ID d’objet

    Note

    Un principal de service est requis 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 :

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

    Utiliser Azure PowerShell pour créer un principal du 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.

Secret d’application AAD

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

Important

Veillez à copier votre secret une fois créé et à le stocker dans un emplacement sûr, comme Azure Key Vault. Il ne sera visible qu’une seule fois après la création.

Étape 4 : Mapper le nom de la famille de packages de votre application à son Id d’application 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 package (PFN) de votre application et son AppId Azure.

Si votre application est une application Win32 empaquetée, créez une demande de mappage de nom de famille de package (PFN) en envoyant un e-mail Win_App_SDK_Push@microsoft.com avec la ligne d’objet « Demande de mappage de notifications Push du SDK Windows App » et le corps « PFN : [votre PFN] », AppId : [votre APPId], ObjectId : [votre 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 Id d’application Azure, ObjectId et votre 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 le Kit de développement logiciel (SDK) d’application Windows et les packages NuGet requis

Ensuite, cliquez avec le bouton droit sur la solution dans l’Explorateur de solutions, puis sélectionnez Gérer les packages NuGet.

Dans le Gestionnaire de packages, 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)

S’il s’agit de la première fois que vous utilisez le Kit de développement logiciel (SDK) d’application Windows dans votre projet et qu’il est empaqueté avec un emplacement externe ou non empaqueté, initialisez le Kit de développement logiciel (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 de démarrage. Pour plus d’informations, consultez Utiliser le runtime du Kit de développement logiciel (SDK) d’application Windows pour les applications empaquetées avec un emplacement externe ou non empaquetées .

Note

Si le Kit de développement logiciel (SDK) n’est pas initialisé, l’application lève System.Runtime.InteropServices.COMException (0x80040154): Class not registered (0x80040154 (REGDB_E_CLASSNOTREG)) et ne s’exécute pas.

Étape 2 : Ajouter des espaces de noms

Ensuite, ajoutez l’espace de noms pour les notifications Microsoft.Windows.PushNotificationsPush du Kit de développement logiciel (SDK) d’application Windows.

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

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

Si vous obtenez une erreur « 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 build réussie, supprimez les marques de commentaire sur les instructions include et using et régénérez le projet. Cela doit résoudre l’erreur.

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

Important

Si votre application n’est pas empaquetée (autrement dit, elle n’a pas d’identité de package lors de l’exécution), passez à l’étape 4 : Inscrivez-vous et répondez aux notifications Push au démarrage de l’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>

Note

Vous trouverez un exemple de la classe C++ terminée pour cet exemple après l’étape 5. Les étapes 4 et 5 fournissent des instructions pas à pas pour ajouter chaque élément dans l’exemple final.

É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.

Important

Vous devez appeler PushNotificationManager::Default().Enregistrer avant d’appeler AppInstance.GetCurrent.GetActivatedEventArgs.

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

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

Important

Vous devez également inscrire tous les gestionnaires d’événements PushNotificationManager.PushReceived avant d’appeler PushNotificationManager.Register(). Sinon, l’exception d’exécution suivante est levée :

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 l’interrogation ou votre propre implémentation de socket personnalisé.

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.

Note

Les URI de canal WNS expirent après 30 jours.

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

Si vous suivez le code du tutoriel, ajoutez votre ID d’objet Azure ici :

// To obtain an AAD RemoteIdentifier for your app,
// follow the instructions on https://learn.microsoft.com/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://learn.microsoft.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;
    }
}

É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 l’Explorateur de solutions, puis sélectionnez Déployer. Visual Studio génère votre application et l’installe 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 didacticiel se présente comme suit :

exemple de console de travail

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 du locataire Azure, votre ID de l'application Azure, et votre clé secrète. Pour plus d’informations sur la récupération de l’ID de locataire Azure et de l’ID d’app Azure, consultez Obtenez les valeurs d’ID de locataire et d’application pour se connecter.

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 provenant du cloud, également connue sous le nom de notification toast push, suivez d'abord Démarrage rapide : Notifications d'application dans le Kit de développement logiciel (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

  • Last updated on