การอัปเดต API ปลั๊กอิน Android Gradle

หน้านี้จะติดตามการเลิกใช้งานและการนำ API ของปลั๊กอิน Android Gradle (AGP) ออก รวมถึงให้ข้อมูลเกี่ยวกับวิธีอัปเดตโค้ดของคุณตามความเหมาะสม

เครื่องมือติดตามการเลิกใช้งานและการนำ API ออก

ตารางต่อไปนี้สรุปเวลาที่ AGP API เลิกใช้งานและถูกนำออกในแง่ของเวอร์ชัน AGP

API	เลิกใช้งานใน AGP เวอร์ชัน	นำออกจาก AGP เวอร์ชัน
Component.setAsmFramesComputationMode	7.2
Component.transformClassesWith	7.2
RenderScript	7.2
Transform	7.2	8.0

AGP 8.12

ปลั๊กอิน Android Gradle 8.12.0 มีการเปลี่ยนแปลง API ที่สำคัญต่อไปนี้

การเปลี่ยนแปลงลักษณะการทำงาน: ตัวเลือก includeAndroidResources จะผสานไฟล์ Manifest จากไดเรกทอรีทดสอบ

ตอนนี้คุณสามารถสร้างไฟล์ AndroidManifest.xml ในไดเรกทอรีต้นทางของการทดสอบเพื่อปรับแต่งไฟล์ Manifest สำหรับ Unit Test ด้วยตัวเลือก android.testOptions.unitTests.includeAndroidResources ได้แล้ว ไฟล์ Manifest ของการทดสอบจะผสานรวมเข้ากับไฟล์ Manifest หลักของแอป ปัญหา #127986458

AGP 8.10

ปลั๊กอิน Android Gradle 8.10.0 มีการเปลี่ยนแปลง API ที่สำคัญต่อไปนี้

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบระดับแหล่งที่มา: finalizeDsl ต้องใช้ประเภทที่มีพารามิเตอร์แล้ว

เพื่อให้ใช้ AndroidComponentsExtension กับปลั๊กอิน com.android.kotlin.multiplatform.library ได้โดยตรง ระบบจึงผ่อนปรนขอบเขตประเภทใน finalizeDsl

ตัวอย่างเช่น หากคุณใช้ประเภทข้อมูลดิบของ AndroidComponentsExtension เพื่อระบุแอปพลิเคชันและไลบรารี ให้ทำดังนี้

extensions.getByType(AndroidComponentsExtension::class).finalizeDsl { androidExtension ->
  androidExtension.experimentalProperties["android.example"] = true
}

คุณจะต้องปรับซอร์สโค้ดก่อนหรือระหว่างการอัปเกรดให้มีลักษณะดังนี้

extensions.getByType<AndroidComponentsExtension<CommonExtension<*, *, *, *, *, *>, *, *>>().finalizeDsl { androidExtension ->
  androidExtension.experimentalProperties["android.example"] = true
}

โปรดทราบว่าหากต้องการเขียนโค้ด finalizeDsl ที่ใช้ได้กับทั้งปลั๊กอิน com.android.library และ com.android.application ปัจจุบัน รวมถึงปลั๊กอิน com.android.kotlin.multiplatform.library ใหม่ คุณอาจต้องตรวจสอบประเภทที่รันไทม์ ดังนี้

extensions.getByType<AndroidComponentsExtension<*, *, *>>().finalizeDsl { androidExtension ->
  when(androidExtension) {
    is CommonExtension<*, *, *, *, *, *> -> androidExtension.experimentalProperties["android.example"] = true
    is KotlinMultiplatformAndroidLibraryExtension -> androidExtension.experimentalProperties["android.example"] = true
  }
}

การเปลี่ยนแปลงนี้เป็นการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบในระดับแหล่งที่มาเท่านั้น และจะไม่ส่งผลต่อปลั๊กอินไบนารี

AGP 8.8

ข้อมูลต่อไปนี้เป็นการอัปเดต API ที่สำคัญสำหรับ AGP 8.8

เลิกใช้งานการกำหนดค่าทรัพยากรแล้ว

การกำหนดค่าทรัพยากรเลิกใช้งานแล้วตั้งแต่ AGP 8.8 เนื่องจาก AGP ไม่รองรับความหนาแน่นของทรัพยากรที่แตกต่างกันอีกต่อไป และตอนนี้ Google Play Console กำหนดให้ต้องเผยแพร่แอปเป็น App Bundle สำหรับการกำหนดค่าภาษา คุณสามารถระบุภาษาที่แอปรองรับโดยใช้ localeFilters DSL เพื่อแมปการกำหนดค่าภาษาไปยังทรัพยากรที่เกี่ยวข้อง

AGP 8.0

ต่อไปนี้เป็นการอัปเดต API ที่สำคัญสำหรับ AGP 8.0

นำ Transform API ออกแล้ว

ตั้งแต่ AGP 8.0 เป็นต้นไป ระบบจะนำ Transform API ออก ซึ่งหมายความว่าระบบจะนำคลาสทั้งหมดในแพ็กเกจ com.android.build.api.transform ออก

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

API ทดแทน

ไม่มี API ใดที่ใช้แทน Transform API ได้โดยตรง แต่มี API ใหม่ที่กำหนดเป้าหมายสำหรับ Use Case แต่ละรายการ API ทดแทนทั้งหมดอยู่ในบล็อก androidComponents {} API เหล่านี้ทั้งหมดพร้อมใช้งานใน AGP 7.2

การรองรับการเปลี่ยนรูปแบบไบต์โค้ด

