The second Android 11 Developer Preview is now available, test it out and share your feedback.

Getting started with WorkManager

With WorkManager, you can easily set up a task and hand it off to the system to run under the conditions you specify. To learn more if WorkManager is the right solution for your task, check out the background processing guide.

In this guide you will learn how to:

  • Add WorkManager to your Android project
  • Create a background task
  • Configure how and when to run the task
  • Hand off your task to the system

For information about WorkManager features, like handling recurring work, creating chains of work and cancelling work, check out the how-to guides.

Add WorkManager to your Android project

To import the WorkManager library into your Android project, add the following dependencies to your app's build.gradle file:

dependencies {
  def work_version = "2.3.4"

    // (Java only)
    implementation "androidx.work:work-runtime:$work_version"

    // Kotlin + coroutines
    implementation "androidx.work:work-runtime-ktx:$work_version"

    // optional - RxJava2 support
    implementation "androidx.work:work-rxjava2:$work_version"

    // optional - GCMNetworkManager support
    implementation "androidx.work:work-gcm:$work_version"

    // optional - Test helpers
    androidTestImplementation "androidx.work:work-testing:$work_version"
  }

Create a background task

A task is defined using the Worker class. The doWork() method is run synchronously on a background thread provided by WorkManager.

To create your background task, extend the Worker class and override the doWork() method. For example, to create a Worker that uploads images, you can do the following:

Kotlin

class UploadWorker(appContext: Context, workerParams: WorkerParameters)
    : Worker(appContext, workerParams) {

    override fun doWork(): Result {
        // Do the work here--in this case, upload the images.

        uploadImages()

        // Indicate whether the task finished successfully with the Result
        return Result.success()
    }
}

Java

public class UploadWorker extends Worker {

    public UploadWorker(
        @NonNull Context context,
        @NonNull WorkerParameters params) {
        super(context, params);
    }

    @Override
    public Result doWork() {
      // Do the work here--in this case, upload the images.

      uploadImages()

      // Indicate whether the task finished successfully with the Result
      return Result.success()
    }
}

The Result returned from doWork() informs WorkManager whether the task:

  • finished successfully via Result.success()
  • failed via Result.failure()
  • needs to be retried at a later time via Result.retry()

Configure how and when to run the task

While a Worker defines the unit of work, a WorkRequest defines how and when work should be run. Tasks may be one-off or periodic. For one-off WorkRequests, use OneTimeWorkRequest and for periodic work PeriodicWorkRequest. For more information on scheduling recurring work, read the recurring work documentation.

In this case, the simplest example for building a WorkRequest for our UploadWorker is:

Kotlin

val uploadWorkRequest = OneTimeWorkRequestBuilder<UploadWorker>()
        .build()

Java

OneTimeWorkRequest uploadWorkRequest = new OneTimeWorkRequest.Builder(UploadWorker.class)
        .build()

The WorkRequest can also include additional information, such as the constraints under which the task should run, input to the work, a delay, and backoff policy for retrying work. These options are explained in greater detail in the Defining Work guide.

Hand off your task to the system

Once you have defined your WorkRequest, you can now schedule it with WorkManager using the enqueue() method.

Kotlin

WorkManager.getInstance(myContext).enqueue(uploadWorkRequest)

Java

WorkManager.getInstance(myContext).enqueue(uploadWorkRequest);

The exact time that the worker is going to be executed depends on the constraints that are used in your WorkRequest and on system optimizations. WorkManager is designed to give the best possible behavior under these restrictions.

Next steps