Szybkie rozpoczęcie: powiadomienia push w Zestaw SDK do aplikacji systemu Windows

W tym przewodniku szybkiego startu utworzysz aplikację Windows, która wysyła i odbiera powiadomienia push przy użyciu Zestaw SDK do aplikacji systemu Windows.

Prerequisites

• Start tworzenie aplikacji Windows
• Utwórz nowy projekt używający Zestaw SDK do aplikacji systemu Windows OR Użyj Zestaw SDK do aplikacji systemu Windows w istniejącym projekcie
• Aby korzystać z powiadomień wypychanych Zestaw SDK do aplikacji systemu Windows, wymagane jest konto Azure.
• Przeczytaj Omówienie powiadomień push

Wymagania dotyczące pakowania

Powiadomienia push w Zestaw SDK do aplikacji systemu Windows obsługują zarówno spakowane, jak i rozpakowane aplikacje desktopowe. Jednak tożsamość pakietu jest wymagana w przypadku dostarczania w trybie tle i aktywacji COM — najbardziej typowego scenariusza produkcyjnego. W poniższej tabeli podsumowano, co jest wymagane na podstawie modelu pakowania:

Przykładowa aplikacja

Ten Szybki start przeprowadzi Cię przez proces dodawania obsługi powiadomień push do aplikacji w wersji Zestaw SDK do aplikacji systemu Windows 1.7. Zobacz podobny kod do tego szybkiego startu w przykładowych aplikacjach znajdujących się na GitHub. Upewnij się, że sprawdzisz branch z preferowaną wersją Zestaw SDK do aplikacji systemu Windows dla przykładów, które najlepiej pasują do twojego projektu.

Przykłady dla każdej wersji Zestaw SDK do aplikacji systemu Windows można również znaleźć, wybierając gałąź wersji w repozytorium przykładów.

Odniesienie do API

Aby uzyskać dokumentację referencyjną API dotyczącą powiadomień wypychanych, zobacz Microsoft.Windows.PushNotifications Namespace.

Konfigurowanie tożsamości aplikacji w usłudze Azure Active Directory (AAD)

Powiadomienia wypychane w usłudze Zestaw SDK do aplikacji systemu Windows używają tożsamości z Azure Active Directory (AAD). Aby żądać identyfikatora URI kanału WNS i tokenów dostępu oraz wysyłać powiadomienia wypychane, wymagane są poświadczenia Azure. Uwaga: Nie obsługujemy powiadomień push Zestaw SDK do aplikacji systemu Windows z Microsoft Partner Center.

Krok 1. Tworzenie rejestracji aplikacji usługi AAD

Zaloguj się do swojego konta Azure i utwórz nowy zasób Rejestracja Aplikacji AAD. Wybierz opcję Nowa rejestracja.

Krok 2: Podaj nazwę i wybierz opcję wielu dzierżawców.

1. Podaj nazwę aplikacji.

2. Powiadomienia push wymagają opcji multi-tenant, więc wybierz tę funkcję.

   1. Aby uzyskać więcej informacji na temat dzierżawców, zobacz Kto może zalogować się do aplikacji?.

3. Wybierz pozycję Zarejestruj

4. Zanotuj identyfikator Application (klienta), ponieważ jest to Azure AppId którego będziesz używać podczas rejestracji aktywacji i żądania tokenu dostępu.

5. Zanotuj swój identyfikator Directory (dzierżawy), ponieważ jest to twój identyfikator Azure TenantId, który będziesz używać podczas żądania tokenu dostępu.

   Important

   Zanotuj swój identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawcy) .

6. Zanotuj identyfikator Object ponieważ jest to identyfikator Azure ObjectId którego będziesz używać podczas żądania kanału. Należy pamiętać, że nie jest to identyfikator obiektu wymieniony na stronie Podstawy . Zamiast tego, aby znaleźć prawidłowy identyfikator obiektu, kliknij nazwę aplikacji w polu aplikacji zarządzanej w katalogu lokalnym na stronie Essentials:

   

   

   Note

   Aby uzyskać identyfikator obiektu, wymagany jest główny obiekt usługi. Jeśli nie jest on skojarzony z Twoją aplikacją, wykonaj kroki opisane w jednym z poniższych artykułów, aby go utworzyć w portalu Azure lub za pomocą wiersza polecenia.

   Użyj portalu, aby utworzyć aplikację Azure AD i główną jednostkę usługi, która może uzyskiwać dostęp do zasobów

   Użyj Azure PowerShell, aby utworzyć głównego obiektu usługi przy użyciu certyfikatu

