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 của bạn sử dụng.
Trong các bản phát hành, thường có các thay đổi về 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 tận dụng các tính năng mới nhất.
Để biết thêm thông tin về cấu trúc dự án được đề xuất cho Trợ lý nâng cấp, hãy xem phần Thiết lập trên trang này.
Các trường hợp sử dụng Trợ lý nâng cấp AGP
Trợ lý nâng cấp AGP sẽ hướng dẫn bạn thực hiện các thay đổi cần thiết để nâng cấp 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. Khi AGP được phát triển, các tệp bản dựng sẽ được cập nhật để hỗ trợ giao diện khi các giao diện 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 phù hợp 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 của bên thứ ba và giúp đảm bảo rằng bạn đang sử dụng các phiên bản trình bổ trợ Gradle của bên thứ ba phù hợp 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 giúp bạn dễ dàng cập nhật các tệp bản dựng và nắm được thông báo lỗi có liên quan sau khi nâng cấp AGP. Trợ lý nâng cấp cũng giải thích lý do bạn cần thực hiện những thay đổi được đề xuấ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 phù hợp với công cụ này, sau đó chạy công cụ này qua Android Studio theo mô tả trong phần Chạy Trợ lý nâng cấp.
Thiết lập dự án
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. Để đảm bảo Trợ lý nâng cấp AGP được thiết lập đúng cách, hãy đọc các phần sau đây.
Xác định cấu trúc cho dự án của bạn bằng cách sử dụng tệp bản dựng Gradle và ngôn ngữ chuyên dụng cho miền
Để khai thác Trợ lý nâng cấp AGP theo cách hiệu quả nhất, hãy làm như sau:
- Đị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 các tính năng của Trợ lý nâng cấp theo cách hiệu quả nhất, hãy định cấu hình bản dựng của bạn bằng cách sử dụng các tệp bản dựng này.
- Sử dụng ngôn ngữ chuyên dụng để khai báo miền cho bản dựng: Các tệp bản dựng Gradle được thể hiện bằng Groovy hoặc Kotlin. Tuy nhiên, cách thể hiện 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 tuân thủ các giới hạn này, Trợ lý nâng cấp có thể vẫn không thực hiện được quá trình nâng cấp một cách trơn tru. Hãy xem phần Khắc phục lỗi để nắm được nội dung 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 sử dụng Trợ lý nâng cấp, bạn nên đảm bảo dự án của mình không có bất cứ thay đổi nào chưa được hệ thống kiểm soát phiên bản nắm bắt. Tại thời điểm này, nếu chưa sử dụng tính nă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ể đưa phiên bản mới của dự án vào 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 đây:
Để chạy Trợ lý nâng cấp, hãy chuyển đến Tools > AGP Upgrade Assistant (Công cụ > Trợ lý nâng cấp AGP) hoặc nhấp vào lời nhắc thông báo, như minh hoạ trong Hình 1.
Cửa sổ công cụ xuất hiện sẽ cho thấy thông tin chi tiết về bản nâng cấp mặc định, bao gồm cả phiên bản AGP hiện tại của dự án và phiên bản mới nhất được hỗ trợ bởi phiên bản Android Studio này.
Hình 1. Cửa sổ công cụ Trợ lý nâng cấp AGP khi khởi động với lời nhắc thông báo. Kiểm tra các bước bắt buộc và được đề xuất.
Trong bảng điều khiển bên trái, cây 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 bước này được phân loại theo tính chất là bắt buộc hay được đề xuất khi nâng cấp, cũng như đây có phải là điều kiện tiên quyết của các bước khác hay không. Hãy chọn từng mục một trong cây để xem thêm thông tin chi tiết về từng bước trong bảng điều khiển chính.
Để chạy quá trình nâng cấp, hãy chọn các bước bắt buộc, cũng như những bước mà bạn mong muốn rồi 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à cố gắng đồng bộ hoá bản dựng mới bằng 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, do các phiên bản mới của trình bổ trợ và thư viện cũng có thể cần được tải xuống.
Xem lại báo cáo sau khi nâng cấp. Báo cáo này mô tả các bước đã hoàn tất và cho biết quá trình nâng cấp có thành công hay không. Báo cáo còn có một hành động để huỷ bỏ những thay đổi mà trợ lý nâng cấp đã thực hiện nếu có vấn đề về việc xây dựng hoặc kiểm thử dự án sau khi nâng cấp.
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 hoạt động nâng cấp không ảnh hưởng tới chức năng nào.
Sau khi bạn xác minh được rằng dự án ở trạng thái ổn định, hãy đưa phiên bản mới của dự án vào hệ thống quản lý phiên bản.
Khắc phục lỗi
Nếu Trợ lý nâng cấp đề xuất nâng cấp nhưng quá trình nâng cấp lại không thành công, thì đây thường là kết quả của việc thay đổi các tệp bản dựng, dẫn đến lỗi đồng bộ hoá. Hãy làm theo các bước sau đây để bóc tách và khắc phục lỗi:
Trước tiên, hãy kiểm tra xem đ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ố, thì 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 qua tính năng quản lý phiên bản hoặc qua 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.
Hãy kiểm tra lỗi bằng cách sử dụng hai loại bảng chi tiết nâng cấp sau đây:
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 phiên bản gặp lỗi khi thực hiện quá trình nâng cấp, cách tốt nhất để bóc tách vấn đề là thực hiện một loạt hoạt động nâng cấp nhỏ hơn, lần lượt từng phiên bản, để tìm ra đâu là quá trình 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 xác định được hoạt động nâng cấp kích hoạt sự cố, bạn có thể tắt từng bước một trong quá trình nâng cấp. Nếu có thể, 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 bạn không tìm thấy bước gây ra vấn đề, hãy kiểm tra ghi chú phát hành của trình bổ trợ Gradle bạn đang dùng để tìm vấn đề về 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 giải quyết được việc sử dụng các API nội bộ hoặc API không dùng nữa.
Báo cá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 bạn tự khắc phục được lỗi, hãy báo cáo lỗi ban đầu cho trình theo dõi lỗi để nhóm phát triển có thể giải quyết sự cố.