เครื่องมือช่วยอัปเกรดปลั๊กอิน 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 ก็อาจยังอัปเกรดอย่างราบรื่นไม่สำเร็จ ดูคำแนะนำเกี่ยวกับวิธีแก้ไขหรือรายงานข้อบกพร่องได้ที่หัวข้อแก้ปัญหาข้อผิดพลาด
สำรองข้อมูลโปรเจ็กต์
ก่อนใช้ตัวช่วยอัปเกรด เราขอแนะนำให้โปรเจ็กต์ของคุณไม่มีการเปลี่ยนแปลงที่ยังไม่ได้คอมมิตตามที่ระบบควบคุมเวอร์ชันแสดง หากไม่ได้ใช้การควบคุมเวอร์ชัน ให้ใช้ข้อมูลสำรองของเวอร์ชันที่ทราบล่าสุดว่าใช้งานได้ ในตอนนี้
หลังจากเรียกใช้ผู้ช่วยอัปเกรดและสร้างและทดสอบโปรเจ็กต์เรียบร้อยแล้ว คุณสามารถคอมมิตโปรเจ็กต์เวอร์ชันใหม่ไปยังระบบควบคุมเวอร์ชันได้
เรียกใช้ผู้ช่วยการอัปเกรด
หากต้องการเรียกใช้ผู้ช่วยอัปเกรด ให้ทำตามขั้นตอนต่อไปนี้
หากต้องการเปิดตัว Upgrade Assistant ให้ไปที่ เครื่องมือ > AGP Upgrade Assistant หรือคลิกข้อความแจ้งการแจ้งเตือนตามที่ แสดงในรูปที่ 1
หน้าต่างเครื่องมือที่ปรากฏจะแสดงรายละเอียดของการอัปเกรดเริ่มต้น รวมถึง AGP เวอร์ชันปัจจุบันของโปรเจ็กต์และเวอร์ชันล่าสุด ที่ Android Studio เวอร์ชันนี้รองรับ
รูปที่ 1 หน้าต่างเครื่องมือ AGP Upgrade Assistant เมื่อเปิดใช้พร้อมข้อความแจ้งการแจ้งเตือน ตรวจสอบขั้นตอนที่จำเป็นและแนะนำ
ในแผงด้านซ้าย ต้นไม้ที่มีช่องทำเครื่องหมายจะแสดงรายละเอียดขั้นตอนแต่ละขั้นตอนในการอัปเกรด โดยจัดหมวดหมู่ตามว่าต้องอัปเดตหรือแนะนำให้อัปเดต และเป็นข้อกำหนดเบื้องต้นของขั้นตอนอื่นๆ หรือไม่ เลือกรายการแต่ละรายการในโครงสร้างแบบต้นไม้เพื่อแสดงรายละเอียดเพิ่มเติมเกี่ยวกับแต่ละขั้นตอนในแผงหลัก
หากต้องการเรียกใช้การอัปเกรด ให้เลือกขั้นตอนที่จำเป็นและต้องการ แล้วคลิกเรียกใช้ขั้นตอนที่เลือก
ผู้ช่วยอัปเกรดจะเปลี่ยนไฟล์บิลด์ของโปรเจ็กต์และพยายามซิงค์บิลด์ของโปรเจ็กต์ใหม่กับ Android Studio การดำเนินการนี้อาจใช้เวลาสักครู่หากคุณมีโมดูลจำนวนมาก เนื่องจากอาจต้องดาวน์โหลดปลั๊กอินและไลบรารีเวอร์ชันใหม่
ตรวจสอบรายงานหลังการอัปเกรด รายงานนี้อธิบายขั้นตอนที่ ดำเนินการเสร็จสมบูรณ์แล้ว และระบุว่าการอัปเกรดสำเร็จหรือไม่ นอกจากนี้ ยังรวมถึง การดำเนินการเพื่อเปลี่ยนกลับการเปลี่ยนแปลงที่ผู้ช่วยอัปเกรดทำไว้ในกรณีที่ มีปัญหาในการสร้างหรือทดสอบโปรเจ็กต์หลังการอัปเกรด
เมื่อซิงค์โปรเจ็กต์กับ Android Studio เรียบร้อยแล้ว ให้สร้างโปรเจ็กต์ และเรียกใช้ชุดทดสอบเพื่อยืนยันว่าการดำเนินการอัปเกรดไม่ได้ เปลี่ยนแปลงฟังก์ชันการทำงานใดๆ
เมื่อยืนยันแล้วว่าโปรเจ็กต์อยู่ในสถานะที่ดี ให้คอมมิตเวอร์ชันใหม่ ของโปรเจ็กต์ไปยังระบบควบคุมเวอร์ชัน
แก้ไขข้อผิดพลาด
หากผู้ช่วยอัปเกรดแนะนำให้อัปเกรดแต่การอัปเกรดไม่สำเร็จ โดยปกติแล้ว สาเหตุเกิดจากการเปลี่ยนแปลงไฟล์บิลด์ ซึ่งส่งผลให้การซิงค์ ไม่สำเร็จ ทำตามขั้นตอนต่อไปนี้เพื่อช่วยแยกและแก้ไขข้อผิดพลาด
ก่อนอื่น ให้ตรวจสอบข้อผิดพลาดที่ทำให้การซิงค์ล้มเหลว บางครั้งข้อผิดพลาดมีสาเหตุที่ชัดเจน ซึ่งคุณสามารถแก้ไขได้ในไฟล์บิลด์ของโปรเจ็กต์
หากข้อความแสดงข้อผิดพลาดไม่ชัดเจน หรือไม่ทราบสาเหตุที่ทำให้เกิดปัญหา ให้เปลี่ยนโปรเจ็กต์กลับไปเป็นสถานะเดิมเพื่อแบ่งการอัปเกรด ออกเป็นขั้นตอนย่อยๆ กู้คืนสถานะเดิมจากระบบควบคุมเวอร์ชันหรือจากการสำรองข้อมูล และตรวจสอบว่าโปรเจ็กต์อยู่ในสถานะเดิมและซิงค์กับ Android Studio แล้ว
ตรวจสอบข้อผิดพลาดโดยดูรายละเอียดการอัปเกรด 2 ประเภทต่อไปนี้
อัปเกรดเป็น AGP เวอร์ชันอื่นที่ไม่ใช่เวอร์ชันล่าสุด หากการอัปเกรดที่ผิดพลาดเป็นการอัปเกรดหลายเวอร์ชัน วิธีที่ดีที่สุดในการแยกปัญหาคือการอัปเกรดทีละเวอร์ชัน เพื่อค้นหาการอัปเกรดแรกที่ทำให้เกิดปัญหา
ในการอัปเกรด ให้ทำแต่ละขั้นตอนทีละขั้นตอน เมื่อระบุการอัปเกรดที่ทำให้เกิดปัญหาแล้ว คุณอาจปิดขั้นตอนแต่ละขั้นตอนในการอัปเกรดได้ หากทำได้ ให้ลองทำแต่ละขั้นตอนทีละขั้นตอนเพื่อดูว่าขั้นตอนใดที่ทำให้เกิดข้อผิดพลาด หากไม่พบขั้นตอนที่รับผิดชอบ ให้ตรวจสอบบันทึกประจำรุ่นของปลั๊กอิน Gradle อื่นๆ ที่คุณใช้เพื่อดูปัญหาความเข้ากันได้กับ Gradle หรือ AGP บางครั้งรุ่นใหม่จะแก้ไขการใช้ API ที่เลิกใช้งานแล้ว หรือ API ภายใน
รายงานข้อบกพร่อง บางครั้งขั้นตอนการเตรียมการทั้งหมด และการซิงค์สำเร็จ แต่ขั้นตอนการอัปเกรดขั้นสุดท้ายยังคงล้มเหลว ในกรณีนี้ โปรดรายงานข้อบกพร่อง แม้ว่าคุณจะแก้ไขข้อผิดพลาดด้วยตนเองได้ ให้รายงานความล้มเหลวดั้งเดิมไปยังเครื่องมือติดตามข้อบกพร่อง เพื่อให้ทีมพัฒนาแก้ไขปัญหาได้