Krok 3. Tworzenie wpisu tajnego na potrzeby rejestracji aplikacji

Klucz tajny będzie używany razem z Azure AppId/ClientId podczas żądania tokenu dostępu do wysyłania powiadomień push.

Przejdź do pozycji Certyfikaty i wpisy tajne , a następnie wybierz pozycję Nowy klucz tajny klienta.

Krok 4. Mapuj swoją nazwę rodziny pakietów aplikacji na Azure AppId

Jeśli Twoja aplikacja jest spakowana (w tym z lokalizacją zewnętrzną), możesz użyć tego procesu do mapowania nazwy rodziny pakietów aplikacji (PFN) i jej Azure AppId.

Jeśli Twoja aplikacja to pakietowa aplikacja Win32, stwórz żądanie mapowania Nazwy Rodziny Pakietów (PFN), wysyłając wiadomość e-mail na adres Win_App_SDK_Push@microsoft.com z tematem "Żądanie mapowania powiadomień push Zestaw SDK do aplikacji systemu Windows" i treścią "PFN: [twój PFN], AppId: [twój APPId], IdObiektu: [twój IdObiektu]." Żądania mapowania są wykonywane co tydzień. Po zakończeniu żądania mapowania otrzymasz powiadomienie.

Kiedy masz już swój Azure AppId, ObjectId i tajne hasło, możesz dodać te poświadczenia do poniższego przykładowego kodu.

Skonfiguruj swoją aplikację, aby odbierać powiadomienia push

Krok 1. Dodawanie Zestaw SDK do aplikacji systemu Windows i wymaganych pakietów NuGet

Następnie kliknij prawym przyciskiem myszy rozwiązanie w Eksplorator rozwiązań i wybierz pozycję Zarządzaj pakietami NuGet.

W Menedżer pakietów dodaj następujące pakiety:

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

Jeśli po raz pierwszy używasz Zestaw SDK do aplikacji systemu Windows w projekcie i jest on spakowany z lokalizacją zewnętrzną lub rozpakowany, zainicjuj Zestaw SDK do aplikacji systemu Windows, dodając następującą właściwość do pliku projektu:

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

lub użyj interfejsu API programu inicjującego. Aby uzyskać więcej informacji, zobacz Używanie środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows dla aplikacji pakowanych z zewnętrznym źródłem lub niepakowanych.

Krok 2: Dodaj przestrzenie nazw

Następnie dodaj przestrzeń nazw dla powiadomień push Zestaw SDK do aplikacji systemu Windows Microsoft.Windows.PushNotifications.

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

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

Jeśli zostanie wyświetlony komunikat "Nie można znaleźć Microsoft.Windows.PushNotifications", prawdopodobnie oznacza to, że pliki nagłówkowe nie zostały wygenerowane. Aby rozwiązać ten problem, upewnij się, że masz zainstalowane powyżej pakiety, oznacz jako komentarz instrukcje include i using powodujące błąd, a następnie ponownie skompiluj aplikację, aby wygenerować pliki nagłówka. Po pomyślnym zakończeniu kompilacji usuń komentarz z instrukcji include i using i skompiluj projekt. Powinno to usunąć błąd.

Krok 3. Dodawanie aktywatora COM do manifestu aplikacji

Jeśli aplikacja jest spakowana (w tym spakowana z lokalizacją zewnętrzną): otwórz Package.appxmanifest. Dodaj następujący element w elemecie <Application> . Zastąp Idwartości , Executablei DisplayName tymi specyficznymi dla aplikacji.

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

Krok 4: Zarejestruj się do odbierania i reaguj na powiadomienia push podczas uruchamiania aplikacji.

Zaktualizuj metodę aplikacji main() , aby dodać następujące elementy:

1. Zarejestruj aplikację, aby otrzymywać powiadomienia push, wywołując PushNotificationManager::Default().Register().
2. Sprawdź źródło żądania aktywacji, wywołując metodę AppInstance::GetCurrent(). GetActivatedEventArgs(). Jeśli aktywacja została wyzwolona z powiadomienia push, odpowiedz biorąc pod uwagę ładunek powiadomienia.

Dodawanie procedur obsługi zdarzeń pierwszego planu

Aby obsłużyć zdarzenie na pierwszym planie, zarejestruj procedurę obsługi elementu PushNotificationManager.PushReceived.

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

Dodaj sprawdzanie metody PushNotificationManager::IsSupported()

Następnie dodaj sprawdzenie, czy interfejsy API PushNotification są obsługiwane za pomocą PushNotificationManager.IsSupported(). Jeśli nie, zalecamy użycie sondowania lub własnej implementacji gniazd niestandardowych.

