Migration von GCMNetworkManager zu WorkManager

In diesem Dokument wird erläutert, wie Apps migriert werden, damit sie die WorkManager-Clientbibliothek verwenden können, um Hintergrundvorgänge anstelle der GCMNetworkManager-Bibliothek auszuführen. Hintergrundjobs werden von einer App am besten mit WorkManager geplant. Wenn Sie zusätzlich die WorkManager-GCM-Bibliothek hinzufügen, können Sie WorkManager die Verwendung von GCM zur Planung der Aufgaben auf Android-Geräten mit API-Level 22 oder niedriger aktivieren.

Zu WorkManager migrieren

Wenn deine App derzeit GCMNetworkManager für Hintergrundvorgänge verwendet, führe die folgenden Schritte aus, um zu WorkManager zu migrieren.

Für die folgenden Schritte gehen wir davon aus, dass Sie mit dem folgenden GCMNetworkManager-Code beginnen, mit dem Ihre Aufgabe definiert und geplant wird:

Kotlin

val myTask = OneoffTask.Builder()
    // setService() says what class does the work
    .setService(MyUploadService::class.java)
    // Don't run the task unless device is charging
    .setRequiresCharging(true)
    // Run the task between 5 & 15 minutes from now
    .setExecutionWindow(5 * DateUtil.MINUTE_IN_SECONDS,
            15 * DateUtil.MINUTE_IN_SECONDS)
    // Define a unique tag for the task
    .setTag("test-upload")
    // ...finally, build the task and assign its value to myTask
    .build()
GcmNetworkManager.getInstance(this).schedule(myTask)

Java

// In GcmNetworkManager, this call defines the task and its
// runtime constraints:
OneoffTask myTask = new OneoffTask.Builder()
    // setService() says what class does the work
    .setService(MyUploadService.class)
    // Don't run the task unless device is charging
    .setRequiresCharging(true)
    // Run the task between 5 & 15 minutes from now
    .setExecutionWindow(
        5 * DateUtil.MINUTE_IN_SECONDS,
        15 * DateUtil.MINUTE_IN_SECONDS)
    // Define a unique tag for the task
    .setTag("test-upload")
    // ...finally, build the task and assign its value to myTask
    .build();
GcmNetworkManager.getInstance(this).schedule(myTask);

In diesem Beispiel wird davon ausgegangen, dass MyUploadService den tatsächlichen Uploadvorgang definiert:

Kotlin

class MyUploadService : GcmTaskService() {
    fun onRunTask(params: TaskParams): Int {
        // Do some upload work
        return GcmNetworkManager.RESULT_SUCCESS
    }
}

Java

class MyUploadService extends GcmTaskService {
    @Override
    public int onRunTask(TaskParams params) {
        // Do some upload work
        return GcmNetworkManager.RESULT_SUCCESS;
    }
}

WorkManager-Bibliotheken einbeziehen

Wenn Sie die WorkManager-Klassen verwenden möchten, müssen Sie die WorkManager-Bibliothek Ihren Build-Abhängigkeiten hinzufügen. Außerdem müssen Sie die WorkManager-GCM-Bibliothek hinzufügen. Dadurch kann WorkManager GCM für die Jobplanung verwenden, wenn Ihre App auf Geräten ausgeführt wird, die JobScheduler nicht unterstützen, also Geräte mit API-Level 22 oder niedriger. Weitere Informationen zum Hinzufügen der Bibliotheken finden Sie unter Erste Schritte mit WorkManager.

Manifest ändern

Bei der Implementierung von GCMNetworkManager haben Sie Ihrem App-Manifest eine Instanz von GcmTaskService hinzugefügt, wie in der Referenzdokumentation zu GcmNetworkManager beschrieben. GcmTaskService prüft die eingehende Aufgabe und delegiert sie an den Aufgaben-Handler. WorkManager verwaltet die Aufgabendelegierung an Ihren Worker. Sie benötigen also keine Klasse mehr, die dies tut. Entfernen Sie einfach GcmTaskService aus dem Manifest.

