Inicio rápido: Notificaciones push en el SDK de aplicaciones de Windows

En este inicio rápido, creará una aplicación de Windows de escritorio que envía y recibe notificaciones push mediante el SDK de aplicaciones de Windows.

Prerequisites

Empezar a desarrollar aplicaciones de Windows
Cree un nuevo proyecto que use el SDK de aplicaciones de Windows O use el SDK de aplicaciones de Windows en un proyecto existente.
Se requiere una cuenta de Azure para usar las notificaciones push del SDK de aplicaciones de Windows.
Lea la visión general de las notificaciones push

Aplicación de ejemplo

En este inicio rápido se explica cómo agregar compatibilidad con notificaciones push a la aplicación en Windows App SDK 1.7. Consulte código similar a este inicio rápido en las aplicaciones de ejemplo que se encuentran en GitHub. Asegúrese de consultar la rama con su versión preferida del SDK de aplicaciones de Windows para ver los ejemplos que mejor coincidan con el proyecto.

Código de la App de Ejemplo

También puede encontrar ejemplos para cada versión de Windows App SDK seleccionando una rama de versión en el repositorio de ejemplos.

Referencia de API

Para obtener documentación de referencia de API para notificaciones push, consulte espacio de nombres Microsoft.Windows.PushNotifications.

Configuración de la identidad de la aplicación en Azure Active Directory (AAD)

Las notificaciones push en windows App SDK usan identidades de Azure Active Directory (AAD). Las credenciales de Azure son necesarias al solicitar un URI del canal WNS y al solicitar tokens de acceso para enviar notificaciones push. Nota: no se soporte técnico con notificaciones push de Windows App SDK con el Centro de partners de Microsoft.

Paso 1: Creación de un registro de aplicaciones de AAD

Inicie sesión en su cuenta de Azure y cree un recurso registro de aplicaciones de AAD. Seleccione Nuevo registro.

Paso 2: Proporcionar un nombre y seleccionar una opción multiinquilino

Especifique un nombre de la aplicación.
Las notificaciones push requieren la opción multiinquilino, así que selecciónela.
1. Para obtener más información sobre los inquilinos, consulte ¿Quién puede iniciar sesión en la aplicación?
Seleccione Registrar.
Tenga en cuenta su ID de aplicación (cliente) , ya que este es su ID de aplicación de Azure que va a usar durante el registro de activación y la solicitud de token de acceso.
Tome nota del identificador de Directory (inquilino), ya que este es el Azure TenantId que va a usar al solicitar un token de acceso.

Important

Tome nota de la id. de aplicación (cliente) y id. de directorio (inquilino).
Tome nota del identificador de objeto de , ya que esta es la Azure ObjectId que va a usar al solicitar una solicitud de canal. Tenga en cuenta que no es el identificador de objeto que aparece en la página Essentials . En su lugar, para encontrar el identificador de objeto correcto , haga clic en el nombre de la aplicación en el campo de la aplicación administrada en el directorio local en la página de Essentials .

Captura de pantalla de

Note

Se requiere un principal de servicio para obtener un identificador de objeto; si no hay uno asociado a la aplicación, siga los pasos descritos en uno de los siguientes artículos para crear uno en el portal de Azure o mediante la línea de comandos.

Uso del portal para crear una aplicación de Azure AD y una entidad de servicio que puedan acceder a los recursos

Uso de Azure PowerShell para crear una entidad de servicio con un certificado

Paso 3: Crear un secreto para el registro de la aplicación

El secreto se usará junto con azure AppId/ClientId al solicitar un token de acceso para enviar notificaciones push.

Secreto de la aplicación AAD

Vaya a Certificados y secretos y seleccione Nuevo secretos de cliente.

Important

Asegúrese de copiar el secreto una vez creado y almacenarlo en una ubicación segura, como Azure Key Vault. Solo se podrá ver una vez después de la creación.

Paso 4: Mapear el Nombre de Familia del Paquete de la aplicación a su ID de la aplicación en Azure

Si su aplicación está empaquetada (incluida con una ubicación externa), puede usar este flujo para asignar el nombre de familia de paquetes (PFN) de su aplicación y su Id de aplicación de Azure.

Si la aplicación es una aplicación Win32 empaquetada, cree una solicitud de asignación de nombre de familia de paquetes (PFN) mediante correo electrónico Win_App_SDK_Push@microsoft.com con la línea de asunto "Solicitud de asignación de notificaciones push del SDK de aplicaciones de Windows" y el cuerpo "PFN: [su PFN]", AppId: [su APPId], ObjectId: [su ObjectId]. Las solicitudes de mapeo se completan semanalmente. Recibirá una notificación una vez completada la solicitud de asignación.

