Can a packaged with external location WinUI 2 (C++/WinRT) application receive WNS Raw Notifications via a background task?

Question

Can a packaged with external location WinUI 2 (C++/WinRT) application receive WNS Raw Notifications via a background task?

Rohan Pande 515

Hi,

I'm trying to implement background processing triggered by WNS Raw Notifications, similar to what is described in the Microsoft documentation here - https://learn.microsoft.com/en-us/windows/apps/develop/notifications/push-notifications/raw-notification-overview#background-tasks-triggered-by-raw-notifications

My application has the following characteristics:

Win32 desktop application
WinUI 2 (XAML hosted)
C++/WinRT
Package with external location
Does not use the Windows App SDK
Not a UWP application

The Microsoft documentation explains how a UWP application can register a PushNotificationTrigger background task so that a Raw Notification can wake the app even when it isn't running.

However, I haven't found any documentation describing whether this is supported for package with external location application using WinUI 2.

My goal is:

Register with WNS and obtain a notification channel.
Receive a WNS Raw Notification while the application is not running.
Execute some background code without launching the application's UI.

Questions?

Is PushNotificationTrigger supported for a package with external location Win32 application?
If so, can someone point me to the required registration steps or a sample would also help?

0 comments

Answer accepted by question author

0 additional answers

Your answer

Answer 1

Taki Ly (WICLOUD CORPORATION) 4,615 Microsoft External Staff Moderator

Hello @Rohan Pande ,

Thank you for providing such a clear description of your scenario.

PushNotificationTrigger is supported for packaged with external location Win32 applications, but the implementation differs significantly from the standard UWP approach. Because your application is a Win32 desktop app, it typically cannot use the UWP in-process background task model natively in the same way. Instead, Windows expects you to implement an Out-of-Process COM Server to receive the raw notification when the application is not already running.

To achieve this, you might consider the following approach:

1. Implement the Background Task via C++/WinRT COM

Your application needs to implement the IBackgroundTask interface and register it as an out-of-process COM server. When a raw notification arrives while the app is closed, Windows will launch your executable with a -BackgroundTask command-line argument.

You can intercept this argument in your WinMain to instantiate the COM class factory instead of initializing your XAML UI, allowing you to run pure background code.

Example structure:

#include <windows.h>
#include <unknwn.h> // Must be strictly included before winrt headers
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.ApplicationModel.Background.h>
#include <winrt/Windows.Networking.PushNotifications.h>
using namespace winrt::Windows::ApplicationModel::Background;
struct PushTask : winrt::implements<PushTask, IBackgroundTask>
{
    void Run(IBackgroundTaskInstance const& taskInstance)
    {
        // Execute your background code here without UI
    }
};
class PushTaskFactory : public winrt::implements<PushTaskFactory, winrt::non_agile, IClassFactory>
{
public:
    HRESULT __stdcall CreateInstance(IUnknown* outer, GUID const& iid, void** result) noexcept override
    {
        *result = nullptr;
        if (outer) return CLASS_E_NOAGGREGATION;
        try {
            *result = winrt::detach_abi(winrt::make<PushTask>());
            return S_OK;
        } catch (...) { return winrt::to_hresult(); }
    }
    HRESULT __stdcall LockServer(BOOL) noexcept override { return S_OK; }
};

2. Update your AppxManifest.xml

For the OS to map the windows.backgroundTasks extension to your COM Server, you would define a CLSID and map it to your executable.

For packaged with external location apps, deploying via MSBuild may occasionally throw validation errors regarding inProcessServer requirements depending on the toolset version. You can manually register the manifest using PowerShell (Add-AppxPackage -Register), bridging it to the COM Server:

