BackgroundTaskBuilder Class

Reference

Definition

Namespace:: Windows.ApplicationModel.Background

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

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: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

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	Gets or sets a value that indicates whether the background task can run in standby mode.
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	Gets a value that indicates whether the device supports running background tasks in modern standby mode.
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)	Registers a background task with the specified task name with the system.
SetTaskEntryPointClsid(Guid)	Assigns a COM CLSID entry point using an existing BackgroundTaskBuilder object.
SetTrigger(IBackgroundTrigger)	Sets the event trigger for a background task.
Validate()	Validates the background task that has been configured with the SetTrigger method. This method is called by the system to determine whether the background task meets the requirements to run.

Applies to

Share via