DeviceServicingTrigger 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 an event that an application can trigger to initiate a long-running update (firmware or settings) of a device.

Windows 8.1 enables you to develop UWP app for your peripheral devices that communicate over USB, HID, and Bluetooth. For example, a user might need to sync content on a PC to or from the device, or perform a long-running update to the device itself like settings or firmware updates. Windows 8.1 provides two background tasks and corresponding APIs that allow your device to sync and update in the background: DeviceServicingTrigger and DeviceUseTrigger. This topic provides API reference information for DeviceServicingTrigger - for info on using this trigger in the context of a device app, see Device sync and update for UWP device apps.

The DeviceServicingTrigger background task allows your UWP app that interacts with your peripheral device to perform long running device updates while your app is suspended, for example settings transfers or firmware updates. Updating your device in the background requires user approval each time the background task is used. Unlike the DeviceUseTrigger background task, the DeviceServicingTrigger background task allows for device reboot and disconnect and allows a maximum of 30 minutes of background activity.

More detail on the policy requirements of the DeviceServicingTrigger background task can be found in the section of this page.
For info about using the DeviceServicingTrigger, see Device sync and update for UWP device apps.
For info about using the DeviceUseTrigger, see Accessing sensors and devices from a background task.

Important

This trigger cannot be used with single-process background tasks.

public ref class DeviceServicingTrigger 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.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class DeviceServicingTrigger final

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class DeviceServicingTrigger 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.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class DeviceServicingTrigger

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class DeviceServicingTrigger

function DeviceServicingTrigger()

Public NotInheritable Class DeviceServicingTrigger

Inheritance: Object Platform::Object IInspectable DeviceServicingTrigger

Attributes: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements: IBackgroundTrigger

Windows requirements

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

Remarks

Certain policies are enforced by Windows to ensure user consent when updating their peripheral devices. Additional polices are enforced to preserve user battery life when syncing and updating peripheral devices. The DeviceServicingTrigger background task is subject to the following policies:

The DeviceServicingTrigger background task requires user consent every time it's triggered.
Your device must be connected or paired with the PC and available when requesting the DeviceServicingTrigger.
Your app is allowed a maximum of 30 minutes (wall clock) of background activity for device updates with DeviceServicingTrigger
Your app is not allowed to request a DeviceServicingTrigger background task while your app is not in the foreground.
Your app can only run one DeviceServicingTrigger at a time. Attempting to create a second DeviceServicingTrigger will raise an exception.
The PC's battery must have more than 33% capacity remaining, or the PC must be on A/C power.
DeviceServicingTrigger background tasks may be canceled by Windows when these policy requirements are no longer met, including a maximum amount of wall clock background time.

Note

UWP app that intend to use the DeviceServicingTrigger background task must also be a privileged app for the device. App privilege is specified in the device metadata for a peripheral device by the device manufacturer. When a UWP app attempts to trigger the DeviceServicingTrigger background task, Windows will validate that the calling app is the privileged app for the device it is attempting to update. If the app is not privileged for the device then Windows will not allow the background task to launch.

For detailed information about app privilege and the policy checks enforced by Windows for the DeviceServicingTrigger background task see Device sync and update for UWP device apps.

Constructors

DeviceServicingTrigger()

Constructor for DeviceServicingTrigger. Takes no parameters.

Methods

RequestAsync(String, TimeSpan, String)

Triggers the background task (settings or firmware update) and returns a DeviceTriggerResult indicating success or failure of the trigger request. Takes the DeviceInformation.ID string, an optional estimated time the background task will run, and an optional app-specific string passed to the background task identifying which device operation to perform. If your app cannot determine an appropriate time estimate, provide zero as the estimated time.

RequestAsync(String, TimeSpan)

Triggers the background task (settings or firmware update) and returns a DeviceTriggerResult indicating success or failure of the trigger request. Takes the DeviceInformation.ID string and an optional estimated time the background task will run. If your app cannot determine an appropriate time estimate, provide zero as the estimated time.

Applies to

Share via