|
| 1 | +--- |
| 2 | +title: Using background tasks in Windows apps |
| 3 | +description: Get an overview of using background tasks and learn how to create a new background task in an app with the BackgroundTaskBuilder in Windows App SDK. |
| 4 | +ms.date: 03/19/2025 |
| 5 | +ms.topic: concept-article |
| 6 | +keywords: windows 11, winui, background task, app lifecycle, windows app sdk |
| 7 | +ms.localizationpriority: medium |
| 8 | +# customer intent: As a Windows developer, I want to learn about using background tasks in Windows apps. |
| 9 | +--- |
| 10 | + |
| 11 | +# Using background tasks in Windows apps |
| 12 | + |
| 13 | +This article provides an overview of using background tasks and describes how to create a new background task in a WinUI 3 app. For information about migrating your UWP apps with background tasks to WinUI, see the Windows App SDK [Background task migration strategy](../migrate-to-windows-app-sdk/guides/background-task-migration-strategy.md). |
| 14 | + |
| 15 | +## BackgroundTaskBuilder in the Windows App SDK |
| 16 | + |
| 17 | +Background tasks are app components that run in the background without a user interface. They can perform actions such as downloading files, syncing data, sending notifications, or updating tiles. They can be triggered by various events, such as time, system changes, user actions, or push notifications. These tasks can get executed when corresponding trigger occurs even when the app is not in running state. |
| 18 | + |
| 19 | +The Windows Runtime (WinRT) [BackgroundTaskBuilder](/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) was designed for UWP applications, and many of the background task triggers are not supported for full trust COM Components. They are supported only when registered with WinRT components that are launched with a `backgroundtaskhost` process. Due to this, Windows App SDK desktop applications can't directly register the full trust COM components to be launched with background task triggers. They require a workaround of including the WinRT components in the project. The [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder) in Windows App SDK API avoids this workaround so WinUI 3 and other desktop applications that use Windows App SDK can register the full trust COM components directly with background tasks. |
| 20 | + |
| 21 | +## Register a background task |
| 22 | + |
| 23 | +The following example registers a background task for a full trust COM component using the Windows App SDK [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder). See the [Background task migration strategy](../migrate-to-windows-app-sdk/guides/background-task-migration-strategy.md) guide for more information. |
| 24 | + |
| 25 | +The C++ code to create and register a background task is as follows: |
| 26 | + |
| 27 | +```cpp |
| 28 | +//Using the Windows App SDK API for BackgroundTaskBuilder |
| 29 | +winrt::Microsoft::Windows::ApplicationModel::Background::BackgroundTaskBuilder builder; |
| 30 | +SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false); |
| 31 | +auto backgroundTrigger = trigger.as<IBackgroundTrigger>(); |
| 32 | +builder.SetTrigger(backgroundTrigger); |
| 33 | +builder.AddCondition(SystemCondition(SystemConditionType::InternetAvailable)); |
| 34 | +builder.SetTaskEntryPointClsid(classGuid); |
| 35 | +builder.Register(); |
| 36 | +``` |
| 37 | + |
| 38 | +To create and register the background task in C#, the code is as follows: |
| 39 | + |
| 40 | +```csharp |
| 41 | +//Using the Windows App SDK API for BackgroundTaskBuilder |
| 42 | +var builder = new Microsoft.Windows.ApplicationModel.Background.BackgroundTaskBuilder(); |
| 43 | +var trigger = new SystemTrigger(SystemTriggerType.TimeZoneChange, false); |
| 44 | +var backgroundTrigger = trigger as IBackgroundTrigger; |
| 45 | +builder.SetTrigger(backgroundTrigger); |
| 46 | +builder.AddCondition(new SystemCondition(SystemConditionType.InternetAvailable)); |
| 47 | +builder.SetTaskEntryPointClsid(classGuid); |
| 48 | +builder.Register(); |
| 49 | +``` |
| 50 | + |
| 51 | +The corresponding package manifest entry for the background task is as follows: |
| 52 | + |
| 53 | +```xml |
| 54 | +<Extension Category="windows.backgroundTasks" EntryPoint="Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.Task"> |
| 55 | + <BackgroundTasks> |
| 56 | + <Task Type="general"/> |
| 57 | + </BackgroundTasks> |
| 58 | +</Extension> |
| 59 | +``` |
| 60 | + |
| 61 | +A full WinUI 3 background task registration sample can be found on [GitHub](https://github.com/microsoft/WindowsAppSDK-Samples/tree/release/experimental/Samples/BackgroundTask). |
| 62 | + |
| 63 | +## Related content |
| 64 | + |
| 65 | +- [Guidelines for background tasks in UWP apps](/windows/uwp/launch-resume/guidelines-for-background-tasks) |
| 66 | +- [Background task migration strategy](../migrate-to-windows-app-sdk/guides/background-task-migration-strategy.md) |
0 commit comments