Primeiros passos com o WorkManager

Para começar a usar o WorkManager, primeiro importe a biblioteca para seu projeto Android.

Adicione as seguintes dependências ao arquivo build.gradle do app:

Groovy

dependencies {
    def work_version = "2.9.1"

    // (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"

    // optional - Multiprocess support
    implementation "androidx.work:work-multiprocess:$work_version"
}

Kotlin

dependencies {
    val work_version = "2.9.1"

    // (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")

    // optional - Multiprocess support
    implementation("androidx.work:work-multiprocess:$work_version")
}

Depois de adicionar as dependências e sincronizar o projeto do Gradle, o próximo passo é definir algum trabalho a ser executado.

Definir o trabalho

O trabalho é definido usando a classe Worker. O método doWork() é executado de forma assíncrona em uma linha de execução em segundo plano fornecida pelo WorkManager.

Para criar trabalhos a serem executados no WorkManager, estenda a classe Worker e substitua o método doWork(). Por exemplo, para criar um Worker que faça upload de imagens, faça o seguinte:

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 work 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 work finished successfully with the Result
     return Result.success();
   }
}

O Result retornado de doWork() informa ao serviço do WorkManager se o trabalho foi bem-sucedido e, no caso de falha, se o trabalho será repetido ou não.

  • Result.success(): o trabalho foi concluído.
  • Result.failure(): o trabalho falhou.
  • Result.retry(): o trabalho falhou e precisa ser repetido em outro momento de acordo com a política de nova tentativa.

Criar uma WorkRequest

Depois de definir o trabalho, ele precisa ser programado com o serviço WorkManager para ser executado. O WorkManager oferece muita flexibilidade na forma como você programa seu trabalho. É possível programá-lo para ser executado periodicamente por um intervalo de tempo ou para ser executado apenas uma vez.

Independentemente de como você programe o trabalho, sempre usará uma WorkRequest. Enquanto Worker define a unidade de trabalho, uma WorkRequest (e as respectivas subclasses) define como e quando ele será executado. No caso mais simples, é possível usar uma OneTimeWorkRequest, como mostrado no exemplo a seguir.

Kotlin

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

Java

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

Enviar a WorkRequest para o sistema

Por fim, você precisa enviar a WorkRequest para WorkManager usando o método enqueue().

Kotlin

WorkManager
    .getInstance(myContext)
    .enqueue(uploadWorkRequest)

Java

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

O tempo exato em que o worker será executado depende das limitações usadas na WorkRequest e nas otimizações do sistema. O WorkManager foi projetado para oferecer o melhor comportamento sob essas restrições.

A seguir

Este guia de primeiros passos é apenas o começo. A WorkRequest também pode incluir outras informações, como as limitações com que o trabalho será executado, a entrada para o trabalho, um atraso e uma política de espera para tentar um trabalho novamente. Na próxima seção, Definir suas solicitações de trabalho, você saberá mais sobre essas opções, além de entender como programar trabalhos únicos e recorrentes.

Outros recursos

Além da documentação do guia, existem vários blogs, codelabs e amostras de código disponíveis para ajudar você a começar.

Amostras

  • Sunflower (link em inglês), um app de demonstração que apresenta as práticas recomendadas com vários componentes de arquitetura, incluindo o WorkManager.

Codelabs

Blogs