Sử dụng Trợ lý nâng cấp trong trình bổ trợ Android cho Gradle

Trợ lý nâng cấp (Upgrade Assistant) trong trình bổ trợ Android cho Gradle (AGP) là một công cụ trong Android Studio giúp bạn nâng cấp các phiên bản AGP mà dự án sử dụng.

Chúng tôi thường xuyên phát hành các thay đổi AGP với các tính năng mới để định cấu hình bản dựng, các API mới hỗ trợ các trình bổ trợ Gradle khác đồng thời tinh chỉnh việc tích hợp bản dựng dự án trong Android Studio. Việc nâng cấp phiên bản AGP mà dự án sử dụng cho phép bạn hưởng lợi từ các tính năng mới nhất.

Trợ lý nâng cấp AGP dùng để làm gì?

Trợ lý nâng cấp AGP sẽ hướng dẫn bạn các bước cần thiết để nâng cấp các phiên bản AGP. Dưới đây là những trường hợp sử dụng Trợ lý nâng cấp phổ biến nhất:

  • Thay đổi cú pháp: Trợ lý nâng cấp sẽ dịch các tệp bản dựng từ một phiên bản AGP cũ hơn cho những thành phần cần sử dụng phiên bản AGP mới hơn. Trong quá trình phát triển AGP, chúng tôi cập nhật các tệp bản dựng để hỗ trợ giao diện khi các tệp này được thay thế, ngừng sử dụng hoặc không được hỗ trợ theo thời gian.

  • Yêu cầu về khả năng tương thích giữa AGP và Gradle: Trợ lý nâng cấp nhận biết được các yêu cầu về khả năng tương thích giữa AGP và Gradle và giúp đảm bảo phiên bản Gradle bạn đang sử dụng đúng với yêu cầu của phiên bản AGP đang dùng.

  • Yêu cầu về khả năng tương thích giữa AGP và các trình bổ trợ Gradle của bên thứ ba: Trợ lý nâng cấp nhận biết được các yêu cầu về khả năng tương thích giữa AGP và một số trình bổ trợ cho Gradle từ bên thứ ba và giúp đảm bảo rằng bạn đang sử dụng các phiên bản của trình bổ trợ Gradle từ bên thứ ba đúng với yêu cầu của phiên bản AGP bạn đang dùng.

Nhìn chung, Trợ lý nâng cấp chỉ có mục đích loại bỏ một số thời điểm dùng các thay đổi theo phương pháp thử và sai để tạo tệp, hoặc phỏng đoán ý nghĩa của thông báo lỗi sau khi nâng cấp, đồng thời giải thích lý do vì sao đề xuất sửa đổi đó là cần thiết.

Cách sử dụng Trợ lý nâng cấp AGP

Để sử dụng Trợ lý nâng cấp, hãy đảm bảo cấu trúc dự án của bạn đủ điều kiện, sau đó chạy công cụ Trợ lý nâng cấp này trong Android Studio như mô tả dưới đây.

Thiết lập

Trước khi chạy Trợ lý nâng cấp, hãy đảm bảo dự án của bạn được định dạng và sao lưu đúng cách.

Định cấu trúc dự án của bạn bằng cách sử dụng tệp bản dựng Gradle và ngôn ngữ miền chuyên biệt

Trợ lý nâng cấp AGP sẽ hoạt động hiệu quả nếu bạn thực hiện theo hướng dẫn dưới đây:

  • Định cấu hình bản dựng bằng cách sử dụng tệp bản dựng Gradle: Trợ lý nâng cấp dựa vào kết quả phân tích tĩnh của các tệp bản dựng Gradle. Để khai thác tối đa các tính năng của Trợ lý nâng cấp, bạn nên định cấu hình bản dựng của mình bằng cách sử dụng các tệp bản dựng này. Xin lưu ý rằng Trợ lý nâng cấp không hỗ trợ các dự án sử dụng buildSrc để định nghĩa các hằng số và biến dùng trong tệp bản dựng. Nhìn chung, việc sử dụng buildSrc để sắp xếp cấu trúc dự án là không hiệu quả: bất kỳ thay đổi nào đối với hằng số và biến buildSrc, dù nhỏ đến mức nào, sẽ kích hoạt quá trình tái xây dựng toàn bộ dự án.
  • Sử dụng ngôn ngữ miền chuyên biệt cho bản dựng đã khai báo: Tệp bản dựng Gradle được thể hiện thông qua các ngôn ngữ lập trình, Groovy và/hoặc Kotlin; tuy nhiên, biểu thức của cấu hình dự án càng được khai báo rõ ràng thì khả năng Trợ lý nâng cấp xác định được các vị trí cần điều chỉnh để nâng cấp càng cao.

Ngay cả khi dự án không chạy trên những giới hạn này, Trợ lý nâng cấp vẫn có thể không thực hiện được quá trình nâng cấp sạch. Hãy xem phần Khắc phục sự cố để được hướng dẫn về cách giải quyết hoặc báo cáo lỗi.

Sao lưu dự án của bạn

Trước khi bắt đầu sử dụng Trợ lý nâng cấp, bạn nên đảm bảo dự án của bạn không có bất kỳ thay đổi nào chưa được hệ thống kiểm soát phiên bản hiển thị. Tại thời điểm này, nếu chưa sử dụng quản lý phiên bản thì bạn nên sao lưu phiên bản có dữ liệu ổn định gần nhất.