<Extensions>
  <Extension Category="windows.backgroundTasks" EntryPoint="YOUR-GUID-HERE">
    <BackgroundTasks>
      <Task Type="pushNotification" />
    </BackgroundTasks>
  </Extension>
  <com:Extension Category="windows.comServer">
    <com:ComServer>
      <com:ExeServer Executable="YourApp.exe" DisplayName="Push Notification server">
        <com:Class Id="YOUR-GUID-HERE" DisplayName="Push Task" />
      </com:ExeServer>
    </com:ComServer>
  </com:Extension>
  <!-- Depending on your OS build validation, an empty dummy inProcessServer declaration might be required by the parser to bypass Win32 schema validations -->
  <Extension Category="windows.activatableClass.inProcessServer" xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10">
      <InProcessServer>
          <Path>dummy.dll</Path>
          <ActivatableClass ActivatableClassId="YOUR-GUID-HERE" ThreadingModel="both" />
      </InProcessServer>
  </Extension>
</Extensions>

3. Register the task at runtime

Even with the manifest declared, the OS requires the runtime registration to route the push payloads. When the app is launched interactively (with UI), you would request access and register the trigger:

auto accessStatus = BackgroundExecutionManager::RequestAccessAsync().get();
PushNotificationTrigger pushTrigger;
BackgroundTaskBuilder builder;
builder.Name(L"PushBackgroundTask");
builder.SetTrigger(pushTrigger);
// The task entry point must strictly match the CLSID in your manifest
builder.TaskEntryPoint(L"YOUR-GUID-HERE"); 
BackgroundTaskRegistration registration = builder.Register();

For further reading on background tasks and identity mapping, you can refer to:

I hope this points you in the right direction. Please let me know if you have any questions or run into unexpected validation issues during your deployment testing issues. If you found my response helpful or informative, I would greatly appreciate it if you could follow this guide for your confirmation.

Thank you.

Rohan Pande 515 Reputation points

2026-07-24T16:59:21.23+00:00

We implemented the out-of-process COM server approach as suggested. The background task registers successfully via BackgroundTaskBuilder::Register(), however BackgroundExecutionManager::RequestAccessAsync() consistently returns 5 (DeniedByUser).

The app is a Win32 desktop application using a package with external location (uap10:AllowExternalContent). It does not appear in Windows Settings → Installed Apps, so there is no way for the user to manually grant background access.

As a result, Windows never activates the com:ExeServer to launch the exe when a push notification arrives while the app is closed.

How can we resolve the DeniedByUser status for a packaged with external location desktop app?
Rohan Pande 515 Reputation points

2026-07-25T05:53:09.78+00:00

Just want to give an update regarding this I was able to see my app is getting triggered by COM but its going in suspended state

This is what's my current understanding please let me know if I am wrong:

When the app is already running with a visible window and a raw push notification arrives, Windows does not route it through the in-process PushNotificationReceived event handler. Instead, it attempts COM activation via the com:ExeServer manifest entry, applying PLM (Process Lifecycle Management) suspension to the running process. The app moves from "Apps" to "Background processes (Suspended)" in Task Manager, the UI freezes, and the notification payload is lost.

The PushNotificationReceived handler with Cancel(true) never fires — the COM activation path takes priority over the in-process channel event.

This creates a deadlock: removing com:ExeServer prevents background task activation when the app is closed, but keeping it causes the running app to be suspended when a notification arrives.

For a packaged with external location Win32 desktop app (uap10:AllowExternalContent), how should com:ExeServer and PushNotificationTrigger be configured so that push notifications are handled in-process when the app is running, and via COM background task only when the app is closed?
Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-07-27T07:06:21.56+00:00
Hi @Rohan Pande ,

I would suggest decoupling the COM server into a separate executable (e.g., BackgroundPushTask.exe) to potentially prevent the main UI process from being suspended during a COM activation. By routing the activation to a secondary process, the active UI might remain unaffected.

A possible approach could follow these steps:

Update the com:ExeServer attribute in the AppxManifest.xml to point to the new BackgroundPushTask.exe rather than the main application.

Within the Run method of the BackgroundPushTask.exe, one might check if the main UI application is currently running.

If the main UI is active, the raw notification payload could be forwarded to the UI process using standard Win32 IPC (such as Named Pipes or WM_COPYDATA), after which the background process could exit.

