From 9f5cf3ecdfb86054c0aca2215b50b2f3248a9a7f Mon Sep 17 00:00:00 2001 From: godlytalias Date: Wed, 23 Oct 2024 01:17:17 +0545 Subject: [PATCH 1/5] Added draft spec docs for backgroundtask Signed-off-by: godlytalias --- specs/BackgroundTask/BackgroundTaskBuilder.md | 101 ++++++++++++++++++ specs/WinRT/WinRTAPIContracts.md | 3 +- 2 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 specs/BackgroundTask/BackgroundTaskBuilder.md diff --git a/specs/BackgroundTask/BackgroundTaskBuilder.md b/specs/BackgroundTask/BackgroundTaskBuilder.md new file mode 100644 index 0000000000..c11a3d3076 --- /dev/null +++ b/specs/BackgroundTask/BackgroundTaskBuilder.md @@ -0,0 +1,101 @@ +BackgroundTaskBuilder API +=== + +This is the spec for BackgroundTaskBuilder API to support Background Task Registration for WinAppSDK apps. + +[Related Bug]( https://github.com/microsoft/WindowsAppSDK/issues/3840) + + +# Background +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. +Current [BackgroundTaskBuilder](https://learn.microsoft.com/en-us/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder) is designed for UWP applications and many of the Background Task triggers are not supported for full trust COM Components and are supported only to be registered with Windows Runtime components that is to be launched with backgroundtaskhost process. Due to this, WinAppSDK desktop applications won’t be able to directly register the full trust COM components to be launched with background task triggers and have to do workaround of including the Windows Runtime components in the project. +This API takes care of avoiding this workaround so that WinAppSDK applications can directly register the full trust COM components with the background tasks. + +# Conceptual pages (How To) + + ## Register Background Task (c++) + + Registering a Background Task for full trust COM component. Developers may also need to set the UniversalBGTask property as true in their project configuration. + + ```c++ + //Using WinAppSDK API for BackgroundTaskBuilder + winrt::Microsoft::Windows::ApplicationModel::Background::BackgroundTaskBuilder builder; + SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false); + auto backgroundTrigger = trigger.as(); + builder.SetTrigger(backgroundTrigger); + builder.SetTaskEntryPointClsid (classGuid); + builder.Register(); +``` + +# API Pages + +## BackgroundTaskBuilder class + +Represents a background task to register with the system. + +This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see [Threading and Marshaling (C++/CX)]( https://learn.microsoft.com/en-us/cpp/cppcx/threading-and-marshaling-c-cx?view=msvc-170 ) and [Using Windows Runtime objects in a multithreaded environment (.NET)]( https://learn.microsoft.com/en-us/windows/uwp/threading-async/using-windows-runtime-objects-in-a-multithreaded-environment) + + +## BackgroundTaskBuilder constructor + +| Name | Description | +|-|-| +| BackgroundTaskBuilder | Create a new BackgroundTaskBuilder object.| + + +## BackgroundTaskBuilder Properties + +| Name | Description | Value | +|-|-|-| +|Name| Gets or sets the name of a background task.|Name(A string representing name of the task) | +|TaskGroup| Gets and sets the group identifier.| TaskGroup (The group identifier.) | + + +## BackgroundTaskBuilder Methods + +| Name | Description | Parameters | Returns | +|-|-|-|-| +| AddCondition(IBackgroundCondition) | Adds a condition to a background task.| __IBackgroundCondition __ Condition for Background Task | | +| Register() | Registers a background task with the system.| | __BackgroundTaskRegistration __| + + + +# API Details + +> Note: all of this new WinAppSDK API is the same as the existing UWP API + [BackgroundTaskBuilder](https://learn.microsoft.com/en-us/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder), only changing the register operation internally to use WindowsRuntimeComponent for registration and then use the WindowsRuntimeComponent to activate the COM component of the application. +```c++ (but really MIDL3) +// Copyright (c) Microsoft Corporation and Contributors. +// Licensed under the MIT License. + +namespace Microsoft.Windows.ApplicationModel.Background +{ + [contractversion(1)] + apicontract BackgroundTaskContract{}; + + [contract(BackgroundTaskContract, 1)] + runtimeclass BackgroundTaskBuilder + { + BackgroundTaskBuilder(); + + void + SetTrigger( + Windows.ApplicationModel.Background.IBackgroundTrigger trigger + ); + void + SetTaskEntryPointClsId( + GUID clsId + ); + + + + String Name{ set; get; }; + + [return_name("task")] + Windows.ApplicationModel.Background.BackgroundTaskRegistration Register( + ); + } +} + +``` + diff --git a/specs/WinRT/WinRTAPIContracts.md b/specs/WinRT/WinRTAPIContracts.md index 639633cf49..c2fb1e7a78 100644 --- a/specs/WinRT/WinRTAPIContracts.md +++ b/specs/WinRT/WinRTAPIContracts.md @@ -101,10 +101,11 @@ additional information compared to the Windows App SDK version. The list of all contracts defined across Windows App SDK | Feature | Repository | Contract | Namespace | Comment | -|--------------------|---------------|---------------------------------|------------------------------------------------------|---------| +|--------------------|---------------|---------------------------------|----------------------------------------------------------------------------|---------| | AccessControl | windowsappsdk | AccessControlContract | Microsoft.Windows.Security.AccessControl | | | AppLifecycle | windowsappsdk | AppLifecycleContract | Microsoft.Windows.AppLifecycle | | | AppNotifications | windowsappsdk | AppNotificationsContract | Microsoft.Windows.AppNotifications | | +| BackgroundTask | windowsappsdk | BackgroundTaskContract | Microsoft.Windows.ApplicationModel.Background | | | Deployment | windowsappsdk | DeploymentManagerContract | Microsoft.Windows.ApplicationModel.WindowsAppRuntime | | | DynamicDependency | windowsappsdk | DynamicDependencyContract | Microsoft.Windows.ApplicationModel.DynamicDependency | | | EnvironmentManager | windowsappsdk | EnvironmentManagerContract | Microsoft.Windows.System | | From d566cbf950121cff6fb22a7f2f07d45c7c720716 Mon Sep 17 00:00:00 2001 From: "Godly T.Alias" Date: Thu, 24 Oct 2024 00:52:43 +0545 Subject: [PATCH 2/5] Update BackgroundTaskBuilder.md --- specs/BackgroundTask/BackgroundTaskBuilder.md | 21 ++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/specs/BackgroundTask/BackgroundTaskBuilder.md b/specs/BackgroundTask/BackgroundTaskBuilder.md index c11a3d3076..4cedd3a22b 100644 --- a/specs/BackgroundTask/BackgroundTaskBuilder.md +++ b/specs/BackgroundTask/BackgroundTaskBuilder.md @@ -3,7 +3,7 @@ BackgroundTaskBuilder API This is the spec for BackgroundTaskBuilder API to support Background Task Registration for WinAppSDK apps. -[Related Bug]( https://github.com/microsoft/WindowsAppSDK/issues/3840) +[Related Bug Report]( https://github.com/microsoft/WindowsAppSDK/issues/3840) # Background @@ -23,7 +23,7 @@ This API takes care of avoiding this workaround so that WinAppSDK applications c SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false); auto backgroundTrigger = trigger.as(); builder.SetTrigger(backgroundTrigger); - builder.SetTaskEntryPointClsid (classGuid); + builder.SetTaskEntryPointClsid(classGuid); builder.Register(); ``` @@ -55,8 +55,8 @@ This class is not agile, which means that you need to consider its threading mod | Name | Description | Parameters | Returns | |-|-|-|-| -| AddCondition(IBackgroundCondition) | Adds a condition to a background task.| __IBackgroundCondition __ Condition for Background Task | | -| Register() | Registers a background task with the system.| | __BackgroundTaskRegistration __| +| AddCondition(IBackgroundCondition) | Adds a condition to a background task.| __IBackgroundCondition__ Condition for Background Task | | +| Register() | Registers a background task with the system.| | __BackgroundTaskRegistration__| @@ -78,22 +78,19 @@ namespace Microsoft.Windows.ApplicationModel.Background { BackgroundTaskBuilder(); - void - SetTrigger( + void SetTrigger( Windows.ApplicationModel.Background.IBackgroundTrigger trigger ); - void - SetTaskEntryPointClsId( + void SetTaskEntryPointClsId( GUID clsId ); - - String Name{ set; get; }; [return_name("task")] - Windows.ApplicationModel.Background.BackgroundTaskRegistration Register( - ); + Windows.ApplicationModel.Background.BackgroundTaskRegistration Register(); + [return_name("task")] + Windows.ApplicationModel.Background.BackgroundTaskRegistration Register(String name); } } From e3880d9c1b84915aef0eeb6b671a361e19ca753a Mon Sep 17 00:00:00 2001 From: godlytalias Date: Tue, 29 Oct 2024 17:04:31 +0530 Subject: [PATCH 3/5] Updated specs Signed-off-by: godlytalias --- specs/BackgroundTask/BackgroundTaskBuilder.md | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/specs/BackgroundTask/BackgroundTaskBuilder.md b/specs/BackgroundTask/BackgroundTaskBuilder.md index 4cedd3a22b..3a9bc3fb76 100644 --- a/specs/BackgroundTask/BackgroundTaskBuilder.md +++ b/specs/BackgroundTask/BackgroundTaskBuilder.md @@ -15,7 +15,7 @@ This API takes care of avoiding this workaround so that WinAppSDK applications c ## Register Background Task (c++) - Registering a Background Task for full trust COM component. Developers may also need to set the UniversalBGTask property as true in their project configuration. + Registering a Background Task for full trust COM component. Developers may also need to set the **WindowsAppSDKUniversalBGTask** property as true in their project configuration. ```c++ //Using WinAppSDK API for BackgroundTaskBuilder @@ -33,7 +33,7 @@ This API takes care of avoiding this workaround so that WinAppSDK applications c Represents a background task to register with the system. -This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see [Threading and Marshaling (C++/CX)]( https://learn.microsoft.com/en-us/cpp/cppcx/threading-and-marshaling-c-cx?view=msvc-170 ) and [Using Windows Runtime objects in a multithreaded environment (.NET)]( https://learn.microsoft.com/en-us/windows/uwp/threading-async/using-windows-runtime-objects-in-a-multithreaded-environment) +This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see [Agile Objects in C++/WinRT](https://learn.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/agile-objects), [Threading and Marshaling (C++/CX)]( https://learn.microsoft.com/en-us/cpp/cppcx/threading-and-marshaling-c-cx?view=msvc-170 ) and [Using Windows Runtime objects in a multithreaded environment (.NET)]( https://learn.microsoft.com/en-us/windows/uwp/threading-async/using-windows-runtime-objects-in-a-multithreaded-environment) ## BackgroundTaskBuilder constructor @@ -47,8 +47,8 @@ This class is not agile, which means that you need to consider its threading mod | Name | Description | Value | |-|-|-| -|Name| Gets or sets the name of a background task.|Name(A string representing name of the task) | -|TaskGroup| Gets and sets the group identifier.| TaskGroup (The group identifier.) | +|Name| Gets or sets the name of a background task.| Name (A string representing name of the task) | +|TaskGroup| Gets and sets the group identifier.| TaskGroup (The group identifier for the task) | ## BackgroundTaskBuilder Methods @@ -57,6 +57,9 @@ This class is not agile, which means that you need to consider its threading mod |-|-|-|-| | AddCondition(IBackgroundCondition) | Adds a condition to a background task.| __IBackgroundCondition__ Condition for Background Task | | | Register() | Registers a background task with the system.| | __BackgroundTaskRegistration__| +| Register(String) | Registers a background task with the system.| __String__ Name for the task | __BackgroundTaskRegistration__| +| SetTaskEntryPointClsId(GUID) | Assigns a COM CLSID entry point using an existing BackgroundTaskBuilder object. | __GUID__ GUID of the Entry point class | | +| SetTrigger(IBackgroundTrigger) | Sets the event trigger for a background task. | __IBackgroundTrigger__ Trigger for Background Task | | @@ -64,7 +67,7 @@ This class is not agile, which means that you need to consider its threading mod > Note: all of this new WinAppSDK API is the same as the existing UWP API [BackgroundTaskBuilder](https://learn.microsoft.com/en-us/uwp/api/windows.applicationmodel.background.backgroundtaskbuilder), only changing the register operation internally to use WindowsRuntimeComponent for registration and then use the WindowsRuntimeComponent to activate the COM component of the application. -```c++ (but really MIDL3) +```c# (but really MIDL3) // Copyright (c) Microsoft Corporation and Contributors. // Licensed under the MIT License. @@ -81,16 +84,19 @@ namespace Microsoft.Windows.ApplicationModel.Background void SetTrigger( Windows.ApplicationModel.Background.IBackgroundTrigger trigger ); - void SetTaskEntryPointClsId( + + void + SetTaskEntryPointClsId( GUID clsId ); String Name{ set; get; }; - [return_name("task")] - Windows.ApplicationModel.Background.BackgroundTaskRegistration Register(); - [return_name("task")] - Windows.ApplicationModel.Background.BackgroundTaskRegistration Register(String name); + Windows.ApplicationModel.Background.BackgroundTaskRegistration Register( + ); + Windows.ApplicationModel.Background.BackgroundTaskRegistration Register( + String taskName + ); } } From 921ffaeed43010a45dfbfc21fafbdb20e0d0cf57 Mon Sep 17 00:00:00 2001 From: godlytalias Date: Tue, 29 Oct 2024 18:45:12 +0530 Subject: [PATCH 4/5] Added AddCondition method Signed-off-by: godlytalias --- specs/BackgroundTask/BackgroundTaskBuilder.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specs/BackgroundTask/BackgroundTaskBuilder.md b/specs/BackgroundTask/BackgroundTaskBuilder.md index 3a9bc3fb76..2ddb3b1b3a 100644 --- a/specs/BackgroundTask/BackgroundTaskBuilder.md +++ b/specs/BackgroundTask/BackgroundTaskBuilder.md @@ -23,6 +23,7 @@ This API takes care of avoiding this workaround so that WinAppSDK applications c SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false); auto backgroundTrigger = trigger.as(); builder.SetTrigger(backgroundTrigger); + builder.AddCondition(backgroundTaskCondition); builder.SetTaskEntryPointClsid(classGuid); builder.Register(); ``` @@ -85,6 +86,10 @@ namespace Microsoft.Windows.ApplicationModel.Background Windows.ApplicationModel.Background.IBackgroundTrigger trigger ); + void AddCondition( + winrt::Windows::ApplicationModel::Background::IBackgroundCondition trigger + ); + void SetTaskEntryPointClsId( GUID clsId From 890b0ba7c4ab9c10d3e6ae166300f661d1aeb1d7 Mon Sep 17 00:00:00 2001 From: godlytalias Date: Wed, 30 Oct 2024 15:51:34 +0530 Subject: [PATCH 5/5] Updated specs with feedbacks received Signed-off-by: godlytalias --- specs/BackgroundTask/BackgroundTaskBuilder.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specs/BackgroundTask/BackgroundTaskBuilder.md b/specs/BackgroundTask/BackgroundTaskBuilder.md index 2ddb3b1b3a..e77b4ef0e0 100644 --- a/specs/BackgroundTask/BackgroundTaskBuilder.md +++ b/specs/BackgroundTask/BackgroundTaskBuilder.md @@ -15,7 +15,7 @@ This API takes care of avoiding this workaround so that WinAppSDK applications c ## Register Background Task (c++) - Registering a Background Task for full trust COM component. Developers may also need to set the **WindowsAppSDKUniversalBGTask** property as true in their project configuration. + Registering a Background Task for full trust COM component. Developers may also need to set the **WindowsAppSDKBackgroundTask** property as true in their project configuration. ```c++ //Using WinAppSDK API for BackgroundTaskBuilder @@ -23,7 +23,7 @@ This API takes care of avoiding this workaround so that WinAppSDK applications c SystemTrigger trigger = SystemTrigger(SystemTriggerType::TimeZoneChange, false); auto backgroundTrigger = trigger.as(); builder.SetTrigger(backgroundTrigger); - builder.AddCondition(backgroundTaskCondition); + builder.AddCondition(SystemCondition(SystemConditionType::InternetAvailable)); builder.SetTaskEntryPointClsid(classGuid); builder.Register(); ``` @@ -48,8 +48,8 @@ This class is not agile, which means that you need to consider its threading mod | Name | Description | Value | |-|-|-| -|Name| Gets or sets the name of a background task.| Name (A string representing name of the task) | -|TaskGroup| Gets and sets the group identifier.| TaskGroup (The group identifier for the task) | +|Name| Gets or sets the name of a background task.| __String__ (A string representing name of the task) | +|TaskGroup| Gets and sets the group identifier so that background task registration can be maintained separately.| __BackgroundTaskRegistrationGroup__ (The group identifier for the task) | ## BackgroundTaskBuilder Methods @@ -59,7 +59,7 @@ This class is not agile, which means that you need to consider its threading mod | AddCondition(IBackgroundCondition) | Adds a condition to a background task.| __IBackgroundCondition__ Condition for Background Task | | | Register() | Registers a background task with the system.| | __BackgroundTaskRegistration__| | Register(String) | Registers a background task with the system.| __String__ Name for the task | __BackgroundTaskRegistration__| -| SetTaskEntryPointClsId(GUID) | Assigns a COM CLSID entry point using an existing BackgroundTaskBuilder object. | __GUID__ GUID of the Entry point class | | +| SetTaskEntryPointClsid(GUID) | Assigns a COM CLSID entry point using an existing BackgroundTaskBuilder object. | __GUID__ GUID of the Entry point class | | | SetTrigger(IBackgroundTrigger) | Sets the event trigger for a background task. | __IBackgroundTrigger__ Trigger for Background Task | | @@ -91,7 +91,7 @@ namespace Microsoft.Windows.ApplicationModel.Background ); void - SetTaskEntryPointClsId( + SetTaskEntryPointClsid( GUID clsId );