Редактиране

Споделяне чрез

Create and register an in-process background task

  • Статия

Important APIs

This topic demonstrates how to create and register a background task that runs in the same process as your app.

In-process background tasks are simpler to implement than out-of-process background tasks. However, they are less resilient. If the code running in an in-process background task crashes, it will take down your app. Also note that DeviceUseTrigger, DeviceServicingTrigger and IoTStartupTask cannot be used with the in-process model. Activating a VoIP background task within your application is also not possible. These triggers and tasks are still supported using the out-of-process background task model.

Be aware that background activity can be terminated even when running inside the app's foreground process if it runs past execution time limits. For some purposes the resiliency of separating work into a background task that runs in a separate process is still useful. Keeping background work as a task separate from the foreground application may be the best option for work that does not require communication with the foreground application.

Fundamentals

The in-process model enhances the application lifecycle with improved notifications for when your app is in the foreground or in the background. Two new events are available from the Application object for these transitions: EnteredBackground and LeavingBackground. These events fit into the application lifecycle based on the visibility state of your application Read more about these events and how they affect the application lifecycle at App lifecycle.

At a high level, you will handle the EnteredBackground event to run your code that will execute while your app is running in the background, and handle LeavingBackground to know when your app has moved to the foreground.

Register your background task trigger

In-process background activity is registered much the same as out-of-process background activity. All background triggers start with registration using the BackgroundTaskBuilder. The builder makes it easy to register a background task by setting all required values in one place:

var builder = new BackgroundTaskBuilder();
builder.Name = "My Background Trigger";
builder.SetTrigger(new TimeTrigger(15, true));
// Do not set builder.TaskEntryPoint for in-process background tasks
// Here we register the task and work will start based on the time trigger.
BackgroundTaskRegistration task = builder.Register();

Note

Universal Windows apps must call RequestAccessAsync before registering any of the background trigger types. To ensure that your Universal Windows app continues to run properly after you release an update, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. For more information, see Guidelines for background tasks.

For in-process background activities you do not set TaskEntryPoint. Leaving it blank enables the default entry point, a new protected method on the Application object called OnBackgroundActivated().

Once a trigger is registered, it will fire based on the type of trigger set in the SetTrigger method. In the example above a TimeTrigger is used, which will fire fifteen minutes from the time it was registered.

Add a condition to control when your task will run (optional)

You can add a condition to control when your task will run after the trigger event occurs. For example, if you don't want the task to run until the user is present, use the condition UserPresent. For a list of possible conditions, see SystemConditionType.

The following sample code assigns a condition requiring the user to be present:

builder.AddCondition(new SystemCondition(SystemConditionType.UserPresent));

Place your background activity code in OnBackgroundActivated()

Put your background activity code in OnBackgroundActivated to respond to your background trigger when it fires. OnBackgroundActivated can be treated just like IBackgroundTask.Run. The method has a BackgroundActivatedEventArgs parameter, which contains everything that the Run method delivers. For example, in App.xaml.cs:

using Windows.ApplicationModel.Background;

...

sealed partial class App : Application
{
  ...

  protected override void OnBackgroundActivated(BackgroundActivatedEventArgs args)
  {
      base.OnBackgroundActivated(args);
      IBackgroundTaskInstance taskInstance = args.TaskInstance;
      DoYourBackgroundWork(taskInstance);  
  }
}

For a richer OnBackgroundActivated example, see Convert an app service to run in the same process as its host app.

Handle background task progress and completion

Task progress and completion can be monitored the same way as for multi-process background tasks (see Monitor background task progress and completion) but you will likely find that you can more easily track them by using variables to track progress or completion status in your app. This is one of the advantages of having your background activity code running in the same process as your app.

Handle background task cancellation

In-process background tasks are cancelled the same way as out-of-process background tasks are (see Handle a cancelled background task). Be aware that your BackgroundActivated event handler must exit before the cancellation occurs, or the whole process will be terminated. If your foreground app closes unexpectedly when you cancel the background task, verify that your handler exited before the cancellation occurred.

The manifest

Unlike out-of-process background tasks, you are not required to add background task information to the package manifest in order to run in-process background tasks.

Summary and next steps

You should now understand the basics of how to write an in-process background task.

See the following related topics for API reference, background task conceptual guidance, and more detailed instructions for writing apps that use background tasks.

Detailed background task instructional topics

Background task guidance

Background Task API Reference