Worker definieren

In Ihrer GCMNetworkManager-Implementierung wird ein OneoffTask oder RecurringTask definiert, um festzulegen, welche Arbeit ausgeführt werden muss. Sie müssen dies in Worker umschreiben, wie unter Arbeitsanfragen definieren beschrieben.

Der GCMNetworkManager-Beispielcode definiert eine myTask-Aufgabe. Die WorkManager-Entsprechung sieht so aus:

Kotlin

class UploadWorker(context: Context, params: WorkerParameters)
                        : Worker(context, params) {
    override fun doWork() : Result {
        // Do the upload operation ...
        myUploadOperation()

        // 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 upload operation ...

      myUploadOperation()

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

Es gibt einige Unterschiede zwischen der GCM-Aufgabe und der Worker:

  • GCM verwendet ein TaskParams-Objekt, um Parameter an die Aufgabe zu übergeben. Der WorkManager verwendet Eingabedaten, die Sie in der WorkRequest angeben können, wie in der WorkManager-Dokumentation unter Eingabe/Ausgabe für Ihre Aufgabe definieren beschrieben. In beiden Fällen können Sie Schlüssel/Wert-Paare übergeben, die alle persistenten Parameter angeben, die für die Aufgabe erforderlich sind.
  • GcmTaskService signalisiert Erfolg oder Misserfolg, indem Flags wie GcmNetworkManager.RESULT_SUCCESS zurückgegeben werden. Ein WorkManager-Worker signalisiert seine Ergebnisse, indem es eine ListenableWorker.Result-Methode wie ListenableWorker.Result.success() verwendet und den Rückgabewert dieser Methode zurückgibt.
  • Wie bereits erwähnt, legen Sie die Einschränkungen oder Tags nicht beim Definieren von Worker fest. Dies geschieht im nächsten Schritt, wenn Sie den WorkRequest erstellen.

Arbeitsanfrage planen

Durch die Definition eines Worker wird angegeben, was du tun musst. Um anzugeben, wann die Arbeit erledigt werden soll, musst du WorkRequest definieren:

  1. Erstellen Sie ein OneTimeWorkRequest- oder PeriodicWorkRequest-Objekt und legen Sie die gewünschten Einschränkungen fest, die angeben, wann die Aufgabe ausgeführt werden soll, sowie alle Tags zur Identifizierung Ihrer Arbeit.
  2. Übergeben Sie die Anfrage an WorkManager.enqueue(), damit die Aufgabe zur Ausführung in die Warteschlange gestellt wird.

Im vorherigen Abschnitt wurde beispielsweise gezeigt, wie eine OneoffTask in eine entsprechende Worker konvertiert wird. Diese Worker enthielt jedoch nicht die Ausführungseinschränkungen und das Tag des OneoffTask-Objekts. Stattdessen werden die Einschränkungen und die Aufgaben-ID beim Erstellen von WorkRequest festgelegt. Außerdem geben wir an, dass die Task nur dann ausgeführt werden darf, wenn eine Netzwerkverbindung besteht. Sie müssen nicht explizit eine Netzwerkverbindung mit GCMNetworkManager anfordern, da GCMNetworkManager standardmäßig eine Netzwerkverbindung benötigt. Für WorkManager ist jedoch keine Netzwerkverbindung erforderlich, sofern Sie diese Einschränkung nicht ausdrücklich hinzufügen. Nachdem wir die WorkRequest definiert haben, wird sie in die Warteschlange mit WorkManager aufgenommen.

Kotlin

val uploadConstraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true).build()

val uploadTask = OneTimeWorkRequestBuilder<UploadWorker>()
    .setConstraints(uploadConstraints)
    .build()
WorkManager.getInstance().enqueue(uploadTask)

Java

Constraints uploadConstraints = new Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true)
    .build();

OneTimeWorkRequest uploadTask =
        new OneTimeWorkRequest.Builder(UploadWorker.class)
  .setConstraints(uploadConstraints)
  .build();
WorkManager.getInstance().enqueue(uploadTask);