Teraz, gdy potwierdzono obsługę powiadomień wypychanych, dodaj zachowanie w oparciu o PushNotificationReceivedEventArgs.

Krok 5. Żądanie identyfikatora URI kanału usługi WNS i zarejestrowanie go na serwerze WNS

Identyfikatory URI kanału WNS to punkty końcowe HTTP do wysyłania powiadomień push. Każdy użytkownik musi zażądać identyfikatora URI kanału i zarejestrować go na serwerze WNS, aby otrzymywać powiadomienia push.

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

Jeśli używasz kodu samouczka, dodaj identyfikator obiektu Azure tutaj:

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

PushNotificationManager podejmie próbę utworzenia URI kanału, automatycznie ponawiając próbę przez nie więcej niż 15 minut. Utwórz procedurę obsługi zdarzeń, aby poczekać na zakończenie wywołania. Po zakończeniu wywołania, jeśli przebiegło pomyślnie, zarejestruj identyfikator URI na serwerze WNS.

Przykładowy kod

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

Krok 6. Kompilowanie i instalowanie aplikacji

Użyj Visual Studio, aby skompilować i zainstalować aplikację. Kliknij prawym przyciskiem myszy plik rozwiązania w Eksplorator rozwiązań i wybierz pozycję Deploy. Visual Studio skompiluje aplikację i zainstaluje ją na maszynie. Aplikację można uruchomić, uruchamiając ją za pomocą menu Start lub debugera Visual Studio.

Konsola kodu samouczka będzie wyglądać następująco:

Token będzie potrzebny do wysłania powiadomienia push do aplikacji.

Wyślij powiadomienie push do swojej aplikacji

Na tym etapie cała konfiguracja jest ukończona, a serwer WNS może wysyłać powiadomienia push do aplikacji klienckich. W poniższych krokach zapoznaj się z nagłówkami żądania i odpowiedzi serwera powiadomień push, aby uzyskać więcej szczegółów.

Krok 1. Żądanie tokenu dostępu

Aby wysłać powiadomienie push, serwer WNS musi najpierw zażądać tokenu dostępu. Wyślij żądanie HTTP POST z identyfikatorem Azure TenantId, Azure AppId i tajnym kluczem. Aby uzyskać informacje na temat pobierania identyfikatorów Azure TenantId i Azure AppId, zobacz Pobierz wartości identyfikatorów dzierżawy i aplikacji na potrzeby logowania.

Przykładowe żądanie 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/

Przykładowe żądanie języka 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);

Jeśli żądanie zakończy się pomyślnie, otrzymasz odpowiedź zawierającą token w polu access_token .

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

Krok 2. Wysyłanie nieprzetworzonego powiadomienia

Utwórz żądanie HTTP POST zawierające token dostępu uzyskany w poprzednim kroku oraz zawartość powiadomienia wypychanego, które chcesz wysłać. Zawartość powiadomienia push zostanie dostarczona do aplikacji.

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

Krok 3. Wysyłanie powiadomienia aplikacji opartej na chmurze

Jeśli interesuje Cię tylko wysyłanie nieprzetworzonych powiadomień, zignoruj ten krok. Aby wysłać powiadomienie aplikacji z chmury, zwane także powiadomieniem push, najpierw postępuj zgodnie z Quickstart: Powiadomienia aplikacji w Zestaw SDK do aplikacji systemu Windows. Powiadomienia aplikacji mogą być powiadomieniami push (wysyłane z chmury) lub wysyłane lokalnie. Wysyłanie powiadomienia aplikacji opartej na chmurze jest podobne do wysyłania nieprzetworzonego powiadomienia w kroku 2, z wyjątkiem sytuacji, gdy nagłówek X-WNS-Type jest toast, typ zawartości Content-Type jest text/xml, a zawartość zawiera ładunek XML powiadomienia aplikacji. Aby uzyskać więcej informacji na temat konstruowania ładunku XML, zobacz Schemat XML powiadomień .

Utwórz żądanie HTTP POST zawierające token dostępu i zawartość powiadomienia aplikacji źródłowej w chmurze, które chcesz wysłać. Zawartość powiadomienia push zostanie dostarczona do aplikacji.

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)
• przykładowy kod powiadomień Push w witrynie GitHub
• Microsoft.Windows PushNotifications: Szczegóły interfejsu API
• Powiadomienia Push w specyfikacji na GitHubie
• Zawartość toastu
• schemat XML powiadomień