Sau khi Trợ lý nâng cấp chạy và xây dựng thành công dự án, bạn có thể chuyển phát phiên bản mới của dự án sang hệ thống kiểm soát phiên bản của mình.

Chạy Trợ lý nâng cấp

Để chạy Trợ lý nâng cấp, hãy làm theo các bước sau:

  1. Chạy Trợ lý nâng cấp thông qua lời nhắc thông báo hoặc bằng cách điều hướng đến Tools > AGP Upgrade Assistant… (Công cụ > Trợ lý nâng cấp AGP…) Cửa sổ công cụ khi xuất hiện sẽ hiển thị thông tin chi tiết về bản nâng cấp mặc định từ phiên bản hiện tại của AGP của Dự án lên phiên bản mới nhất được hỗ trợ bởi phiên bản Android Studio này.
Cửa sổ công cụ Trợ lý nâng cấp AGP khi khởi chạy và lời nhắc thông báo.
Hình 1. Cửa sổ công cụ Trợ lý nâng cấp AGP khi khởi chạy và lời nhắc thông báo.
  1. Kiểm tra các bước bắt buộc và được khuyến nghị. Trong ngăn bên trái, một cây gồm các hộp đánh dấu chứa thông tin chi tiết về từng bước trong quá trình nâng cấp. Các danh mục này được phân loại theo tính chất bắt buộc hoặc được khuyến nghị và liệu các điều kiện đó có là điều kiện tiên quyết của các bước khác hay không. Chọn từng mục một trong cây để hiển thị thêm thông tin chi tiết về từng bước trong bảng ngăn chính.

  2. Chạy bản nâng cấp bằng cách chọn các bước cần thiết hoặc theo yêu cầu và nhấp vào Run selected steps (Chạy các bước đã chọn). Trợ lý nâng cấp sẽ thay đổi các tệp bản dựng của dự án và đồng bộ hoá dự án bản dụng mới với Android Studio. Quá trình này có thể mất một chút thời gian nếu bạn có nhiều mô-đun, bở các phiên bản mới của trình bổ trợ và thư viện xuống cũng có thể cần tải xuống.

  3. Sau khi dự án được đồng bộ hoá thành công với Android Studio, hãy xây dựng dự án và chạy bộ kiểm thử để xác minh rằng thao tác nâng cấp không ảnh hưởng tới chức năng nào.

  4. Sau khi bạn đã xác minh rằng dự án ở trạng thái ổn định, hãy chuyển phát phiên bản mới của dự án với hệ thống quản lý phiên bản.

Khắc phục sự cố

Nếu Trợ lý nâng cấp cung cấp một bản nâng cấp, nhưng quá trình nâng cấp không thành công (thường là do thay đổi các tệp bản dựng dẫn đến lỗi đồng bộ hoá), bạn có thể thực hiện theo hướng dẫn dưới đây để bóc tách và khắc phục vấn đề.

  • Trước tiên, hãy kiểm tra điều gì dẫn đến lỗi đồng bộ hoá đó. Đôi khi, lỗi xảy ra có nguyên nhân rõ ràng. Bạn có thể giải quyết các lỗi này trong các tệp bản dựng của dự án.

  • Nếu thông báo lỗi không rõ ràng hoặc không xác định được nguyên nhân gây ra sự cố, bạn cần đưa dự án về trạng thái ban đầu để chia nhỏ quá trình nâng cấp thành các bước nhỏ hơn. Khôi phục trạng thái ban đầu từ quản lý phiên bản hoặc từ các bản sao lưu, đồng thời đảm bảo dự án (ở trạng thái gốc) đã được đồng bộ hoá với Android Studio. Sau đó, bạn có thể điều tra bằng cách sử dụng hai loại bảng phân tích nâng cấp sau:

    • Nâng cấp lên phiên bản AGP nhưng không phải là phiên bản mới nhất. Nếu một số lượng lớn các phiên bản của bản nâng cấp gặp lỗi, cách tốt nhất để cải thiện và bóc tách vấn đề là thực hiện một loạt các bản nâng cấp nhỏ hơn, lần lượt từng phiên bản, để tìm ra đâu là bản nâng cấp đầu tiên kích hoạt sự cố.
    • Trong một bản nâng cấp, hãy thực hiện lần lượt từng bước một. Sau khi tìm thấy bản nâng cấp giữa các phiên bản AGP kế tiếp kích hoạt sự cố, bạn có thể tắt từng bước một trong bản nâng cấp. Tiếp đó, hãy thử thực hiện lần lượt từng bước để xem bước nào gây ra vấn đề. Nếu không tìm thấy bước gây ra vấn đề, bạn nên kiểm tra ghi chú phát hành của toàn bộ trình bổ trợ Gradle bạn đang dùng để tìm vấn đề liên quan đến khả năng tương thích với Gradle hoặc AGP; đôi khi một bản phát hành mới sẽ xuất hiện để giải quyết các API nội bộ hoặc đã ngừng sử dụng.
  • Báo lỗi. Đôi khi, mọi bước sơ bộ và đồng bộ hoá đều thành công nhưng bước nâng cấp cuối cùng lại gặp vấn đề nào đó. Trong trường hợp này, vui lòng báo cáo lỗi.

Ngay cả khi tự khắc phục được lỗi, bạn vẫn cần báo cáo lỗi gốc cho trình theo dõi lỗi để nhóm phát triển có thể giải quyết sự cố.