|
| 1 | +--- |
| 2 | +title: Background task migration strategy |
| 3 | +description: Considerations and strategies for approaching the migration process, and how to migrate your UWP background tasks to use the Windows App SDK background task APIs. |
| 4 | +ms.topic: concept-article |
| 5 | +ms.date: 02/26/2025 |
| 6 | +keywords: Windows, App, SDK, migrate, migrating, migration, port, porting |
| 7 | +ms.localizationpriority: medium |
| 8 | +# customer intent: As a Windows developer, I want to learn about the considerations and strategies for migrating my UWP background tasks to use the Windows App SDK background task APIs. |
| 9 | +--- |
| 10 | + |
| 11 | +# Background task migration strategy |
| 12 | + |
| 13 | +Background tasks are used heavily in UWP apps for performing jobs when a particular trigger is invoked on the machine. As these don’t require any service to be running listening for the triggers, it's very power efficient. So, while migrating UWP apps to WinUI and other desktop apps that use Windows App SDK, developers may require support for implementing background tasks on the platform. |
| 14 | + |
| 15 | +Background tasks offered in the UWP app model can either be out-of-proc or in-proc. Below is the migration strategy for each of these types when moving to the Windows App SDK [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder) APIs. |
| 16 | + |
| 17 | +## Out-of-proc background tasks |
| 18 | + |
| 19 | +In the case of out-of-proc background tasks in UWP, background tasks will be written in a Windows Runtime (WinRT) component and the component would be given to [BackgroundTaskBuilder](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) as a [TaskEntryPoint](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder.taskentrypoint?view=winrt-26100) during registration. While migrating to Windows App SDK, developers can keep this as-is and package the WinRT component together with the desktop project. In this case, the broker infrastructure will be launching `backgroundtaskhost` process when the trigger is invoked, and the WinRT component background task would be executed in the process. In this approach, the background task would be running in a Low Integrity Level (IL) process (`backgroundtaskhost.exe`) while the main desktop project would be running in a Medium IL process. |
| 20 | + |
| 21 | +If the application needs both to run in a medium IL process, then full trust COM component needs to be used for background task. In that scenario, developers must go with [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder) API for successful registration of the full trust COM component. Note that the [BackgroundTaskBuilder](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) API from the **Windows.ApplicationModel.Background** namespace will throw exceptions while registering of some of the triggers. |
| 22 | + |
| 23 | +A background task registration sample can be found [here](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/experimental/Samples/BackgroundTask). |
| 24 | + |
| 25 | +More details on the implementation are available [here](/windows/uwp/launch-resume/create-and-register-a-winmain-background-task). The only required change would be to replace the WinRT [BackgroundTaskBuilder](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) API with the Windows App SDK API [Microsoft.Windows.ApplicationModel.Background.BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder). |
| 26 | + |
| 27 | +## In-proc background tasks |
| 28 | + |
| 29 | +In case of in-proc background tasks in UWP, background task routines are implemented in the [OnBackgroundActivated](/uwp/api/windows.ui.xaml.application.onbackgroundactivated) callback which runs as part of the foreground process. This won't be possible in a WinUI application as the **OnBackgroundActivated** callbacks aren't available. The application needs to move the background task implementations to full trust COM tasks as described above and define the COM server in the package manifest to handle the COM activation of the task. When the trigger occurs, COM activation will happen on the corresponding [COM Coclass](/windows/uwp/cpp-and-winrt-apis/author-coclasses#implement-the-coclass-and-class-factory) registered for the trigger. |
| 30 | + |
| 31 | +A background task registration sample can be found [here](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/experimental/Samples/BackgroundTask). |
| 32 | + |
| 33 | +More details on the implementation are available [here](/windows/uwp/launch-resume/create-and-register-a-winmain-background-task). Only change would be to replace the WinRT [BackgroundTaskBuilder](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) API with the Windows App SDK APIs in [Microsoft.Windows.ApplicationModel.Background.BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder). |
| 34 | + |
| 35 | +## Windows App SDK BackgroundTaskBuilder API |
| 36 | + |
| 37 | +This new API is created to support the full trust COM background task implementations in WinUI and other desktop applications using Windows App SDK, as the WinRT API throws exceptions during registration except for a few triggers. The following code shows how to register background task using Windows App SDK [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder) APIs: |
| 38 | + |
| 39 | +```cpp |
| 40 | +//Using Windows App SDK API for BackgroundTaskBuilder |
| 41 | +winrt::Microsoft::Windows::ApplicationModel::Background::BackgroundTaskBuilder builder; |
| 42 | +SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false); |
| 43 | +auto backgroundTrigger = trigger.as<IBackgroundTrigger>(); |
| 44 | +builder.SetTrigger(backgroundTrigger); |
| 45 | +builder.AddCondition(SystemCondition(SystemConditionType::InternetAvailable)); |
| 46 | +builder.SetTaskEntryPointClsid(classGuid); |
| 47 | +builder.Register(); |
| 48 | +``` |
| 49 | + |
| 50 | +Here is the equivalent C# code: |
| 51 | + |
| 52 | +```csharp |
| 53 | +// Using Windows App SDK API for BackgroundTaskBuilder |
| 54 | +var builder = new Microsoft.Windows.ApplicationModel.Background.BackgroundTaskBuilder(); |
| 55 | +var trigger = new SystemTrigger(SystemTriggerType.TimeZoneChange, false); |
| 56 | +builder.SetTrigger(trigger); |
| 57 | +builder.AddCondition(new SystemCondition(SystemConditionType.InternetAvailable)); |
| 58 | +builder.SetTaskEntryPointClsid(classGuid); |
| 59 | +builder.Register(); |
| 60 | +``` |
| 61 | + |
| 62 | +For using this API, developers would need to add a specific tag as below in their project file: |
| 63 | + |
| 64 | +``` xml |
| 65 | +<WindowsAppSDKBackgroundTask>true</WindowsAppSDKBackgroundTask> |
| 66 | +``` |
| 67 | + |
| 68 | +Also in the manifest file **EntryPoint** for **BackgroundTask** is set as **Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.Task**: |
| 69 | + |
| 70 | +``` xml |
| 71 | +<Extension Category="windows.backgroundTasks" EntryPoint="Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.Task"> |
| 72 | + <BackgroundTasks> |
| 73 | + <Task Type="general"/> |
| 74 | + </BackgroundTasks> |
| 75 | +</Extension> |
| 76 | +``` |
| 77 | + |
| 78 | +For C# applications, an **ActivatableClass** registration may also need to be added manually as below: |
| 79 | + |
| 80 | +```xml |
| 81 | +<Extension Category="windows.activatableClass.inProcessServer"> |
| 82 | + <InProcessServer> |
| 83 | + <Path>Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.dll</Path> |
| 84 | + <ActivatableClass ActivatableClassId="Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.Task" ThreadingModel="both"/> |
| 85 | + </InProcessServer> |
| 86 | +</Extension> |
| 87 | +``` |
| 88 | + |
| 89 | +## Leveraging TaskScheduler for background task migration |
| 90 | + |
| 91 | +[Task Scheduler](/windows/win32/api/_taskschd/) helps in achieving the same functionality that is provided by [BackgroundTaskBuilder](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) in UWP apps. More details on implementations using **TaskScheduler** are available [here](/windows/win32/api/taskschd/). |
| 92 | + |
| 93 | +## ApplicationTrigger use in Windows App SDK applications |
| 94 | + |
| 95 | +[ApplicationTrigger](/uwp/api/windows.applicationmodel.background.applicationtrigger) is supported in UWP applications due to the lifetime management scenario where the application process can be suspended. This scenario does not occur for WinUI and other Windows App SDK desktop applications, so this trigger is not supported in WinUI applications. All logic related to **ApplicationTrigger** will need to be rewritten to execute by launching another process or by running in a thread pool thread. For more information, see [CreateThread](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createthread) and [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessa). |
| 96 | + |
| 97 | +## Related content |
| 98 | + |
| 99 | +- [Using background tasks in Windows apps](/windows/apps/windows-app-sdk/applifecycle/background-tasks) |
| 100 | +- [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder) |
0 commit comments