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

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

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

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

กรณีการใช้งานตัวช่วยอัปเกรด AGP

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

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

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

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

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

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

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

สร้างโปรเจ็กต์

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

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

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

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

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

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

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

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

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

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

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

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

    หน้าต่างเครื่องมือ AGP Upgrade Assistant เมื่อเปิดใช้ และข้อความแจ้งการแจ้งเตือน
    รูปที่ 1 หน้าต่างเครื่องมือ AGP Upgrade Assistant เมื่อเปิดใช้พร้อมข้อความแจ้งการแจ้งเตือน

  2. ตรวจสอบขั้นตอนที่จำเป็นและแนะนำ

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

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

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

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

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

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

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

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

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

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

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

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

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

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