Merge pull request #6618 from MicrosoftDocs/jken/fix-568635-push-notifications-gaps

GrantMeStrength · web-flow · commit ab996a38e947 · 2026-04-09T12:32:21.000-07:00
Fix 568635: Push notifications discoverability and WNS auth gaps
diff --git a/hub/apps/develop/notifications/index.md b/hub/apps/develop/notifications/index.md
@@ -54,6 +54,13 @@ For a full breakdown of delivery methods, see [Choose a notification delivery me
 - [App notifications quickstart](app-notifications/app-notifications-quickstart.md)
 - [Push notifications overview](push-notifications/index.md) — WNS push using `PushNotificationManager`
 
+**Building a WPF or WinForms app?**
+- [App notifications quickstart](app-notifications/app-notifications-quickstart.md) — local toast notifications work packaged or unpackaged
+- [Push notifications quickstart](push-notifications/push-quickstart.md) — WNS push supports a limited truly unpackaged path, but packaging (MSIX or packaged with external location) is required for background delivery and COM activation
+
+> [!IMPORTANT]
+> Windows App SDK push notifications require an [Azure account](https://azure.microsoft.com/pricing/purchase-options/azure-account) and an **Azure AD app registration**. If your app is packaged, you also need to submit a Package Family Name (PFN) mapping request by email — allow for **up to one week** of processing time before launch. See the [push notifications quickstart](push-notifications/push-quickstart.md) for full prerequisites.
+
 **Building or maintaining a UWP app?**
 - [Send a local app notification from C++ UWP apps](app-notifications/send-local-toast-cpp-uwp.md)
 - [Windows Push Notification Services (WNS) overview](push-notifications/wns-overview.md)
diff --git a/hub/apps/develop/notifications/push-notifications/push-quickstart.md b/hub/apps/develop/notifications/push-notifications/push-quickstart.md
@@ -2,7 +2,7 @@
 title: Quickstart Push notifications in the Windows App SDK
 description: Send push notifications using the Windows App SDK
 ms.topic: quickstart
-ms.date: 07/14/2025
+ms.date: 04/09/2026
 keywords: push, notification
 ms.localizationpriority: medium
 ms.custom:
@@ -21,6 +21,21 @@ In this quickstart you will create a desktop Windows application that sends and
 - An [Azure Account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn) is required in order to use Windows App SDK push notifications.
 - Read [Push notifications overview](../../../windows-app-sdk/notifications/push-notifications/index.md)
 
+## Packaging requirements
+
+Push notifications in the Windows App SDK support both packaged and truly unpackaged desktop apps. However, **package identity is required for background delivery and COM activation** — the most common production scenario. The following table summarizes what's required based on your packaging model:
+
+| Packaging model | COM activator required | PFN mapping required | Unpackaged supported |
+|---|---|---|---|
+| **MSIX packaged** (WinUI 3, packaged WPF/WinForms) | Yes — in `Package.appxmanifest` | Yes — via PFN mapping email | No |
+| **Packaged with external location** | Yes — in `Package.appxmanifest` | Yes — via PFN mapping email | No |
+| **Truly unpackaged** (no package identity) | No (skip Step 3) | No | Yes — limited functionality |
+
+> [!IMPORTANT]
+> If your app is packaged (MSIX or packaged with external location), you must map your app's **Package Family Name (PFN)** to its **Azure AppId** before push notifications will work. Mapping requests are submitted by email to [Win_App_SDK_Push@microsoft.com](mailto:Win_App_SDK_Push@microsoft.com) and are processed **on a weekly basis**. Plan for this lead time before your launch.
+>
+> See [Step 4: Map your app's Package Family Name to its Azure AppId](#step-4-map-your-apps-package-family-name-to-its-azure-appid) for details.
+
 ## Sample app
 
 This quickstart walks through adding push notifications support to your app on Windows App SDK 1.7. See similar code to this quickstart in the sample apps found on [GitHub](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/1.7-stable/Samples/Notifications/Push). Make sure to check out the [branch with your preferred version of the Windows App SDK](https://github.com/microsoft/WindowsAppSDK-Samples/branches) for the samples that best match your project.
@@ -161,6 +176,9 @@ Open your **Package.appxmanifest**. Add the following inside the `<Application>`
  </Package>    
 ```
 
+> [!NOTE]
+> The `Id` attribute in `<com:Class>` must be set to your **Azure AppId** (the Application (client) ID from your Azure AD app registration). This is how Windows App SDK connects your app's COM activation to its Azure identity — when WNS activates your app to deliver a background push notification, it uses this GUID to locate and launch the correct COM server. Use the same Azure AppId value you noted in Step 1 above.
+
 > [!NOTE]
 > An example of the completed C++ class for this example can be found [after Step 5](#example-code). Steps 4 and 5 provide step-by-step guidance to add each piece in the final example.
 
@@ -195,7 +213,7 @@ Now that there's confirmed push notification support, add in behavior based on [
 WNS Channel URIs are the HTTP endpoints for sending push notifications. Each client must request a Channel URI and register it with the WNS server to receive push notifications.
 
 > [!NOTE]
-> WNS Channel URIs expire after 30 days.
+> WNS Channel URIs expire after 30 days. **Request a fresh channel URI on every app launch** rather than caching a previous one. When the new URI differs from what your backend has stored, send the updated URI to your cloud service so it can keep its records current. Do not assume the URI will remain stable between sessions — treating it as a mutable, session-scoped value avoids silent delivery failures caused by expired or stale channel URIs.
 
 ```cpp
 auto channelOperation{ PushNotificationManager::Default().CreateChannelAsync(winrt::guid("[Your app's Azure ObjectID]")) };
diff --git a/hub/apps/develop/notifications/push-notifications/wns-overview.md b/hub/apps/develop/notifications/push-notifications/wns-overview.md
@@ -3,7 +3,7 @@ description: The Windows Push Notification Services (WNS) enables third-party de
 title: Windows Push Notification Services (WNS) overview
 ms.assetid: 2125B09F-DB90-4515-9AA6-516C7E9ACCCD
 template: detail.hbs
-ms.date: 11/27/2024
+ms.date: 04/09/2026
 ms.topic: article
 keywords: windows 10, uwp
 ms.localizationpriority: medium
@@ -32,7 +32,10 @@ Before you can send notifications using WNS, your app must be registered with th
 
 ## Requesting a notification channel
 
-When an app that is capable of receiving push notifications runs, it must first request a notification channel through the [**CreatePushNotificationChannelForApplicationAsync**](/uwp/api/Windows.Networking.PushNotifications.PushNotificationChannelManager#Windows_Networking_PushNotifications_PushNotificationChannelManager_CreatePushNotificationChannelForApplicationAsync_System_String_). For a full discussion and example code, see [How to request, create, and save a notification channel](/previous-versions/windows/apps/hh465412(v=win.10)). This API returns a channel URI that is uniquely linked to the calling application and its tile, and through which all notification types can be sent.
+> [!NOTE]
+> The channel-request guidance in this section applies to UWP apps that use [**CreatePushNotificationChannelForApplicationAsync**](/uwp/api/Windows.Networking.PushNotifications.PushNotificationChannelManager#Windows_Networking_PushNotifications_PushNotificationChannelManager_CreatePushNotificationChannelForApplicationAsync_System_String_). If you're building a Windows App SDK desktop app (WinUI 3, WPF, or WinForms), use `PushNotificationManager` instead — see the [Push notifications quickstart](push-quickstart.md).
+
+When an app that is capable of receiving push notifications runs, it must first request a notification channel through the [**CreatePushNotificationChannelForApplicationAsync**](/uwp/api/Windows.Networking.PushNotifications.PushNotificationChannelManager#Windows_Networking_PushNotifications_PushNotificationChannelManager_CreatePushNotificationChannelForApplicationAsync_System_String_). For a full discussion and example code, see [How to request, create, and save a notification channel](request-create-save-notification-channel.md). This API returns a channel URI that is uniquely linked to the calling application and its tile, and through which all notification types can be sent.
 
 After the app has successfully created a channel URI, it sends it to its cloud service, together with any app-specific metadata that should be associated with this URI.
 
@@ -41,10 +44,15 @@ After the app has successfully created a channel URI, it sends it to its cloud s
 -   We do not guarantee that the notification channel URI for an app will always remain the same. We advise that the app requests a new channel every time it runs and updates its service when the URI changes. The developer should never modify the channel URI and should consider it as a black-box string. At this time, channel URIs expire after 30 days. If your Windows 10 app will periodically renew its channel in the background then you can download the [Push and periodic notifications sample](https://github.com/microsoftarchive/msdn-code-gallery-microsoft/tree/411c271e537727d737a53fa2cbe99eaecac00cc0/Official%20Windows%20Platform%20Sample/Windows%208%20app%20samples/%5BC%23%5D-Windows%208%20app%20samples/C%23/Windows%208%20app%20samples/Push%20and%20periodic%20notifications%20client-side%20sample%20(Windows%208)) for Windows 8.1 and re-use its source code and/or the pattern it demonstrates.
 -   The interface between the cloud service and the client app is implemented by you, the developer. We recommend that the app go through an authentication process with its own service and transmit data over a secure protocol such as HTTPS.
 -   It is important that the cloud service always ensures that the channel URI uses the domain "notify.windows.com". The service should never push notifications to a channel on any other domain. If the callback for your app is ever compromised, a malicious attacker could submit a channel URI to spoof WNS. Without inspecting the domain, your cloud service could potentially disclose information to this attacker unknowingly. The subdomain of the channel URI is subject to change and should not be considered when validating the channel URI.
--   If your cloud service attempts to deliver a notification to an expired channel, WNS will return [response code 410](/previous-versions/windows/apps/hh465435(v=win.10)). In response to that code, your service should no longer attempt to send notifications to that URI.
+-   If your cloud service attempts to deliver a notification to an expired channel, WNS will return [response code 410](push-request-response-headers.md). In response to that code, your service should no longer attempt to send notifications to that URI.
 
 ## Authenticating your cloud service
 
+> [!WARNING]
+> This section describes the legacy UWP authentication flow using a **Package SID** and **secret key** obtained from the Microsoft Store Dashboard, which authenticates to `login.live.com`. This flow is specific to UWP apps registered via Partner Center and is **not compatible** with Windows App SDK push notifications.
+>
+> If you are building a WPF, WinForms, or WinUI 3 app using the Windows App SDK, use the **Azure Active Directory (Azure AD)** authentication flow described in the [Push notifications quickstart](push-quickstart.md) instead.
+
 To send a notification, the cloud service must be authenticated through WNS. The first step in this process occurs when you register your app with the Microsoft Store Dashboard. During the registration process, your app is given a Package security identifier (SID) and a secret key. This information is used by your cloud service to authenticate with WNS.
 
 The WNS authentication scheme is implemented using the client credentials profile from the [OAuth 2.0](https://tools.ietf.org/html/draft-ietf-oauth-v2-23) protocol. The cloud service authenticates with WNS by providing its credentials (Package SID and secret key). In return, it receives an access token. This access token allows a cloud service to send a notification. The token is required with every notification request sent to the WNS.
@@ -56,7 +64,7 @@ At a high level, the information chain is as follows:
 
 ![wns diagram for cloud service authentication](images/wns-diagram-02.jpg)
 
-In the authentication with WNS, the cloud service submits an HTTP request over Secure Sockets Layer (SSL). The parameters are supplied in the "application/x-www-for-urlencoded" format. Supply your Package SID in the "client\_id" field and your secret key in the "client\_secret" field as shown in the following example. For syntax details, see the [access token request](/previous-versions/windows/apps/hh465435(v=win.10)) reference.
+In the authentication with WNS, the cloud service submits an HTTP request over Secure Sockets Layer (SSL). The parameters are supplied in the "application/x-www-form-urlencoded" format. Supply your Package SID in the "client\_id" field and your secret key in the "client\_secret" field as shown in the following example. For syntax details, see the [access token request](push-request-response-headers.md) reference.
 
 > [!NOTE]
 > This is just an example, not cut-and-paste code that you can successfully use in your own code. 
@@ -72,7 +80,7 @@ In the authentication with WNS, the cloud service submits an HTTP request over S
 
 The WNS authenticates the cloud service and, if successful, sends a response of "200 OK". The access token is returned in the parameters included in the body of the HTTP response, using the "application/json" media type. After your service has received the access token, you are ready to send notifications.
 
-The following example shows a successful authentication response, including the access token. For syntax details, see [Push notification service request and response headers](/previous-versions/windows/apps/hh465435(v=win.10)).
+The following example shows a successful authentication response, including the access token. For syntax details, see [Push notification service request and response headers](push-request-response-headers.md).
 
 ``` http
  HTTP/1.1 200 OK   
@@ -98,13 +106,13 @@ The following example shows a successful authentication response, including the
 
 Using the channel URI, the cloud service can send a notification whenever it has an update for the user.
 
-The access token described above can be reused for multiple notification requests; the cloud server is not required to request a new access token for every notification. If the access token has expired, the notification request will return an error. We recommended that you do not try to re-send your notification more than once if the access token is rejected. If you encounter this error, you will need to request a new access token and resend the notification. For the exact error code, see [Push notification response codes](/previous-versions/windows/apps/hh465435(v=win.10)).
+The access token described above can be reused for multiple notification requests; the cloud server is not required to request a new access token for every notification. If the access token has expired, the notification request will return an error. We recommend that you do not try to re-send your notification more than once if the access token is rejected. If you encounter this error, you will need to request a new access token and resend the notification. For the exact error code, see [Push notification service request and response headers](push-request-response-headers.md).
 
 1.  The cloud service makes an HTTP POST to the channel URI. This request must be made over SSL and contains the necessary headers and the notification payload. The authorization header must include the acquired access token for authorization.
 
-    An example request is shown here. For syntax details, see [Push notification response codes](/previous-versions/windows/apps/hh465435(v=win.10)).
+    An example request is shown here. For syntax details, see [Push notification service request and response headers](push-request-response-headers.md).
 
-    For details on composing the notification payload, see [Quickstart: Sending a push notification](/previous-versions/windows/apps/hh868252(v=win.10)). The payload of a tile, toast, or badge push notification is supplied as XML content that adheres to their respective defined [Adaptive tiles schema](/windows/uwp/launch-resume/adaptive-tiles-schema) or [Legacy tiles schema](/uwp/schemas/tiles/tiles-xml-schema-portal). The payload of a raw notification does not have a specified structure. It is strictly app-defined.
+    For details on composing the notification payload, see [Quickstart: Push notifications in the Windows App SDK](push-quickstart.md). The payload of a tile, toast, or badge push notification is supplied as XML content that adheres to their respective defined [Adaptive tiles schema](/windows/uwp/launch-resume/adaptive-tiles-schema) or [Legacy tiles schema](/uwp/schemas/tiles/tiles-xml-schema-portal). The payload of a raw notification does not have a specified structure. It is strictly app-defined.
 
     ``` http
      POST https://cloud.notify.windows.com/?token=AQE%bU%2fSjZOCvRjjpILow%3d%3d HTTP/1.1
@@ -138,7 +146,7 @@ This diagram illustrates the data flow:
 
 By default, tile and badge notifications expire three days after being downloaded. When a notification expires, the content is removed from the tile or queue and is no longer shown to the user. It's a best practice to set an expiration (using a time that makes sense for your app) on all tile and badge notifications so that your tile's content doesn't persist longer than it is relevant. An explicit expiration time is essential for content with a defined lifespan. This also assures the removal of stale content if your cloud service stops sending notifications, or if the user disconnects from the network for an extended period.
 
-Your cloud service can set an expiration for each notification by setting the X-WNS-TTL HTTP header to specify the time (in seconds) that your notification will remain valid after it is sent. For more information, see [Push notification service request and response headers](/previous-versions/windows/apps/hh465435(v=win.10)).
+Your cloud service can set an expiration for each notification by setting the X-WNS-TTL HTTP header to specify the time (in seconds) that your notification will remain valid after it is sent. For more information, see [Push notification service request and response headers](push-request-response-headers.md).
 
 For example, during a stock market's active trading day, you can set the expiration for a stock price update to twice that of your sending interval (such as one hour after receipt if you are sending notifications every half-hour). As another example, a news app might determine that one day is an appropriate expiration time for a daily news tile update.
 
@@ -281,12 +289,10 @@ This is the XAML for the [**ContentDialog**](/uwp/api/Windows.UI.Xaml.Controls.C
 
 ## Related topics
 
+* [Quickstart: Push notifications in the Windows App SDK](push-quickstart.md)
+* [Push notification service request and response headers](push-request-response-headers.md)
+* [How to request, create, and save a notification channel](request-create-save-notification-channel.md)
+* [WNS notification priorities](wns-notification-priorities.md)
+* [Raw notifications overview](raw-notification-overview.md)
+* [Troubleshoot push notifications](troubleshoot-notifications.md)
 * [Send a local tile notification](/windows/uwp/launch-resume/sending-a-local-tile-notification)
-* [Quickstart: Sending a push notification](/previous-versions/windows/apps/hh868252(v=win.10))
-* [How to update a badge through push notifications](/previous-versions/windows/apps/hh465450(v=win.10))
-* [How to request, create, and save a notification channel](/previous-versions/windows/apps/hh465412(v=win.10))
-* [How to intercept notifications for running applications](/previous-versions/windows/apps/jj709907(v=win.10))
-* [How to authenticate with the Windows Push Notification Service (WNS)](/previous-versions/windows/apps/hh465407(v=win.10))
-* [Push notification service request and response headers](/previous-versions/windows/apps/hh465435(v=win.10))
-* [Guidelines and checklist for push notifications]()
-* [Raw notifications](/previous-versions/windows/apps/hh761488(v=win.10))