API-Zuordnungen

In diesem Abschnitt wird beschrieben, wie einige GCMNetworkManager-Funktionen und -Einschränkungen den WorkManager-Äquivalenten zugeordnet werden.

Einschränkungszuordnungen

Mit GCMNetworkManager können Sie eine Reihe von Einschränkungen für die Ausführung Ihrer Aufgabe festlegen. In den meisten Fällen gibt es eine eindeutige äquivalente WorkManager-Einschränkung. In diesem Abschnitt werden diese Äquivalente aufgeführt.

Legen Sie Einschränkungen für GCMNetworkManager-Aufgaben fest, indem Sie die entsprechende Methode im Builder-Objekt der Aufgabe aufrufen. Zum Beispiel können Sie durch Aufrufen von Task.Builder.setRequiredNetwork() eine Netzwerkanforderung festlegen.

Sie erstellen in WorkManager ein Constraints.Builder-Objekt und rufen die Methoden dieses Objekts auf, um Einschränkungen festzulegen (z. B. Constraints.Builder.setRequiredNetworkType())). Verwenden Sie dann den Builder, um ein Einschränkungsobjekt zu erstellen, das Sie an die Arbeitsanfrage anhängen können. Weitere Informationen finden Sie unter Arbeitsanfragen definieren.

Einschränkung "GCMNetworkManager" WorkManager-Entsprechung Hinweise
setPersisted() (nicht erforderlich) Alle WorkManager-Jobs werden auch nach Geräteneustarts beibehalten.
setRequiredNetwork() setRequiredNetworkType() Standardmäßig benötigt GCMNetworkManager Netzwerkzugriff. WorkManager benötigt standardmäßig keinen Netzwerkzugriff. Wenn Ihr Job Netzwerkzugriff erfordert, müssen Sie setRequiredNetworkType(CONNECTED) verwenden oder einen genaueren Netzwerktyp festlegen.
setRequiresCharging()

Andere Zuordnungen

Neben den Einschränkungen gibt es weitere Einstellungen, die Sie auf GCMNetworkManager-Aufgaben anwenden können. In diesem Abschnitt wird beschrieben, wie diese Einstellungen entsprechend auf einen WorkManager-Job angewendet werden.

Tags

Alle GCMNetworkManager-Aufgaben müssen einen Tag-String enthalten, den Sie durch Aufrufen der Builder-Methode setTag() festlegen. WorkManager-Jobs sind eindeutig durch eine ID gekennzeichnet, die automatisch von WorkManager generiert wird. Rufen Sie WorkRequest.getId() auf, um diese ID zu erhalten. Außerdem können Arbeitsanfragen optional ein oder mehrere Tags enthalten. Um ein Tag für Ihren WorkManager-Job festzulegen, rufen Sie die Methode WorkRequest.Builder.addTag() auf, bevor Sie mit diesem Builder die WorkRequest erstellen.

In GCMNetworkManager können Sie setUpdateCurrent() aufrufen, um anzugeben, ob die Aufgabe eine vorhandene Aufgabe durch dasselbe Tag ersetzen soll. Die entsprechende WorkManager-Methode besteht darin, die Aufgabe durch Aufrufen von enqueueUniqueWork() oder enqueueUniquePeriodicWork() in die Warteschlange zu stellen. Wenn Sie diese Methoden verwenden, geben Sie dem Job einen eindeutigen Namen und geben auch an, wie WorkManager die Anfrage verarbeiten soll, wenn es bereits einen ausstehenden Job mit diesem Namen gibt. Weitere Informationen finden Sie unter Einzelne Aufgaben verarbeiten.

Aufgabenparameter

Sie können Parameter an einen GCMNetworkManager-Job übergeben, indem Sie Task.Builder.setExtras() aufrufen und einen Bundle mit den Parametern übergeben. Mit WorkManager können Sie ein Data-Objekt an den WorkManager-Job übergeben, das die Parameter als Schlüssel/Wert-Paare enthält. Weitere Informationen finden Sie unter Eingabedaten zuweisen.