Device​Servicing​Trigger Device​Servicing​Trigger Device​Servicing​Trigger Class

Definition

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 Windows Store 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 Windows Store device apps.

The DeviceServicingTrigger background task allows your Windows Store 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.

public : sealed class DeviceServicingTrigger : IBackgroundTrigger, IDeviceServicingTriggerpublic sealed class DeviceServicingTrigger : IBackgroundTrigger, IDeviceServicingTriggerPublic NotInheritable Class DeviceServicingTrigger Implements IBackgroundTrigger, IDeviceServicingTrigger
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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] > Windows Store 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 Windows Store 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 Windows Store device apps.

Constructors

DeviceServicingTrigger() DeviceServicingTrigger() DeviceServicingTrigger()

Constructor for DeviceServicingTrigger. Takes no parameters.

public : DeviceServicingTrigger()public DeviceServicingTrigger()Public Sub New()
Attributes

Methods

RequestAsync(String, TimeSpan) RequestAsync(String, TimeSpan) 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.

public : IAsyncOperation<DeviceTriggerResult> RequestAsync(PlatForm::String deviceId, TimeSpan expectedDuration)public IAsyncOperation<DeviceTriggerResult> RequestAsync(String deviceId, TimeSpan expectedDuration)Public Function RequestAsync(deviceId As String, expectedDuration As TimeSpan) As IAsyncOperation( Of DeviceTriggerResult )
Parameters
deviceId
PlatForm::String String String

The DeviceInformation.ID of the device the background task will access. The device path must match the device that will perform the background operation and is used by Windows to ensure that policy requirements are met.

expectedDuration
TimeSpan TimeSpan TimeSpan

Optional value. The expected duration of the background settings update or background firmware update. If provided, it will be displayed to the user in the system consent dialog when the task is triggered by your app. Set this value to zero if an appropriate time estimate cannot be determined.

Returns
Attributes
See Also

RequestAsync(String, TimeSpan, String) RequestAsync(String, TimeSpan, String) 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.

public : IAsyncOperation<DeviceTriggerResult> RequestAsync(PlatForm::String deviceId, TimeSpan expectedDuration, PlatForm::String arguments)public IAsyncOperation<DeviceTriggerResult> RequestAsync(String deviceId, TimeSpan expectedDuration, String arguments)Public Function RequestAsync(deviceId As String, expectedDuration As TimeSpan, arguments As String) As IAsyncOperation( Of DeviceTriggerResult )
Parameters
deviceId
PlatForm::String String String

The DeviceInformation.ID of the device the background task will access. The device path must match the device that will perform the background operation and is used by Windows to ensure that policy requirements are met.

expectedDuration
TimeSpan TimeSpan TimeSpan

Optional value. The expected duration of the background settings update or background firmware update. If provided, it will be displayed to the user in the system consent dialog when the task is triggered by your app. Set this value to zero if an appropriate time estimate cannot be determined.

arguments
PlatForm::String String String

Optional value. An app-specific string passed to the background task identifying which device operation to perform.

Returns
Attributes
See Also