If the main UI is closed, the background task might process the payload silently or initiate the main application.

Regarding the 5 (DeniedByUser) status from RequestAccessAsync(), sparse packages often lack full integration with the standard Windows Privacy settings for Background Apps, which could cause the API to default to a denied state. Since the COM background task appears to trigger successfully despite this response, I think it might be viable to ignore the API's return status for a packaged with external location desktop application.

For reference on implementing IPC and managing out-of-process background tasks, I recommend reviewing these resources:

Interprocess Communications (IPC) in Windows

Create and register an out-of-process background task

I hope exploring this decoupled architecture might offer a viable direction for resolving the PLM suspension behavior in your scenario.

Thank you.
Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-07-29T10:33:42.29+00:00

Hi @Rohan Pande ,

Do you have any new updates on this post? If you have any question, feel free to reach out.
Rohan Pande 515 Reputation points

2026-08-04T05:47:38.96+00:00
After having a valid dummy.dll I tried running the application but when I checked the Windows Event Logs found this error: Background task activation failed with 0x800401F9 (CO_E_ERRORINDLL— "Error in the DLL").

The entry point was declared as a WinRT in-process activation (windows.backgroundTasks in the manifest + builder.TaskEntryPoint(clsid) in code), which made Windows try to load an in-process DLL (dummy.dll) that doesn't really exist. But the app actually activates via classic out-of-process COM (com:Extension/windows.comServer), so the two registrations conflicted.

Then I found a Microsoft's sample for this scenario uses only com:Extension/windows.comServer in the manifest, with nowindows.backgroundTasks declaration -- the entry point is set purely in code via SetTaskEntryPointClsid.

Reference: https://learn.microsoft.com/en-us/windows/uwp/launch-resume/create-and-register-a-winmain-background-task

TaskEntryPoint is for WinRT in-process tasks. SetTaskEntryPointClsid is the correct API for classic out-of-process COM activation in packaged Win32 apps.

So, I removed the two blocks from appxmanifest file

<Extension Category="windows.backgroundTasks" EntryPoint="..."> and <Extension Category="windows.activatableClass.inProcessServer">` (the dummy.dll entry)

Note : Only COM server block is present in appxmanifest file.

And in code I replace the API

builder.SetTaskEntryPointClsid(winrt::guid(CLSID_PushTask));

Result: Background task now activates correctly when the app is closed and once after processing even displays toast notification

Can you confirm this is the intended pattern is right or wrong -- that windows.backgroundTasks + windows.activatableClass.inProcessServeris only for WinRT in-process tasks, and out-of-process COM background tasks should skip that extension entirely in favor of SetTaskEntryPointClsid?
Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-08-04T06:47:32.02+00:00

Hi @Rohan Pande ,

Thank you for sharing your findings and for taking the time to document your investigation in detail.

Based on the Win32 COM background task sample you referenced, I can see that your revised implementation using windows.comServer together with BackgroundTaskBuilder.SetTaskEntryPointClsid(...) is consistent with the sample implementation, and it appears to have resolved the background task activation issue in your testing. Specifically, you were able to successfully activate the background task when the application was closed and display a toast notification after processing.

At this point, I am unable to officially confirm whether this represents the intended design pattern for all supported scenarios, as I do not have access to internal product engineering design guidance. However, your findings do appear to align with the publicly available Win32 COM background task sample that uses COM server registration and SetTaskEntryPointClsid(...) for task activation.

Thank you again for sharing the root cause analysis and final implementation details. If the information shared throughout this discussion was helpful during your investigation, I would greatly appreciate it if you could follow this guide for your confirmation, as this helps highlight the solution and makes it easier for other developers facing a similar issue to discover the relevant guidance and findings from this thread.

Thank you.
Taki Ly (WICLOUD CORPORATION) 4,615 Reputation points Microsoft External Staff Moderator

2026-08-06T10:37:18.4533333+00:00

Hi @Rohan Pande ,

Have you seen my follow-up in this post? If you have any question, feel free to reach out.