Una vez que tenga azure AppId, ObjectId y secret, puede agregar esas credenciales al código de ejemplo siguiente.

Configuración de la aplicación para recibir notificaciones push

Paso 1: Agregar el SDK de aplicaciones de Windows y los paquetes NuGet necesarios

A continuación, haga clic con el botón derecho en la solución en el Explorador de soluciones y seleccione Administrar paquetes NuGet.

En el Administrador de paquetes, agregue los siguientes paquetes:

Microsoft.WindowsAppSDK (versión mínima 1.1.0)
Microsoft.Windows.SDK.BuildTools (versión mínima 10.0.22000.194)
Microsoft.Windows.CppWinRT, (versión mínima 2.0.210930.14)
Microsoft.Windows.ImplementationLibrary (versión mínima 1.0.210930.1)

Si esta es la primera vez que usa Windows App SDK en el proyecto y se empaqueta con ubicación externa o desempaquetada, inicialice el SDK de aplicaciones de Windows agregando la siguiente propiedad al archivo de proyecto:

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

o use la API de programa previo. Consulte Usar el entorno de ejecución de Windows App SDK para aplicaciones empaquetadas con ubicación externa o desempaquetadas para obtener más detalles.

Note

Si el SDK no se inicializa, la aplicación iniciará System.Runtime.InteropServices.COMException (0x80040154): Class not registered (0x80040154 (REGDB_E_CLASSNOTREG)) y no se ejecutará.

Paso 2: Agregar espacios de nombres

A continuación, agregue el espacio de nombres para las notificaciones Microsoft.Windows.PushNotificationspush del SDK de aplicaciones de Windows.

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

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

Si recibe un error "No se encuentra Microsoft.Windows.PushNotifications", probablemente significa que no se han generado los archivos de encabezado. Para resolverlo, asegúrese de que tiene instalados los paquetes anteriores, convierta en comentario las instrucciones include y using que provocan el error y recompile la aplicación para generar los archivos de encabezado. Una vez que la compilación se realiza correctamente, quite la marca de comentario de instrucciones include y using y recompile el proyecto. Esto debe resolver el error.

Paso 3: Agregar el activador COM al manifiesto de la aplicación

Important

Si la aplicación está desempaquetada (es decir, carece de identidad de paquete en tiempo de ejecución), vaya al paso 4: Registrar y responder a las notificaciones push en el inicio de la aplicación.

Si tu aplicación está empaquetada (incluyendo si está empaquetada con ubicación externa): abre el Package.appxmanifest. Agregue lo siguiente dentro del <Application> elemento . Reemplace los Idvalores , Executabley DisplayName por los específicos de la aplicación.

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

Se puede encontrar un ejemplo de la clase de C++ completada para este ejemplo después del paso 5. Los pasos 4 y 5 proporcionan instrucciones paso a paso para agregar cada pieza en el ejemplo final.

Paso 4: Registrar y responder a notificaciones push en el inicio de la aplicación

Actualice el método de su aplicación main() para agregar lo siguiente:

Registre su aplicación para recibir notificaciones push llamando a PushNotificationManager::Default().Register().
Compruebe el origen de la solicitud de activación llamando a AppInstance::GetCurrent(). GetActivatedEventArgs(). Si la activación se desencadenó desde una notificación push, responda en función de la carga útil de la notificación.

Important

Debe llamar a PushNotificationManager::D efault(). Registre antes de llamar a AppInstance.GetCurrent.GetActivatedEventArgs.

Adición de controladores de eventos en primer plano

Para controlar un evento en primer plano, registre un controlador para PushNotificationManager.PushReceived.

Important

También debe registrar los controladores de eventos PushNotificationManager.PushReceived antes de llamar a PushNotificationManager.Register(). De lo contrario, se producirá la siguiente excepción en tiempo de ejecución:

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

Agregue la comprobación PushNotificationManager::IsSupported()

A continuación, agregue una comprobación si se admiten las API pushNotification con PushNotificationManager.IsSupported().. Si no es así, se recomienda usar el sondeo o su propia implementación de socket personalizado.

Ahora que hay compatibilidad con notificaciones push confirmadas, agregue el comportamiento basado en PushNotificationReceivedEventArgs.

Paso 5: Solicitar un URI del canal WNS y registrarlo con el servidor WNS

