|
| 1 | +--- |
| 2 | +title: Using background tasks in Windows apps |
| 3 | +description: This article provides an overview of using background tasks and describes how to create a new background task in a WinUI app. |
| 4 | +ms.date: 01/05/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 app. |
| 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 previous [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 to be registered with Windows Runtime (WinRT) components that are to be 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 have to do a workaround of including the WinRT components in the project. This API avoids this workaround so WinUI and other desktop applications that use Windows App SDK can register the full trust COM components with the background tasks directly. |
| 20 | + |
| 21 | +## Register a background task |
| 22 | + |
| 23 | +The following code registers a background task for full trust COM component. You'll also need to set the **WindowsAppSDKBackgroundTask** property to **true** in the project configuration. Additionally, in the manifest file, the **EntryPoint** for **BackgroundTask** must be set to **Microsoft.Windows.ApplicationModel.Background.UniversalBGTask.Task**. |
| 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 | +## Related content |
| 62 | + |
| 63 | +[Guidelines for background tasks in UWP apps](/windows/uwp/launch-resume/guidelines-for-background-tasks) |
0 commit comments