Thông tin cập nhật về API của trình bổ trợ Android cho Gradle

Trang này theo dõi việc ngừng sử dụng và xoá Android Gradle plugin API (AGP API) và cung cấp thông tin về cách cập nhật mã cho phù hợp.

Theo dõi việc ngừng sử dụng và xoá API

Bảng sau đây tóm tắt thời điểm các API AGP bị ngừng sử dụng và bị xoá, xét về phiên bản AGP.

API Ngừng sử dụng trong phiên bản AGP Xoá khỏi phiên bản AGP
Component.setAsmFramesComputationMode 7.2
Component.transformClassesWith 7.2
RenderScript 7.2
Transform 7.2 8.0

AGP 8.0

Sau đây là các nội dung cập nhật API quan trọng cho AGP 8.0.

Xoá Transform API

Transform API bị xoá kể từ phiên bản AGP 8.0. Điều này có nghĩa là tất cả các lớp trong gói com.android.build.api.transform đều bị xoá.

Việc xoá Transform API là để cải thiện hiệu năng bản dựng. Các dự án sử dụng Transform API buộc AGP phải sử dụng quy trình ít tối ưu hơn cho bản dựng. Điều này có thể dẫn đến sự tăng vọt số lần hồi quy trong thời gian tạo bản dựng. Khó sử dụng Transform API, cũng như khó kết hợp API này với các tính năng khác của Gradle. Các API thay thế có thể giúp dễ dàng mở rộng AGP mà không gây ra vấn đề về hiệu năng hoặc gây ra lỗi về độ chính xác.

API thay thế

Transform API không được thay thế bằng một API duy nhất – mà là các API mới, được nhắm đến từng trường hợp sử dụng. Tất cả API thay thế đều nằm trong khối androidComponents {}. AGP 7.2 có thể sử dụng được tất cả các API này.

Hỗ trợ chuyển đổi mã byte

Để chuyển đổi mã byte, hãy sử dụng Instrumentation API. Đối với các thư viện, bạn chỉ có thể đăng ký một chức năng đo lường dành cho các lớp dự án cục bộ. Đối với các ứng dụng và quy trình kiểm thử, bạn có thể chọn chỉ đăng ký một chức năng đo lường dành cho các lớp cục bộ hoặc mọi lớp (bao gồm cả các phần phụ thuộc cục bộ và từ xa). Để sử dụng API này, chức năng đo lường sẽ chạy độc lập trên từng lớp, với quyền truy cập hạn chế vào các lớp khác trong đường dẫn lớp (xem createClassVisitor() để biết thêm thông tin ). Quy tắc hạn chế này cải thiện hiệu năng của cả các bản dựng đầy đủ và các bản dựng bổ sung, đồng thời giúp nền tảng API trở nên đơn giản. Mỗi thư viện được đo lường song song ngay khi sẵn sàng, thay vì sau khi mọi việc biên dịch hoàn tất. Ngoài ra, một sự thay đổi trong một lớp đơn lẻ có nghĩa là chỉ có các lớp bị ảnh hưởng mới được đo lường lại trong một bản dựng bổ sung. Hãy xem ví dụ về cách sử dụng Instrumentation API trong hướng dẫn AGP Chuyển đổi các lớp bằng ASM.

Hỗ trợ việc thêm các lớp đã tạo vào ứng dụng của bạn

Để thêm các lớp được tạo bổ sung vào ứng dụng, hãy sử dụng Artifacts API với MultipleArtifact.ALL_CLASSES_DIRS. Cụ thể, hãy sử dụng đoạn mã

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

với MultipleArtifact.ALL_CLASSES_DIRS để thêm các thư mục được tạo bổ sung vào các lớp dự án. Artifacts API sẽ tự động chọn một vị trí duy nhất để tác vụ tuỳ chỉnh của bạn có thể xuất đầu ra. Hãy xem hướng dẫn addToAllClasses để tìm hiểu ví dụ về cách sử dụng API này.

Hỗ trợ việc chuyển đổi dựa trên phân tích toàn bộ chương trình

Để triển khai các lượt chuyển đổi dựa trên kết quả phân tích toàn bộ chương trình, tất cả các lớp có thể được chuyển đổi cùng nhau trong một tác vụ. Bạn nên sử dụng phương pháp này một cách thận trọng vì độ hao hụt hiệu năng bản dựng cao hơn nhiều so với việc sử dụng Instrumentation API. Nếu trình bổ trợ của bạn sử dụng API này, bạn nên chọn thực hiện chuyển đổi đối với mỗi loại bản dựng để nhà phát triển ứng dụng có thể vô hiệu hoá chuyển đổi đó trong các bản dựng phát triển.

Để đăng ký một tác vụ chuyển đổi mọi lớp cùng nhau, trình bổ trợ Android cho Gradle 7.4 giới thiệu API Artifacts.forScope. Để chuyển đổi mọi lớp trong dự án hiện tại, hãy sử dụng Artifacts.forScope.PROJECT. Để chuyển đổi mọi lớp trong dự án hiện tại, dự án đã nhập và mọi phần phụ thuộc bên ngoài, hãy sử dụng Artifacts.forScope.ALL. Đoạn mã sau đây cho biết cách sử dụng Artifacts.forScope.ALL để đăng ký một tác vụ chuyển đổi mọi lớp cùng nhau:

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

Hãy xem hướng dẫn modifyProjectClasses để tìm hiểu ví dụ về cách sử dụng API này và hãy xem hướng dẫn customizeAgpDsl để tìm hiểu ví dụ về cách đăng ký các phần mở rộng tuỳ chỉnh cho các loại bản dựng Android.

Nếu trường hợp sử dụng của bạn không thuộc bất kỳ API AndroidComponents nào, vui lòng gửi báo cáo lỗi.

Một số trình bổ trợ thường dùng đã được di chuyển để sử dụng những API mới này, bao gồm trình bổ trợ theo dõi hiệu năng của Firebase (1.4.1 tương thích với AGP 8.0) và trình bổ trợ Hilt Gradle (2.40.1 tương thích với AGP 8.0). Trợ lý nâng cấp AGP cũng sẽ giúp các nhà phát triển dự án nâng cấp các trình bổ trợ thường dùng khi cần thiết.

Nếu bạn đang sử dụng Transform API thông qua trình bổ trợ của bên thứ ba, vui lòng cho tác giả biết rằng họ cần cập nhật trình bổ trợ để tương thích với các API mới của AGP 8.0.

AGP 7.2

Sau đây là các nội dung cập nhật API quan trọng cho AGP 7.2.

RenderScript đã ngừng hoạt động

Các API RenderScript ngừng hoạt động kể từ phiên bản AGP 7.2. Chức năng của các API này vẫn sẽ tiếp tục hoạt động, nhưng sẽ tạo ra cảnh báo, và sẽ bị xoá hoàn toàn trong các phiên bản AGP trong tương lai. Để xem hướng dẫn về cách thực hiện chuyển đổi để loại bỏ RenderScript, hãy xem Di chuyển từ RenderScript.

Component.transformClassesWithComponent.setAsmFramesComputationMode đã ngừng hoạt động

Kể từ phiên bản AGP 7.2, các API đo lường mã byte của lớp là Component.transformClassesWithComponent.setAsmFramesComputationMode đã ngừng hoạt động. Các API này đã chuyển sang một khối mới có tên là Component.instrumentation chứa tất cả API liên quan đến việc định cấu hình quá trình đo lường. Để tiếp tục sử dụng các tính năng đo lường này, hãy sử dụng các API tương ứng trong khối mới, như được minh hoạ trong đoạn mã sau đây:

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }