BackgroundTaskBuilder BackgroundTaskBuilder BackgroundTaskBuilder BackgroundTaskBuilder Class

Represents a background task to be registered with the system.

Note

Starting in Windows 8.1, the parameters used to register the background task are validated at the time the task is registered. See the remarks for Register().

Syntax

Declaration

public sealed class BackgroundTaskBuilderpublic sealed class BackgroundTaskBuilderPublic NotInheritable Class BackgroundTaskBuilderpublic sealed class BackgroundTaskBuilder

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).

Constructors summary

Creates an instance of the BackgroundTaskBuilder class.

Properties summary

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

Indicates whether the background task requires network connectivity in order to run.

SocketActivityTrigger and ControlChannelTrigger are designed for apps that maintain long-lived network connections, even when they run in the background. Apps requiring short-lived network interactions as part of their background task’s logic (for example, sending out one HTTP request) may call directly into the core networking APIs ( HttpClient, StreamSocket, DatagramSocket, etc.) as long as they use the InternetAvailable condition with their background task or use the IsNetworkRequested flag on their background task registration. This tells the Background Tasks 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 InternetAvailable or IsNetworkRequested as described here, 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.)

Gets or sets the name of a background task.

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

Prerelease. Gets and sets the group identifier.

Methods summary

Adds a condition to a background task.

Registers a background task with the system.

Sets the event trigger for a background task.

Constructors

  • BackgroundTaskBuilder()
    BackgroundTaskBuilder()
    BackgroundTaskBuilder()
    BackgroundTaskBuilder()

    Creates an instance of the BackgroundTaskBuilder class.

    public BackgroundTaskBuilder()public New()Public Sub New()public BackgroundTaskBuilder()

Properties

  • CancelOnConditionLoss
    CancelOnConditionLoss
    CancelOnConditionLoss
    CancelOnConditionLoss

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

    public bool CancelOnConditionLoss { get; set; }public bool CancelOnConditionLoss { get; set; }Public ReadWrite Property CancelOnConditionLoss As boolpublic bool CancelOnConditionLoss { get; set; }

    Property Value

    • bool
      bool
      bool
      bool

      Whether or not the background task will be canceled if at least one of its required conditions is no longer met.

  • IsNetworkRequested
    IsNetworkRequested
    IsNetworkRequested
    IsNetworkRequested

    Indicates whether the background task requires network connectivity in order to run.

    SocketActivityTrigger and ControlChannelTrigger are designed for apps that maintain long-lived network connections, even when they run in the background. Apps requiring short-lived network interactions as part of their background task’s logic (for example, sending out one HTTP request) may call directly into the core networking APIs ( HttpClient, StreamSocket, DatagramSocket, etc.) as long as they use the InternetAvailable condition with their background task or use the IsNetworkRequested flag on their background task registration. This tells the Background Tasks 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 InternetAvailable or IsNetworkRequested as described here, 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.)

    public bool IsNetworkRequested { get; set; }public bool IsNetworkRequested { get; set; }Public ReadWrite Property IsNetworkRequested As boolpublic bool IsNetworkRequested { get; set; }

    Property Value

    • bool
      bool
      bool
      bool

      A value indicating whether network connectivity is requested.

  • Name
    Name
    Name
    Name

    Gets or sets the name of a background task.

    public string Name { get; set; }public string Name { get; set; }Public ReadWrite Property Name As stringpublic string Name { get; set; }

    Property Value

    • string
      string
      string
      string

      A description of the background task.

  • TaskEntryPoint
    TaskEntryPoint
    TaskEntryPoint
    TaskEntryPoint

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

    public string TaskEntryPoint { get; set; }public string TaskEntryPoint { get; set; }Public ReadWrite Property TaskEntryPoint As stringpublic string TaskEntryPoint { get; set; }

    Property Value

    • string
      string
      string
      string

      The name of an application-defined class that performs the work of a background task.

    Remarks

    Windows Store app using C++, C#, or Visual Basic The task entry point class must implement the IBackgroundTask interface. The system calls Run(IBackgroundTaskInstance) when the background task is triggered. In addition, the class must be specified in the <Extensions> section of the application's manifest as <Extension Category="windows.backgroundTasks" EntryPoint="appNamespace.appClassName">.The task entry point class can be implemented in the same process as the application's foreground component (in-proc); however, it cannot run on any of the application's foreground threads because the application might be suspended when the background task is triggered. For best results, implement the class in a separate process (out-of-proc) to decouple it from the application's foreground components and allow the system to manage the application's processes more efficiently.

    Windows Store app using JavaScript The entry point for a JavaScript background task is a JavaScript start page. See Current for more information.Note that JavaScript background tasks must call close() to terminate when they are done, so they don't continue to consume the user's memory and battery.

  • TaskGroup
    TaskGroup
    TaskGroup
    TaskGroup

    Prerelease. Gets and sets the group identifier.

    public BackgroundTaskRegistrationGroup TaskGroup { get; set; }public BackgroundTaskRegistrationGroup TaskGroup { get; set; }Public ReadWrite Property TaskGroup As BackgroundTaskRegistrationGrouppublic BackgroundTaskRegistrationGroup TaskGroup { get; set; }

    Property Value

    Remarks

    To reduce collisions with other group identifiers, consider including your domain name in the group identifier. For example: "com.contoso.appname.tasks". Or use the string form of a GUID.

