ใช้ผู้ช่วยการอัปเกรดปลั๊กอิน Android Gradle

ผู้ช่วยอัปเกรดปลั๊กอิน Android Gradle (AGP) เป็นเครื่องมือใน Android Studio ที่ช่วยคุณอัปเกรดเวอร์ชัน AGP ที่โปรเจ็กต์ใช้

android skills add agp-9-upgrade

มีการเผยแพร่การเปลี่ยนแปลง AGP บ่อยครั้งที่เกี่ยวข้องกับฟีเจอร์ใหม่สำหรับการกำหนดค่าบิลด์, API ใหม่สำหรับใช้โดยปลั๊กอิน Gradle อื่นๆ และการปรับแต่งการผสานรวมบิลด์โปรเจ็กต์กับ Android Studio การอัปเกรดเวอร์ชัน AGP ที่โปรเจ็กต์ใช้จะช่วยให้คุณได้รับประโยชน์จากฟีเจอร์ล่าสุด

ดูข้อมูลเพิ่มเติมเกี่ยวกับโครงสร้างโปรเจ็กต์ที่แนะนำสำหรับผู้ช่วยการอัปเกรดได้ที่การตั้งค่าในหน้านี้

กรณีการใช้งาน AGP Upgrade Assistant

ผู้ช่วยอัปเกรด AGP จะแนะนำการเปลี่ยนแปลงที่จำเป็นในการอัปเกรดเวอร์ชัน AGP กรณีการใช้งานที่พบบ่อยที่สุดสำหรับผู้ช่วยอัปเกรดมีดังนี้

• การเปลี่ยนแปลงไวยากรณ์: ผู้ช่วยอัปเกรดจะพยายามแปลไฟล์บิลด์สำหรับ AGP เวอร์ชันเก่าเป็นไฟล์ที่จำเป็นสำหรับ AGP เวอร์ชันใหม่ เมื่อ AGP ได้รับการพัฒนา ไฟล์บิลด์จะได้รับการอัปเดตเพื่อรองรับอินเทอร์เฟซเมื่อมีการแทนที่ เลิกใช้งาน หรือไม่รองรับเมื่อเวลาผ่านไป

• ข้อกำหนดด้านความเข้ากันได้ระหว่าง AGP กับ Gradle: ผู้ช่วยอัปเกรดจะทราบข้อกำหนดด้านความเข้ากันได้ระหว่าง AGP กับ Gradle และช่วยตรวจสอบว่าคุณใช้ Gradle เวอร์ชันที่จำเป็นสำหรับ AGP เวอร์ชันของคุณ

• ข้อกำหนดด้านความเข้ากันได้ระหว่าง AGP และปลั๊กอิน Gradle ของบุคคลที่สาม: ผู้ช่วยอัปเกรดจะทราบข้อกำหนดด้านความเข้ากันได้ระหว่าง AGP และปลั๊กอิน Gradle ของบุคคลที่สามบางรายการ และช่วยตรวจสอบว่าคุณใช้ปลั๊กอิน Gradle ของบุคคลที่สามเวอร์ชันที่จำเป็นสำหรับ AGP เวอร์ชันของคุณ

โดยทั่วไปแล้ว ผู้ช่วยอัปเกรดจะช่วยให้อัปเดตไฟล์บิลด์และทำความเข้าใจข้อความแสดงข้อผิดพลาดที่เกี่ยวข้องได้ง่ายขึ้นหลังจากอัปเกรด AGP นอกจากนี้ ผู้ช่วยอัปเกรดยังอธิบายเหตุผลที่จำเป็นต้องทำการเปลี่ยนแปลงที่เสนอด้วย

วิธีใช้ผู้ช่วยอัปเกรด AGP

หากต้องการใช้ผู้ช่วยอัปเกรด ให้ตรวจสอบว่าโครงสร้างโปรเจ็กต์รองรับเครื่องมือดังกล่าว แล้วเรียกใช้จาก Android Studio ตามที่อธิบายไว้ในเรียกใช้ผู้ช่วยอัปเกรด

ตั้งค่าโปรเจ็กต์

ก่อนเรียกใช้ผู้ช่วยอัปเกรด ให้ตรวจสอบว่าโปรเจ็กต์ได้รับการจัดรูปแบบและสำรองข้อมูลอย่างถูกต้อง โปรดอ่านส่วนต่อไปนี้เพื่อให้แน่ใจว่าผู้ช่วยการอัปเกรด AGP ได้รับการตั้งค่าอย่างถูกต้อง

จัดโครงสร้างโปรเจ็กต์โดยใช้ไฟล์บิลด์ Gradle และภาษาเฉพาะโดเมน

หากต้องการใช้ผู้ช่วยอัปเกรด AGP ให้เกิดประโยชน์สูงสุด ให้ทำดังนี้

• กำหนดค่าบิลด์โดยใช้ไฟล์บิลด์ Gradle: ผู้ช่วยอัปเกรดอาศัยการวิเคราะห์แบบคงที่ของไฟล์บิลด์ Gradle กำหนดค่าบิลด์โดยใช้ไฟล์บิลด์เหล่านี้เพื่อให้ใช้ประโยชน์จากผู้ช่วยการอัปเกรดได้อย่างเต็มที่ ใช้แคตตาล็อกเวอร์ชัน Gradle เพื่ออ้างอิงทรัพยากร Dependency และปลั๊กอินที่กำหนดไว้ในไฟล์ libs.versions.toml ในไดเรกทอรีย่อย gradle ของโปรเจ็กต์

• ใช้ภาษาเฉพาะโดเมนของบิลด์แบบประกาศ: ไฟล์บิลด์ Gradle จะแสดงเป็น Groovy หรือ Kotlin อย่างไรก็ตาม ยิ่งการแสดงออกของการกำหนดค่าโปรเจ็กต์เป็นแบบประกาศมากเท่าใด ผู้ช่วยอัปเกรดก็ยิ่งมีแนวโน้มที่จะค้นหาตำแหน่งทั้งหมดที่ต้องปรับเปลี่ยนเพื่ออัปเกรดได้สำเร็จมากขึ้นเท่านั้น

แม้ว่าโปรเจ็กต์จะเป็นไปตามข้อจำกัดเหล่านี้ แต่ผู้ช่วยอัปเกรดก็อาจยังอัปเกรดอย่างสมบูรณ์ไม่สำเร็จ ดูคำแนะนำเกี่ยวกับวิธีแก้ไขหรือรายงานข้อบกพร่องได้ที่แก้ปัญหาข้อผิดพลาด

สำรองข้อมูลโปรเจ็กต์

ก่อนใช้ผู้ช่วยอัปเกรด เราขอแนะนำให้โปรเจ็กต์ของคุณไม่มีการเปลี่ยนแปลงที่ยังไม่ได้คอมมิตตามที่ระบบควบคุมเวอร์ชันเห็น หากไม่ได้ใช้การควบคุมเวอร์ชัน ให้ใช้ข้อมูลสำรองของเวอร์ชันที่ทราบว่าใช้งานได้ล่าสุด ณ จุดนี้

หลังจาก Upgrade Assistant ทำงานและสร้างและทดสอบโปรเจ็กต์เรียบร้อยแล้ว คุณสามารถคอมมิตโปรเจ็กต์เวอร์ชันใหม่ลงในระบบควบคุมเวอร์ชันได้

เรียกใช้ผู้ช่วยการอัปเกรด

หากต้องการเรียกใช้ผู้ช่วยอัปเกรด ให้ทำตามขั้นตอนต่อไปนี้

1. หากต้องการเปิดผู้ช่วยอัปเกรด ให้ไปที่เครื่องมือ > ผู้ช่วยอัปเกรด AGP หรือคลิกที่ข้อความแจ้งเตือนดังที่แสดงในรูปที่ 1

   หน้าต่างเครื่องมือที่ปรากฏขึ้นจะแสดงรายละเอียดของการอัปเกรดเริ่มต้น ซึ่งรวมถึง AGP เวอร์ชันปัจจุบันของโปรเจ็กต์และเวอร์ชันล่าสุดที่ Android Studio เวอร์ชันนี้รองรับ

   

2. ดูขั้นตอนที่จำเป็นและขั้นตอนที่แนะนำ

   ในแผงด้านซ้าย แผนผังที่มีช่องทำเครื่องหมายจะแสดงรายละเอียดขั้นตอนต่างๆ ในการอัปเกรด โดยจัดหมวดหมู่ตามความจำเป็นหรือคำแนะนำในการอัปเดต และเป็นข้อกำหนดเบื้องต้นของขั้นตอนอื่นๆ หรือไม่ เลือกแต่ละรายการในแผนผังเพื่อแสดงรายละเอียดเพิ่มเติมเกี่ยวกับแต่ละขั้นตอนในแผงหลัก

3. หากต้องการเรียกใช้การอัปเกรด ให้เลือกขั้นตอนที่จำเป็นและต้องการ แล้วคลิกเรียกใช้ขั้นตอนที่เลือก

   ผู้ช่วยอัปเกรดจะเปลี่ยนไฟล์บิลด์ของโปรเจ็กต์และพยายามซิงค์บิลด์โปรเจ็กต์ใหม่กับ Android Studio ซึ่งอาจใช้เวลาสักครู่หากคุณมีโมดูลจำนวนมาก เนื่องจากอาจต้องดาวน์โหลดปลั๊กอินและไลบรารีเวอร์ชันใหม่

