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. DerWorkManager
verwendet Eingabedaten, die Sie in derWorkRequest
angeben können, wie in derWorkManager
-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 wieGcmNetworkManager.RESULT_SUCCESS
zurückgegeben werden. Ein WorkManager-Worker
signalisiert seine Ergebnisse, indem es eineListenableWorker.Result
-Methode wieListenableWorker.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 denWorkRequest
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:
- Erstellen Sie ein
OneTimeWorkRequest
- oderPeriodicWorkRequest
-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. - Ü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.