Los URI del canal WNS son los puntos de conexión HTTP para enviar notificaciones push. Cada cliente debe solicitar un URI de canal y registrarlo en el servidor WNS para recibir notificaciones push.

Note

Los URI del canal WNS expiran después de 30 días.

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

Si sigue el código del tutorial, agregue el identificador de objeto de Azure aquí:

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

El PushNotificationManager intentará crear un URI de canal, reintentando automáticamente durante no más de 15 minutos. Cree un controlador de eventos para esperar a que se complete la llamada. Una vez completada la llamada, si se realizó correctamente, registre el URI con el servidor WNS.

Código de ejemplo

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

Paso 6: Compilar e instalar la aplicación

Use Visual Studio para compilar e instalar la aplicación. Haga clic con el botón derecho en el archivo de solución en el Explorador de soluciones y seleccione Implementar. Visual Studio compilará la aplicación e la instalará en la máquina. Puede ejecutar la aplicación iniciandola mediante el menú Inicio o el depurador de Visual Studio.

La consola del código del tutorial tendrá este aspecto:

consola de ejemplo de trabajo

Necesitará el token para enviar una notificación push a la aplicación.

Envío de una notificación push a la aplicación

En este momento, se completa toda la configuración y el servidor WNS puede enviar notificaciones push a las aplicaciones cliente. En los pasos siguientes, consulte los encabezados de solicitud y respuesta del servidor de notificaciones push y para más detalles.

Paso 1: Solicitar un token de acceso

Para enviar una notificación push, el servidor WNS primero debe solicitar un token de acceso. Envíe una solicitud HTTP POST con Azure TenantId, Azure AppId y Secret. Para obtener información sobre cómo recuperar el Azure TenantId y el Azure AppId, consulte Obtención de valores de identificador de inquilino y de aplicación para el inicio de sesión.

Solicitud de ejemplo 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/

Solicitud de ejemplo de 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 la solicitud se realiza correctamente, recibirá una respuesta que contiene el token en el campo access_token .

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

Paso 2. Enviar una notificación sin procesar

Cree una solicitud HTTP POST que contenga el token de acceso que obtuvo en el paso anterior y el contenido de la notificación push que desea enviar. El contenido de la notificación push se entregará a la aplicación.

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

Paso 3: Envío de una notificación de aplicación de origen en la nube

Si solo está interesado en enviar notificaciones sin procesar, omita este paso. Para enviar una notificación de aplicación procedente de la nube, también conocida como notificación emergente push, primero siga Inicio rápido: Notificaciones de aplicaciones en Windows App SDK. Las notificaciones de la aplicación pueden ser push (enviadas desde la nube) o enviarse localmente. El envío de una notificación de aplicación generada en la nube es similar al envío de una notificación sin procesar en el paso 2, excepto que el encabezado X-WNS-Type es toast, el Content-Type es text/xml, y el contenido contiene la carga XML de notificación de la aplicación. Consulte esquema XML de notificaciones para obtener más información sobre cómo construir la carga XML.

Cree una solicitud HTTP POST que contenga el token de acceso y el contenido de la notificación de aplicación de origen en la nube que desea enviar. El contenido de la notificación push se entregará a la aplicación.

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

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-09-06

Compartir a través de

Inicio rápido: Notificaciones push en el SDK de aplicaciones de Windows

Prerequisites

Aplicación de ejemplo

Referencia de API

Configuración de la identidad de la aplicación en Azure Active Directory (AAD)

Paso 1: Creación de un registro de aplicaciones de AAD

Paso 2: Proporcionar un nombre y seleccionar una opción multiinquilino

Paso 3: Crear un secreto para el registro de la aplicación

Paso 4: Mapear el Nombre de Familia del Paquete de la aplicación a su ID de la aplicación en Azure

Configuración de la aplicación para recibir notificaciones push

Paso 1: Agregar el SDK de aplicaciones de Windows y los paquetes NuGet necesarios

Paso 2: Agregar espacios de nombres

Paso 3: Agregar el activador COM al manifiesto de la aplicación

Paso 4: Registrar y responder a notificaciones push en el inicio de la aplicación

Adición de controladores de eventos en primer plano

Agregue la comprobación PushNotificationManager::IsSupported()

Paso 5: Solicitar un URI del canal WNS y registrarlo con el servidor WNS

Código de ejemplo

Paso 6: Compilar e instalar la aplicación

Envío de una notificación push a la aplicación

Paso 1: Solicitar un token de acceso

Paso 2. Enviar una notificación sin procesar

Paso 3: Envío de una notificación de aplicación de origen en la nube

Resources

Comentarios

Recursos adicionales