4. ตรวจสอบรายงานหลังการอัปเกรด รายงานนี้จะอธิบายขั้นตอนที่เสร็จสมบูรณ์และระบุว่าการอัปเกรดสำเร็จหรือไม่ นอกจากนี้ยังมี การดำเนินการเพื่อเปลี่ยนกลับการเปลี่ยนแปลงที่ทำโดยผู้ช่วยอัปเกรดหากมี ปัญหาในการสร้างหรือทดสอบโปรเจ็กต์หลังจากการอัปเกรด

5. เมื่อโปรเจ็กต์ซิงค์กับ Android Studio เรียบร้อยแล้ว ให้สร้างโปรเจ็กต์และเรียกใช้ชุดโปรแกรมทดสอบเพื่อยืนยันว่าการดำเนินการอัปเกรดไม่ได้เปลี่ยนแปลงฟังก์ชันการทำงานใดๆ

6. เมื่อยืนยันแล้วว่าโปรเจ็กต์อยู่ในสถานะที่ดี ให้คอมมิตโปรเจ็กต์เวอร์ชันใหม่ไปยังระบบควบคุมเวอร์ชัน

แก้ไขข้อผิดพลาด

หากผู้ช่วยอัปเกรดแนะนำให้อัปเกรดแต่การอัปเกรดไม่สำเร็จ โดยปกติแล้วจะเป็นผลมาจากการเปลี่ยนแปลงไฟล์บิลด์ ซึ่งส่งผลให้การซิงค์ไม่สำเร็จ ทำตามขั้นตอนต่อไปนี้เพื่อช่วยแยกและแก้ไขข้อผิดพลาด

• ก่อนอื่น ให้ตรวจสอบข้อผิดพลาดที่ทำให้การซิงค์ไม่สำเร็จ บางครั้งข้อผิดพลาดก็มีสาเหตุที่ชัดเจน ซึ่งคุณสามารถแก้ไขได้ในไฟล์บิลด์ของโปรเจ็กต์

• หากข้อความแสดงข้อผิดพลาดไม่ชัดเจน หรือไม่แน่ใจว่าสาเหตุของปัญหาคืออะไร ให้คืนค่าโปรเจ็กต์กลับสู่สถานะเดิมเพื่อแบ่งการอัปเกรดออกเป็นขั้นตอนย่อยๆ กู้คืนสถานะเดิมจากการควบคุมเวอร์ชันหรือจากข้อมูลสำรอง และตรวจสอบว่าโปรเจ็กต์อยู่ในสถานะเดิมและซิงค์กับ Android Studio แล้ว

ตรวจสอบข้อผิดพลาดโดยทำตามรายละเอียดการอัปเกรด 2 ประเภทต่อไปนี้

• อัปเกรดเป็น AGP เวอร์ชันอื่นที่ไม่ใช่เวอร์ชันล่าสุด หากการอัปเกรดที่เกิดข้อผิดพลาดเป็นการอัปเกรดหลายเวอร์ชัน วิธีที่ดีที่สุดในการแยกปัญหาคือการอัปเกรดทีละน้อยๆ จากเวอร์ชันหนึ่งไปยังอีกเวอร์ชันหนึ่ง เพื่อค้นหาการอัปเกรดแรกที่ทำให้เกิดปัญหา

• ในการอัปเกรด ให้ทำตามขั้นตอนทีละขั้นตอน เมื่อระบุการอัปเกรดที่ทำให้เกิดปัญหาได้แล้ว คุณอาจปิดแต่ละขั้นตอนในการอัปเกรดได้ หากทำได้ ให้ลองทำแต่ละขั้นตอนทีละขั้นตอนเพื่อดูว่าขั้นตอนใดเป็นสาเหตุของข้อผิดพลาด หากไม่พบขั้นตอนที่ทำให้เกิดปัญหา ให้ตรวจสอบบันทึกประจำรุ่นของปลั๊กอิน Gradle อื่นๆ ที่คุณใช้เพื่อดูปัญหาความเข้ากันได้กับ Gradle หรือ AGP บางครั้งรุ่นใหม่อาจแก้ไขการใช้ API ที่เลิกใช้งานแล้วหรือ API ภายใน

• รายงานข้อบกพร่อง บางครั้งขั้นตอนการเตรียมการและการซิงค์ทั้งหมดก็สำเร็จ แต่ขั้นตอนการอัปเกรดขั้นสุดท้ายยังคงไม่สำเร็จ ในกรณีนี้ โปรดรายงานข้อบกพร่อง แม้ว่าคุณจะแก้ไขข้อผิดพลาดได้ด้วยตนเอง แต่ก็ควรรายงานข้อผิดพลาดที่เกิดขึ้นในตอนแรกไปยังเครื่องมือติดตามข้อบกพร่อง เพื่อให้ทีมพัฒนาแก้ไขปัญหาได้