Skip to content

Commit c6c5221

Browse files
committed
Updating content per email feedback
1 parent e7f290a commit c6c5221

1 file changed

Lines changed: 22 additions & 2 deletions

File tree

hub/apps/windows-app-sdk/applifecycle/background-tasks.md

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,17 @@ Background tasks are app components that run in the background without a user in
1616

1717
The implementation of background tasks is different for UWP and WinUI apps. 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).
1818

19+
[Task Scheduler](/windows/win32/api/_taskschd/) helps desktop apps achieve 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/).
20+
1921
## Register a background task
2022

2123
Use the [BackgroundTaskBuilder](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder) class included with the Windows App SDK to register a background task that uses full trust COM component.
2224

2325
The following example shows how to register a background task using C++. In the Windows App SDK github sample, you can see this registration code in [MainWindow.Xaml.cpp](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/BackgroundTask/InProc%20BackgroundTask/cpp-winui/BackgroundTaskBuilder/MainWindow.xaml.cpp#L82)
2426

2527
```cpp
28+
auto access = co_await BackgroundExecutionManager::RequestAccessAsync();
29+
2630
// Unregister all existing background task registrations
2731
auto allRegistrations = BackgroundTaskRegistration::AllTasks();
2832
for (const auto& taskPair : allRegistrations)
@@ -33,17 +37,28 @@ for (const auto& taskPair : allRegistrations)
3337

3438
//Using the Windows App SDK API for BackgroundTaskBuilder
3539
winrt::Microsoft::Windows::ApplicationModel::Background::BackgroundTaskBuilder builder;
40+
builder.Name(L"TimeZoneChangeTask");
3641
SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false);
3742
auto backgroundTrigger = trigger.as<IBackgroundTrigger>();
3843
builder.SetTrigger(backgroundTrigger);
3944
builder.AddCondition(SystemCondition(SystemConditionType::InternetAvailable));
40-
builder.SetTaskEntryPointClsid(__uuidof(winrt::BackgroundTaskBuilder::BackgroundTask));
41-
builder.Register();
45+
builder.SetTaskEntryPointClsid(__uuidof(winrt::BackgroundTaskInProcCPP::BackgroundTask));
46+
47+
try
48+
{
49+
builder.Register();
50+
}
51+
catch (...)
52+
{
53+
// Indicate an error was encountered.
54+
}
4255
```
4356

4457
The following example shows how to register a background task using C#. In the Windows App SDK github sample, you can see this registration code in [MainWindow.Xaml.cpp](https://github.com/microsoft/WindowsAppSDK-Samples/blob/main/Samples/BackgroundTask/InProc%20BackgroundTask/cs-winui/BackgroundTaskBuilder/MainWindow.xaml.cs#L79).
4558

4659
```csharp
60+
await BackgroundExecutionManager.RequestAccessAsync();
61+
4762
// Unregister all existing background task registrations
4863
var allRegistrations = BackgroundTaskRegistration.AllTasks;
4964
foreach (var taskPair in allRegistrations)
@@ -54,6 +69,7 @@ foreach (var taskPair in allRegistrations)
5469

5570
//Using the Windows App SDK API for BackgroundTaskBuilder
5671
var builder = new Microsoft.Windows.ApplicationModel.Background.BackgroundTaskBuilder();
72+
builder.Name = "TimeZoneChangeTask";
5773
var trigger = new SystemTrigger(SystemTriggerType.TimeZoneChange, false);
5874
var backgroundTrigger = trigger as IBackgroundTrigger;
5975
builder.SetTrigger(backgroundTrigger);
@@ -68,8 +84,12 @@ Note that the call to [SetEntryPointClsid](/windows/windows-app-sdk/api/winrt/mi
6884

6985
Use the following best practices when registering background tasks.
7086

87+
* Call [BackgroundExecutionManager.RequestAccessAsync](/uwp/api/windows.applicationmodel.background.backgroundexecutionmanager.requestaccessasync) before registering background tasks.
88+
7189
* Don't register a background task multiple times. Either verify that a background task isn't already registered before registering or, as in the Windows App SDK sample, unregister all background tasks and then reregister the tasks. Use the [BackgroundTaskRegistration](/uwp/api/windows.applicationmodel.background.backgroundtaskregistration) class to query for existing background tasks.
7290

91+
* Use the [BackgroundTaskBuilder.Name](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.background.backgroundtaskbuilder.name) property to specify a meaningful name for the background task to simplify debugging and maintenance.
92+
7393

7494

7595
## Implement IBackgroundTask

0 commit comments

Comments
 (0)