Methods

  • AddCondition(IBackgroundCondition)
    AddCondition(IBackgroundCondition)
    AddCondition(IBackgroundCondition)
    AddCondition(IBackgroundCondition)

    Adds a condition to a background task.

    public void AddCondition(IBackgroundCondition condition)public void AddCondition(IBackgroundCondition condition)Public Function AddCondition(condition As IBackgroundCondition) As voidpublic void AddCondition(IBackgroundCondition condition)

    Parameters

    Remarks

    AddCondition(IBackgroundCondition) can be called more than once to specify more than one condition for a background task. All specified conditions must be met before the system will schedule the task.

  • Register()
    Register()
    Register()
    Register()

    Registers a background task with the system.

    public BackgroundTaskRegistration Register()public BackgroundTaskRegistration Register()Public Function Register() As BackgroundTaskRegistrationpublic BackgroundTaskRegistration Register()

    Returns

    Remarks

    The task must have an event trigger and a task entry point for the Register() method to succeed. The system schedules the background task when its trigger event occurs and all of its conditions have been met.

    Background task parameter validatio

    n

    Windows 8 Windows 8 does not validate the parameters set on the BackgroundTaskBuilder object until the system tries to run the background task. If the parameters aren't valid, the background task can't start and an event log entry is created.

    Windows 8.1 Starting in Windows 8.1, the parameters used to register the background task are validated at the time of registration. An error is returned if the background task registration fails, allowing the app to determine whether or not the background task is valid. For C# and Visual Basic, task registration errors typically result in specific .NET exceptions being thrown. These exceptions are thrown as first-chance exceptions and should be corrected while you're still developing your code.Existing Windows 8 apps running on Windows 8.1 are subject to this new system behavior, which can cause the app to crash if it can't handle a failed background task registration. (An event log entry will still be generated for the failed background task registration.) As a result, Windows 8 apps that register invalid background tasks should be rewritten to register background tasks correctly and to handle failed background task registration as a caught exception.

  • SetTrigger(IBackgroundTrigger)
    SetTrigger(IBackgroundTrigger)
    SetTrigger(IBackgroundTrigger)
    SetTrigger(IBackgroundTrigger)

    Sets the event trigger for a background task.

    public void SetTrigger(IBackgroundTrigger trigger)public void SetTrigger(IBackgroundTrigger trigger)Public Function SetTrigger(trigger As IBackgroundTrigger) As voidpublic void SetTrigger(IBackgroundTrigger trigger)

    Parameters

    Remarks

    In addition to specifying the type of event trigger for a background task, an application must also enable background tasks that use the event trigger type in the <Extensions><Extension><BackgroundTasks> section of its manifest. Valid types include the following:

    • <Task Type="audio"/>
    • <Task Type="timer"/>
    • <Task Type="systemEvent"/>
    • <Task Type="pushNotification"/>
    • <Task Type="realTimeCommunication"/>

    If the background task type is not specified or specified incorrectly in the manifest, calls that attempt to use that kind of background task will fail.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.ApplicationModel.Background.dll