Migration von GCMNetworkManager zu WorkManager

In diesem Dokument wird erläutert, wie Sie Apps zur WorkManager-Clientbibliothek migrieren. statt der GCMNetworkManager-Bibliothek Hintergrundvorgänge auszuführen. Die ist die Verwendung von WorkManager bei der Planung von Hintergrundjobs für eine App am besten geeignet. Von einschließlich der GCM-Bibliothek von WorkManager, können Sie aktivieren, dass WorkManager GCM zum Planen der Aufgaben auf Android-Geräten mit API-Level 22 planen oder niedriger.

Zu WorkManager migrieren

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

Für die folgenden Schritte gehen wir davon aus, dass Sie mit den folgenden Schritten beginnen: GCMNetworkManager-Code, der Ihre Aufgabe definiert und plant:

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 hinzufügen

Wenn Sie die WorkManager-Klassen verwenden möchten, müssen Sie die WorkManager-Bibliothek zu Ihrem Abhängigkeiten zu erstellen. Sie müssen auch die WorkManager-GCM-Bibliothek hinzufügen, aktiviert WorkManager die Verwendung von GCM für die Auftragsplanung, wenn Ihre App auf Geräte, die JobScheduler nicht unterstützen (d. h. Geräte mit API-Level 22) oder niedriger). Ausführliche Informationen zum Hinzufügen der Bibliotheken finden Sie unter Erste Schritte mit WorkManager.

Manifest ändern

Bei der Implementierung von GCMNetworkManager haben Sie GcmTaskService in dein App-Manifest ein, wie in GcmNetworkManager beschrieben. Referenzdokumentation. GcmTaskService sieht sich die eingehende Aufgabe an und delegiert sie an die Aufgabe -Handler. WorkManager verwaltet die Aufgabendelegierung für Ihren Worker, sodass Sie nicht mehr brauchen eine Klasse, die das erledigt. entfernen Sie einfach GcmTaskService aus dem Manifests.

Hinweis :Möglicherweise haben Sie Ihrem GcmTaskService eine Logik hinzugefügt, um vor Durch das Senden der Aufgabe an den Handler. In diesem Fall müssen Sie diese Logik in die von Ihnen definierte Worker-Klasse ein, im nächsten Abschnitt.

Worker definieren

Deine GCMNetworkManager-Implementierung definiert ein OneoffTask oder RecurringTask, was genau angibt, was zu tun ist. Sie müssen das so umformulieren, Worker, wie unter Arbeit definieren -Anfragen.

Hinweis: In GCMNetworkManager legt die Aufgabe sowohl fest, welche Arbeit Sie ausführen möchten, wann die Aufgabe ausgeführt werden soll. Mit der WorkManager-Bibliothek verwenden Sie zwei verschiedene Klassen zum Definieren dieser Elemente. Die Worker definiert die Aufgabe, die Sie ausführen möchten ausführen; wenn Sie die WorkRequest, Sie geben alle an Einschränkungen für die Ausführung des Jobs.

Das Beispiel für GCMNetworkManager Code definiert eine myTask-Aufgabe. Das WorkManager-Äquivalent 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. Die WorkManager verwendet Eingabedaten, die Sie in WorkRequest wie folgt angeben können: wie in der WorkManager-Dokumentation unter Ein-/Ausgabe definieren Ihre Aufgabe. In beiden Fällen können Sie Schlüssel/Wert-Paare übergeben, die beliebige persistente Parameter, die für die Aufgabe benötigt werden.
• GcmTaskService signalisiert Erfolg oder Misserfolg, indem Flags wie diese zurückgegeben werden: GcmNetworkManager.RESULT_SUCCESS. Ein WorkManager-Worker signalisiert seine Ergebnisse mit einer ListenableWorker.Result wie zum Beispiel ListenableWorker.Result.success(), und den Rückgabewert dieser Methode zurückgeben.
• Wie bereits erwähnt, legen Sie beim Definieren der Worker; stattdessen im nächsten Schritt, wenn Sie die WorkRequest.

Arbeitsanfrage planen

Durch Definition eines Worker kannst du festlegen, was du tun musst. Um festzulegen, wann die Arbeit abgeschlossen sein sollte, müssen Sie WorkRequest:

1. OneTimeWorkRequest erstellen oder PeriodicWorkRequest und Legen Sie die gewünschten Einschränkungen fest, die angeben, wann die Aufgabe ausgeführt werden soll, sowie um Ihre Arbeit zu identifizieren.
2. Anfrage übergeben an WorkManager.enqueue() um die Aufgabe zur Ausführung in die Warteschlange zu stellen.

Im vorherigen Abschnitt wurde beispielsweise gezeigt, wie ein OneoffTask in einen entsprechenden Worker. Diese Worker enthielt jedoch keine die Ausführungseinschränkungen und das Tag des OneoffTask-Objekts. Stattdessen legen wir die und die Aufgaben-ID beim Erstellen von WorkRequest. Außerdem geben wir an, Die Aufgabe darf nur ausgeführt werden, wenn eine Netzwerkverbindung besteht. Sie benötigen keine explizit eine Netzwerkverbindung mit GCMNetworkManager anfordern, GCMNetworkManager erfordert standardmäßig eine Netzwerkverbindung, WorkManager jedoch. erfordern keine Netzwerkverbindung, es sei denn, Sie fügen diese Einschränkung ausdrücklich hinzu. Nachdem Sie die WorkRequest definiert haben, fügen wir sie dem WorkManager in die Warteschlange ein.

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

