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

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

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

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

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

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

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

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

• กำหนดค่าบิลด์โดยใช้ไฟล์บิลด์ Gradle: Upgrade Assistant อาศัยการวิเคราะห์แบบคงที่ของไฟล์บิลด์ Gradle หากต้องการใช้ ผู้ช่วยการอัปเกรดให้ได้ประโยชน์สูงสุด ให้กำหนดค่าบิลด์โดยใช้ไฟล์บิลด์ต่อไปนี้

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

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

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

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

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

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

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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