从 GCMNetworkManager 迁移到 WorkManager

本文档说明了如何将应用迁移到使用 WorkManager 客户端库执行后台操作，而不是使用 GCMNetworkManager 库。应用计划后台作业的首选方法是使用 WorkManager。通过同时包含 WorkManager GCM 库，您可以使 WorkManager 在 Android 设备（运行 API 级别 22 或更低版本）上使用 GCM 计划任务。

迁移到 WorkManager

如果您的应用当前使用 GCMNetworkManager 执行后台操作，请按照以下步骤迁移到 WorkManager。

对于以下步骤，我们假设您从以下 GCMNetworkManager 代码开始，该代码定义并计划了您的任务

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

在此示例中，我们假设 MyUploadService 定义了实际的上传操作

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 库

要使用 WorkManager 类，您需要将 WorkManager 库添加到您的构建依赖项中。您还需要添加 WorkManager GCM 库，该库使 WorkManager 能够在您的应用在不支持 JobScheduler 的设备（即运行 API 级别 22 或更低版本的设备）上运行时使用 GCM 进行作业调度。有关添加库的完整详细信息，请参阅 WorkManager 入门。

修改您的清单

当您实现 GCMNetworkManager 时，您会将 GcmTaskService 的实例添加到您的应用清单中，如 GcmNetworkManager 的参考文档中所述。GcmTaskService 查看传入的任务并将其委托给任务处理程序。WorkManager 管理对您的 Worker 的任务委托，因此您不再需要执行此操作的类；只需从清单中删除您的 GcmTaskService 即可。

定义 Worker

您的 GCMNetworkManager 实现定义了 OneoffTask 或 RecurringTask，它指定了需要执行哪些工作。您需要将其重写为 Worker，如定义工作请求中所述。

GCMNetworkManager 代码示例定义了一个 myTask 任务。WorkManager 等效项如下所示

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

GCM 任务和 Worker 之间存在一些差异

GCM 使用 TaskParams 对象将参数传递给任务。WorkManager 使用输入数据，您可以在 WorkRequest 上指定输入数据，如 WorkManager 文档中有关定义任务的输入/输出的说明。在这两种情况下，您都可以传递键/值对，指定任务所需的任何可持久化参数。
GcmTaskService 通过返回 GcmNetworkManager.RESULT_SUCCESS 等标志来表示成功或失败。WorkManager Worker 通过使用 ListenableWorker.Result 方法（如 ListenableWorker.Result.success()）并返回该方法的返回值来表示其结果。
正如我们提到的，您不会在定义 Worker 时设置约束或标签；而是在下一步创建 WorkRequest 时执行此操作。

计划工作请求

定义 Worker 指定了需要执行的操作。要指定工作应何时执行，您需要定义 WorkRequest

创建一个 OneTimeWorkRequest 或 PeriodicWorkRequest，并设置任何所需的约束，指定任务应何时运行，以及任何用于识别您的工作的标签。
将请求传递给WorkManager.enqueue()，以便将任务排队等待执行。

例如，上一节展示了如何将OneoffTask转换为等效的Worker。但是，该Worker没有包含OneoffTask对象的执行约束和标签。相反，我们在创建WorkRequest时设置了约束和任务 ID。我们还将指定，除非存在网络连接，否则任务不得运行。您无需使用 GCMNetworkManager 显式请求网络连接，因为 GCMNetworkManager 默认情况下需要网络连接，但 WorkManager 除非您专门添加该约束，否则不需要网络连接。定义WorkRequest后，我们使用 WorkManager 将其排队。

Kotlin

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

val uploadTask = OneTimeWorkRequestBuilder&lt;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 映射

本节介绍一些 GCMNetworkManager 功能和约束如何映射到 WorkManager 等效项。

约束映射

GCMNetworkManager 允许您设置一些关于任务何时应运行的约束。在大多数情况下，存在一个清晰的等效 WorkManager 约束。本节列出了这些等效项。

通过调用任务的 Builder 对象中的相应方法来设置 GCMNetworkManager 任务上的约束；例如，您可以通过调用Task.Builder.setRequiredNetwork()来设置网络需求。

在 WorkManager 中，您创建一个Constraints.Builder对象并调用该对象的 methods 来设置约束（例如，Constraints.Builder.setRequiredNetworkType())，然后使用 Builder 创建一个 Constraints 对象，您可以将其附加到工作请求。有关更多信息，请参阅定义工作请求。

GCMNetworkManager 约束	WorkManager 等效项	注释
`setPersisted()`	（不需要）	所有 WorkManager 作业都会在设备重启后持久化
`setRequiredNetwork()`	`setRequiredNetworkType()`	默认情况下，GCMNetworkManager 需要网络访问权限。WorkManager 默认情况下不需要网络访问权限。如果您的作业需要网络访问权限，则必须使用`setRequiredNetworkType(CONNECTED)`，或设置更具体的网络类型。
`setRequiresCharging()`

其他映射

除了约束之外，您还可以对 GCMNetworkManager 任务应用其他设置。本节列出了将这些设置应用于 WorkManager 作业的对应方法。

所有 GCMNetworkManager 任务都必须具有一个标签字符串，您可以通过调用 Builder 的setTag()方法来设置它。WorkManager 作业由一个 ID 唯一标识，该 ID 由 WorkManager 自动生成；您可以通过调用WorkRequest.getId()获取该 ID。此外，工作请求可以可选地具有一个或多个标签。要为您的 WorkManager 作业设置标签，请在使用该 Builder 创建WorkRequest之前，调用WorkRequest.Builder.addTag()方法。

在 GCMNetworkManager 中，您可以调用setUpdateCurrent()来指定任务是否应替换具有相同标签的任何现有任务。等效的 WorkManager 方法是通过调用enqueueUniqueWork()或enqueueUniquePeriodicWork()来排队任务；如果您使用这些方法，则会为作业提供一个唯一名称，并指定如果已存在具有该名称的挂起作业，WorkManager 如何处理该请求。有关更多信息，请参阅处理唯一工作。

任务参数

您可以通过调用Task.Builder.setExtras()并传递包含参数的Bundle来将参数传递给 GCMNetworkManager 作业。WorkManager 允许您将Data对象传递给 WorkManager 作业，其中包含参数作为键/值对。有关详细信息，请参阅分配输入数据。