Premiers pas avec WorkManager

Pour commencer à utiliser WorkManager, importez d'abord la bibliothèque dans votre projet Android.

Ajoutez les dépendances suivantes au fichier build.gradle de votre application :

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")
}

Une fois que vous avez ajouté les dépendances et synchronisé votre projet Gradle, l'étape suivante consiste à définir des tâches à exécuter.

Définir des tâches

Les tâches sont définies à l'aide de la classe Worker. La méthode doWork() s'exécute de manière asynchrone sur un thread d'arrière-plan fourni par WorkManager.

Pour créer une tâche à exécuter par WorkManager, développez la classe Worker et ignorez la méthode doWork(). Par exemple, pour créer un Worker qui importe des images, vous pouvez procéder comme suit :

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();
   }
}

Le Result renvoyé par doWork() indique au service WorkManager si une tâche a été effectuée et, en cas d'échec, si elle doit faire l'objet d'une nouvelle tentative.

  • Result.success() : la tâche a été effectuée avec succès.
  • Result.failure() : la tâche a échoué.
  • Result.retry() : la tâche a échoué et doit être testée ultérieurement conformément à ses règles de nouvelle tentative.

Créer une WorkRequest

Une fois que votre tâche est définie, elle doit être planifiée avec le service WorkManager pour pouvoir s'exécuter. WorkManager offre une grande flexibilité dans la planification des tâches. Vous pouvez planifier l'exécution de temps à autre sur une période donnée ou une seule fois.

Quelle que soit la méthode choisie, vous utiliserez toujours une WorkRequest. Un Worker définit l'unité de travail, et une WorkRequest (et ses sous-classes) définit comment et quand elle doit être exécutée. Dans le cas le plus simple, vous pouvez utiliser un objet OneTimeWorkRequest, comme illustré dans l'exemple suivant.

Kotlin

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

Java

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

Envoyer la WorkRequest au système

Enfin, vous devez envoyer votre WorkRequest au WorkManager à l'aide de la méthode enqueue().

Kotlin

WorkManager
    .getInstance(myContext)
    .enqueue(uploadWorkRequest)

Java

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

Le délai exact d'exécution du nœud de calcul dépend des contraintes utilisées dans votre WorkRequest et des optimisations du système. WorkManager est conçu pour offrir un comportement optimal dans ces conditions.

Étapes suivantes

Ce guide de démarrage ne fait que survoler le sujet. La WorkRequest peut également inclure des informations supplémentaires telles que les contraintes avec lesquelles la tâche doit s'exécuter, les données d'entrée de la tâche, un délai et l'intervalle entre les nouvelles tentatives d'exécution de la tâche. Dans la section suivante, Définir vos requêtes de travail, vous découvrirez ces options plus en détail et découvrirez comment planifier des tâches uniques et récurrentes.

Ressources supplémentaires

En plus de la documentation du guide, plusieurs blogs, ateliers de programmation et exemples de code sont disponibles pour vous aider à vous lancer.

Exemples

  • Sunflower, une application de démonstration qui montre les bonnes pratiques associées à divers composants d'architecture, y compris WorkManager.

Ateliers de programmation

Blogs