Hinweis: Bei GCMNetworkManager muss jede Aufgabe ein eindeutiges Tag haben. Das Analoge Das WorkManager-Konstrukt ist die WorkRequest-ID. Diese ID wird automatisch festgelegt von WorkManager, wenn die Anfrage erstellt wird, erhalten Sie die ID, indem Sie WorkRequest.getId() WorkManager können Sie auch Tags für Ihre Jobs definieren. GCMNetworkManager-Tags verwendet, da sie nicht eindeutig sein müssen. haben Sie vielleicht ähnliche WorkManager-Aufgaben werden alle gleichzeitig in die Warteschlange gestellt und alle verwenden dasselbe Tag.

Hinweis: Für GCMNetworkManager müssen Sie ein Ausführungsfenster definieren, aber Für WorkManager ist das nicht erforderlich. Stattdessen führt WorkManager den Job aus, sobald nachdem die Einschränkungen erfüllt wurden. In diesem Beispiel gehen wir davon aus, eine bestimmte Uhrzeit für die Ausführung des Jobs festlegen müssen.

API-Zuordnungen

In diesem Abschnitt wird beschrieben, wie einige GCMNetworkManager-Funktionen und -Einschränkungen zugeordnet werden. in WorkManager-Entsprechungen ein.

Einschränkungszuordnungen

Mit GCMNetworkManager können Sie eine Reihe von Einschränkungen dafür festlegen, wann Ihre Aufgabe ausführen. In den meisten Fällen gibt es eine eindeutige WorkManager-Einschränkung. Dieses werden diese Entsprechungen aufgelistet.

Legen Sie Einschränkungen für GCMNetworkManager-Aufgaben fest, indem Sie die entsprechende Methode in das Builder-Objekt der Aufgabe; Sie können z. B. eine Netzwerkanforderung festlegen, Task.Builder.setRequiredNetwork() wird aufgerufen.

In WorkManager erstellen Sie ein Constraints.Builder-Objekt und die Methoden dieses Objekts aufrufen, um Einschränkungen festzulegen (z. B. Constraints.Builder.setRequiredNetworkType()), Erstellen Sie dann mit dem Builder ein Einschränkungsobjekt, das Sie an die Arbeitsanfrage. Weitere Informationen finden Sie unter Arbeit definieren -Anfragen.

Hinweis: Mit GCMNetworkManager können Sie ein bestimmtes Ausführungsfenster für Ihre Aufgabe. In WorkManager gibt es keine vergleichbare Funktionalität. Bei Bedarf zu einer bestimmten Zeit ausgeführt werden soll, empfehlen wir, andere Optionen wie AlarmManager

GCMNetworkManager-Einschränkung	WorkManager-Entsprechung	Hinweise
setPersisted()	(nicht erforderlich)	Alle WorkManager-Jobs bleiben bei Geräteneustarts erhalten.
setRequiredNetwork()	setRequiredNetworkType()	Standardmäßig erfordert GCMNetworkManager Netzwerkzugriff. WorkManager erfordert standardmäßig keinen Netzwerkzugriff. Wenn für den Job ein Netzwerkzugriff erforderlich ist, müssen Sie setRequiredNetworkType(CONNECTED) verwenden oder einen bestimmten Netzwerktyp festlegen.
setRequiresCharging()

Andere Zuordnungen

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

Tags

Alle GCMNetworkManager-Aufgaben müssen über einen Tag-String verfügen, den Sie durch Aufrufen der setTag() des Bauarbeiters . WorkManager-Jobs sind eindeutig durch eine ID gekennzeichnet, die automatisch von WorkManager generiert; erhalten Sie diese ID, indem Sie WorkRequest.getId() In Arbeitsanfragen können optional ein oder mehrere Tags enthalten. Um ein Tag für WorkManager-Job ist, rufen Sie die WorkRequest.Builder.addTag() bevor Sie diesen Builder zum Erstellen der WorkRequest verwenden.

In GCMNetworkManager können Sie setUpdateCurrent() , um anzugeben, ob die Aufgabe eine vorhandene Aufgabe durch dasselbe Tag ersetzen soll. Der entsprechende WorkManager-Ansatz besteht darin, die Aufgabe durch Aufrufen enqueueUniqueWork() oder enqueueUniquePeriodicWork(); Wenn Sie diese Methoden verwenden, geben Sie dem Job einen eindeutigen Namen und geben an, wie WorkManager sollte die Anfrage bearbeiten, wenn es bereits einen ausstehenden Auftrag mit dieser Namen. Weitere Informationen finden Sie unter Umgang mit eindeutigen (geschäftlich).

Aufgabenparameter

Sie können Parameter an einen GCMNetworkManager-Job übergeben, indem Sie folgenden Befehl aufrufen: Task.Builder.setExtras() und eine Bundle übergeben, die die Parameter enthält. WorkManager ermöglicht es Ihnen, Ein Data-Objekt für den WorkManager-Job, das die Parameter als Schlüssel/Wert-Paar enthält Paare. Weitere Informationen finden Sie unter Eingabedaten zuweisen: