BackgroundTaskBuilder Class

Definition

Represents a background task to register with the system.

public ref class BackgroundTaskBuilder sealed
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Standard)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
class BackgroundTaskBuilder final
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Standard)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundTaskBuilder final
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Standard)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
public sealed class BackgroundTaskBuilder
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Standard)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundTaskBuilder
function BackgroundTaskBuilder()
Public NotInheritable Class BackgroundTaskBuilder
Inheritance
Object Platform::Object IInspectable BackgroundTaskBuilder
Attributes

Windows requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)

Remarks

Note

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) and Using Windows Runtime objects in a multithreaded environment (.NET).

If your background task requires network connectivity, be aware of the following:

** Network related triggers**

  • Use a SocketActivityTrigger to activate the background task when a packet is received and you need to perform a short-lived task. After performing the task, the background task should terminate to save power.
  • Use a ControlChannelTrigger to activate the background task when a packet is received and you need to perform a long-lived task.

** Network related conditions and flags**

  • Add the InternetAvailable condition (BackgroundTaskBuilder.AddCondition) to your background task to delay triggering the background task until the network stack is running. This condition saves power because the background task won't execute until network access is available. This condition does not provide real-time activation.

Regardless of the trigger you use, set IsNetworkRequested on your background task to ensure that the network stays up while the background task runs. This tells the background task infrastructure to keep the network up while the task is executing, even if the device has entered Connected Standby mode. If your background task does not use IsNetworkRequested, then your background task will not be able to access the network when in Connected Standby mode (for example, when a phone's screen is turned off.)

Version history

Windows version SDK version Value added
1703 15063 TaskGroup
2004 19041 SetTaskEntryPointClsid

Constructors

BackgroundTaskBuilder()

Creates an instance of the BackgroundTaskBuilder class.

Properties

AllowRunningTaskInStandby
CancelOnConditionLoss

Indicates whether the background task will be canceled if at least one of its required conditions is no longer met.

IsNetworkRequested

Indicates whether to keep the network up while running the background task.

IsRunningTaskInStandbySupported
Name

Gets or sets the name of a background task.

TaskEntryPoint

Gets or sets the class that performs the work of a background task.

TaskGroup

Gets and sets the group identifier.

Methods

AddCondition(IBackgroundCondition)

Adds a condition to a background task.

Register()

Registers a background task with the system.

Register(String)
SetTaskEntryPointClsid(Guid)

Assigns a COM CLSID entry point using an existing BackgroundTaskBuilder object.

SetTrigger(IBackgroundTrigger)

Sets the event trigger for a background task.

Validate()

Applies to