หากต้องการเปลี่ยนรูปแบบไบต์โค้ด ให้ใช้ Instrumentation API สำหรับไลบรารี คุณสามารถลงทะเบียนการวัดคุมสำหรับคลาสโปรเจ็กต์ที่อยู่ในเครื่องเท่านั้น ส่วนแอปและการทดสอบ คุณสามารถเลือกที่จะลงทะเบียนการวัดคุมสำหรับคลาสในเครื่องเท่านั้นหรือคลาสทั้งหมด ซึ่งรวมถึงทรัพยากร Dependency ในเครื่องและระยะไกล หากต้องการใช้ API นี้ การวัดจะทำงานแยกกันในแต่ละคลาส โดยมีสิทธิ์เข้าถึงคลาสอื่นๆ ใน classpath อย่างจำกัด (ดูข้อมูลเพิ่มเติมได้ที่ createClassVisitor()) ข้อจำกัดนี้จะช่วยปรับปรุงประสิทธิภาพของทั้งบิลด์แบบเต็มและแบบเพิ่ม และช่วยให้ API มีประสิทธิภาพมากขึ้น ไลบรารีแต่ละรายการจะได้รับการวัดค่าพร้อมกันทันทีที่พร้อม แทนที่จะรอให้การคอมไพล์ทั้งหมดเสร็จสมบูรณ์ นอกจากนี้ การเปลี่ยนแปลงในคลาสเดียวหมายความว่าเฉพาะคลาสที่ได้รับผลกระทบเท่านั้นที่ต้องได้รับการปรับแต่งใหม่ในบิลด์ที่เพิ่มขึ้น ดูตัวอย่างวิธีใช้ Instrumentation API ได้ที่สูตร AGP การเปลี่ยนรูปแบบคลาสด้วย ASM

การรองรับการเพิ่มคลาสที่สร้างขึ้นลงในแอป

หากต้องการเพิ่มคลาสที่สร้างขึ้นเพิ่มเติมลงในแอป ให้ใช้ Artifacts API กับ MultipleArtifact.ALL_CLASSES_DIRS โดยเฉพาะอย่างยิ่ง ให้ใช้

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

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

การรองรับการเปลี่ยนรูปแบบโดยอิงตามการวิเคราะห์ทั้งโปรแกรม

หากต้องการใช้การเปลี่ยนรูปแบบตามการวิเคราะห์ทั้งโปรแกรม คุณสามารถเปลี่ยนรูปแบบคลาสทั้งหมดพร้อมกันในงานเดียวได้ ควรใช้วิธีนี้ด้วยความระมัดระวังเนื่องจากมีต้นทุนด้านประสิทธิภาพของบิลด์สูงกว่าการใช้ Instrumentation API มาก หากปลั๊กอินใช้ API นี้ เราขอแนะนำให้เลือกใช้การเปลี่ยนรูปแบบตามประเภทบิลด์ เพื่อให้นักพัฒนาแอปปิดใช้การเปลี่ยนรูปแบบสำหรับบิลด์การพัฒนาได้

หากต้องการลงทะเบียนงานที่เปลี่ยนรูปแบบคลาสทั้งหมดพร้อมกัน ปลั๊กอิน Android Gradle 7.4 จะเปิดตัว API Artifacts.forScope หากต้องการเปลี่ยนรูปแบบคลาสทั้งหมดในโปรเจ็กต์ปัจจุบัน ให้ใช้ Artifacts.forScope.PROJECT หากต้องการเปลี่ยนรูปแบบคลาสทั้งหมดในโปรเจ็กต์ปัจจุบัน โปรเจ็กต์ที่นำเข้า และทรัพยากร Dependency ภายนอกทั้งหมด ให้ใช้ Artifacts.forScope.ALL โค้ดต่อไปนี้แสดงวิธีใช้ Artifacts.forScope.ALL เพื่อลงทะเบียนงานที่เปลี่ยนรูปแบบคลาสทั้งหมดพร้อมกัน

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

ดูสูตร modifyProjectClasses เพื่อดูตัวอย่างวิธีใช้ API นี้ และสูตร customizeAgpDsl เพื่อดูตัวอย่างวิธีลงทะเบียนส่วนขยายที่กำหนดเองกับประเภทบิลด์ Android

หากกรณีการใช้งานของคุณไม่ครอบคลุมอยู่ใน API ของ AndroidComponents คุณสามารถรายงานข้อบกพร่องได้

ปลั๊กอินที่ใช้กันโดยทั่วไปหลายรายการได้ย้ายข้อมูลไปใช้ API ใหม่เหล่านี้แล้ว ซึ่งรวมถึงปลั๊กอิน Firebase Performance Monitoring (1.4.1 เข้ากันได้กับ AGP 8.0) และปลั๊กอิน Hilt Gradle (2.40.1 เข้ากันได้กับ AGP 8.0) ผู้ช่วยอัปเกรด AGP จะช่วยนักพัฒนาโปรเจ็กต์อัปเกรดปลั๊กอินที่ใช้กันโดยทั่วไปตามความจำเป็นด้วย

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

AGP 7.2

ต่อไปนี้เป็นการอัปเดต API ที่สำคัญสำหรับ AGP 7.2

RenderScript เลิกใช้งานแล้ว

ตั้งแต่ AGP 7.2 เป็นต้นไป เราจะเลิกใช้งาน RenderScript API โดยจะยังคงทำงานต่อไป แต่จะแสดงคำเตือน และจะถูกนำออกอย่างสมบูรณ์ใน AGP เวอร์ชันต่อๆ ไป ดูคำแนะนำเกี่ยวกับวิธีเปลี่ยนจากการใช้ RenderScript ได้ที่ย้ายข้อมูลจาก RenderScript

Component.transformClassesWith และ Component.setAsmFramesComputationMode เลิกใช้งานแล้ว

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

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }