Início Rápido: Notificações por push no SDK do Aplicativo Windows

Neste início rápido, você criará um aplicativo de Windows da área de trabalho que envia e recebe notificações por push usando o SDK do Aplicativo Windows.

Prerequisites

• Start desenvolvendo aplicativos Windows
• Criar um novo projeto que usa o SDK do Aplicativo Windows OR Use o SDK do Aplicativo Windows em um projeto existente
• Uma conta Azure é necessária para usar SDK do Aplicativo Windows notificações por push.
• Leia a visão geral das notificações por push

Requisitos de empacotamento

As notificações por push no SDK do Aplicativo Windows dão suporte a aplicativos de área de trabalho empacotados e verdadeiramente descompactados. No entanto, a identidade do pacote é necessária para entrega em segundo plano e ativação COM — o cenário de produção mais comum. A tabela a seguir resume o que é necessário com base no modelo de empacotamento:

Aplicativo de exemplo

Este guia de início rápido explica como adicionar suporte a notificações por push ao seu aplicativo no SDK do Aplicativo Windows 1.7. Veja um código semelhante a este início rápido nos aplicativos de exemplo encontrados em GitHub. Verifique o branch com sua versão preferencial do SDK do Aplicativo Windows para obter os exemplos que melhor correspondem ao seu projeto.

Você também pode encontrar amostras para cada versão do SDK do Aplicativo Windows selecionando um branch de versão no repositório de amostras.

Referência de API

Para obter a documentação de referência da API para notificações por push, consulte Microsoft.Windows. Namespace pushNotifications.

Configurar a identidade do aplicativo no AAD (Azure Active Directory)

As notificações por push no SDK do Aplicativo Windows usam identidades do Azure Active Directory (AAD). Azure credenciais são necessárias ao solicitar um URI do Canal do WNS e ao solicitar tokens de acesso para enviar notificações por push. Nota: não damos suporte ao uso das notificações por push do SDK do Aplicativo Windows com o Microsoft Partner Center.

Etapa 1: Criar um registro de aplicativo do AAD

Faça logon em sua conta Azure e crie um novo recurso AAD App Registration. Selecione Novo registro.

Etapa 2: Informe um nome e selecione uma opção multiusuário

1. Forneça um nome de aplicativo.

2. As notificações por push exigem a opção multilocatário, portanto, selecione-a.

   1. Para obter mais informações sobre locatários, consulte Quem pode entrar em seu aplicativo?.

3. Escolha Registrar

4. Anote sua ID Application (cliente), pois esta é sua Azure AppId que você usará durante o registro de ativação e a solicitação de token de acesso.

5. Anote sua ID do Diretório (locatário), pois esta é sua Azure TenantId que você usará ao solicitar um token de acesso.

   Important

   . Tome nota do ID de aplicativo (cliente) e do ID de diretório (locatário) .

6. Anote sua ID Objeto, pois esta é a Azure ObjectId que você usará ao solicitar uma solicitação de canal. Observe que esta não é a ID do objeto listada na página do Essentials. Em vez disso, para encontrar o ID de Objeto correto, clique no nome do aplicativo no campo "aplicativo gerenciado no diretório local" na página "Essentials" .

   

   captura de tela

   Note

   Um principal de serviço é necessário para obter uma ID de Objeto, se não houver uma associada ao seu aplicativo, siga as etapas em um dos seguintes artigos para criar um no portal do Azure ou usando a linha de comando.

   Use o portal para criar uma aplicação Azure AD e um principal de serviço que possa acessar recursos

   Use Azure PowerShell para criar um principal de serviço com um certificado

Etapa 3: Criar um segredo para o registro do aplicativo

Seu segredo será usado junto com seu Azure AppId/ClientId ao solicitar um token de acesso para enviar notificações por push.

Navegue até Certificados & segredos e selecione Novo segredo do cliente.

Etapa 4: Mapear o Nome da Família de Pacotes do seu aplicativo para o Azure AppId

Se o seu aplicativo estiver empacotado (incluindo empacotado em um local externo), você pode usar este fluxo para mapear o Nome da Família de Pacotes (PFN) do seu aplicativo junto ao seu AppId do Azure.

Se seu aplicativo for um aplicativo Win32 empacotado, crie uma solicitação de mapeamento PFN (Nome da Família de Pacotes) enviando por email Win_App_SDK_Push@microsoft.com com a linha de assunto "SDK do Aplicativo Windows Solicitação de Mapeamento de Notificações por Push" e o corpo "PFN: [seu PFN]", AppId: [sua APPId], ObjectId: [sua ObjectId]. As solicitações de mapeamento são concluídas semanalmente. Você será notificado após a conclusão da solicitação de mapeamento.

Depois de ter seu Azure AppId, ObjectId e segredo, você pode adicionar essas credenciais ao código de exemplo abaixo.

Configurar seu aplicativo para receber notificações por push

Etapa 1: Adicionar SDK do Aplicativo Windows e pacotes NuGet necessários

Em seguida, clique com o botão direito do mouse na solução no Gerenciador de Soluções e selecione Manage NuGet Packages.

No Gerenciador de Pacotes, adicione os seguintes pacotes:

• Microsoft. WindowsAppSDK (versão mínima 1.1.0)
• Microsoft. Windows. SDK. BuildTools (versão mínima 10.0.22000.194)
• Microsoft. Windows. CppWinRT, (versão mínima 2.0.210930.14)
• Microsoft. Windows. ImplementationLibrary, (versão mínima 1.0.210930.1)

Se esta for a primeira vez que você estiver usando SDK do Aplicativo Windows em seu projeto e ele for empacotado com local externo ou desempacotado, inicialize o SDK do Aplicativo Windows adicionando a seguinte propriedade ao arquivo de projeto:

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

ou usar a API bootstrapper. Consulte Uso do runtime do SDK do Aplicativo Windows para aplicativos empacotados com local externo ou não empacotados para obter mais detalhes.

Etapa 2: Adicionar namespaces

Em seguida, adicione o namespace para notificações push do SDK do Aplicativo Windows Microsoft.Windows.PushNotifications.

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

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

Se você receber o erro "Não é possível encontrar Microsoft.Windows.PushNotifications", isso provavelmente significa que os arquivos de cabeçalho não foram gerados. Para resolver, verifique se você tem os pacotes acima instalados, comente as instruções de inclusão e de uso que estão causando o erro e reconstrua o aplicativo para que os arquivos de cabeçalho sejam gerados. Depois que o build for bem-sucedido, descomente as instruções de inclusão e as instruções de uso e recompile o projeto. Isso deve resolver o erro.

Etapa 3: Adicionar o ativador COM ao manifesto do aplicativo

Se seu aplicativo estiver empacotado (incluindo empacotado com localização externa): abra seu Package.appxmanifest. Adicione o seguinte dentro do elemento <Application>. Substitua os valores Id, Executablee DisplayName por aqueles específicos ao seu aplicativo.

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

Etapa 4: Registrar e responder a notificações por push na inicialização do aplicativo

Atualize o método main() do aplicativo para adicionar o seguinte:

1. Registre seu aplicativo para receber notificações push chamando o PushNotificationManager::Default().Register().
2. Verifique a origem da solicitação de ativação chamando AppInstance::GetCurrent(). GetActivatedEventArgs(). Se a ativação foi disparada de uma notificação por push, responda com base no conteúdo da notificação.

Adicionando manipuladores de eventos em primeiro plano

Para lidar com um evento em primeiro plano, registre um manipulador para PushNotificationManager.PushReceived.

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

Adicionar a verificação PushNotificationManager::IsSupported()

Em seguida, adicione uma verificação se as APIs PushNotification têm suporte com PushNotificationManager.IsSupported(). Caso contrário, recomendamos que você use sondagem ou sua própria implementação de soquete personalizado.

Agora que o suporte a notificações por push foi confirmado, adicione um comportamento com base em PushNotificationReceivedEventArgs.

Etapa 5: Solicitar um URI do Canal do WNS e registrá-lo no servidor WNS

Os URIs de canal do WNS são os endpoints HTTP para o envio de notificações push. Cada cliente deve solicitar um URI do Canal e registrá-lo no servidor WNS para receber notificações por push.

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

Se você estiver seguindo o código do tutorial, adicione a ID do objeto Azure aqui:

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

O PushNotificationManager tentará criar uma URI de canal, repetindo automaticamente por no máximo 15 minutos. Crie um manipulador de eventos para aguardar a conclusão da chamada. Depois que a chamada for concluída, se tiver sido bem-sucedida, registre o URI com o servidor WNS.

Código de exemplo

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

Etapa 6: Criar e instalar seu aplicativo

Use Visual Studio para criar e instalar seu aplicativo. Clique com o botão direito do mouse no arquivo de solução no Gerenciador de Soluções e selecione Deploy. Visual Studio criará seu aplicativo e o instalará em seu computador. Você pode executar o aplicativo iniciando-o por meio do Menu Iniciar ou do depurador Visual Studio.

O console do código do tutorial terá esta aparência:

Você precisará do token para enviar uma notificação por push ao seu aplicativo.

Enviar uma notificação por push para seu aplicativo

Neste ponto, toda a configuração está concluída e o servidor WNS pode enviar notificações por push para aplicativos cliente. Nas etapas a seguir, consulte os cabeçalhos de solicitação e resposta do servidor de notificação por push para obter mais detalhes.

Etapa 1: Solicitar um token de acesso

Para enviar uma notificação por push, primeiro o servidor WNS precisa solicitar um token de acesso. Envie uma solicitação HTTP POST com seu Azure TenantId, Azure AppId e segredo. Para obter informações sobre como recuperar o TenantId do locatário e o AppId do aplicativo no Azure, consulte Obter os valores de ID de locatário e aplicativo para autenticação.

Solicitação de exemplo 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/

Solicitação de exemplo do 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);

Se sua solicitação for bem-sucedida, você receberá uma resposta que contém seu token no campo access_token.

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

Etapa 2. Enviar uma notificação bruta

Crie uma solicitação HTTP POST que contenha o token de acesso obtido na etapa anterior e o conteúdo da notificação por push que você deseja enviar. O conteúdo da notificação por push será entregue ao aplicativo.

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

Etapa 3: Enviar uma notificação de aplicativo de origem na nuvem

Se você estiver interessado apenas em enviar notificações brutas, ignore esta etapa. Para enviar uma notificação de aplicativo de origem na nuvem, também conhecida como notificação por push, siga primeiro Quickstart: Notificações de aplicativo no SDK do Aplicativo Windows. As notificações do aplicativo podem ser enviadas por push (enviadas da nuvem) ou enviadas localmente. Enviar uma notificação de aplicativo originada na nuvem é semelhante ao envio de uma notificação bruta na etapa 2, exceto que o cabeçalho X-WNS-Type é toast, o cabeçalho Content-Type é text/xmle o conteúdo inclui a carga XML da notificação do aplicativo. Consulte o esquema XML de notificações para saber mais sobre como construir sua carga XML.

Crie uma solicitação HTTP POST que contenha seu token de acesso e o conteúdo da notificação de aplicativo de origem na nuvem que você deseja enviar. O conteúdo da notificação por push será entregue ao aplicativo.

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 WNS (Serviço de Notificação por Push)
• Exemplo de código de notificações Push no GitHub
• Microsoft.Windows. Detalhes da API do PushNotifications
• Especificação de notificações push no GitHub
• Conteúdo do aviso
• Esquema XML de notificações