استخدام "مساعد ترقية مكوّن Google Gradle الإضافي" على Android

"مساعد ترقية" المكوّن الإضافي لنظام Gradle المتوافق مع Android ‏(AGP) هو أداة في "استوديو Android" تساعدك في ترقية إصدار AGP الذي يستخدمه مشروعك.

يتم إصدار تحديثات متكررة لتغييرات AGP المتعلقة بالميزات الجديدة لضبط عملية الإنشاء، وواجهات برمجة التطبيقات الجديدة التي تستخدمها مكوّنات Gradle الإضافية الأخرى، وتحسينات على دمج عملية إنشاء المشروع مع "استوديو Android". تتيح لك ترقية إصدار AGP الذي يستخدمه مشروعك الاستفادة من أحدث الميزات.

لمزيد من المعلومات حول بنية المشروع المقترَحة لأداة Upgrade Assistant، يُرجى الاطّلاع على الإعداد في هذه الصفحة.

حالات استخدام "مساعد ترقية AGP"

يساعدك "مساعد ترقية" Android Gradle Plugin في إجراء التغييرات اللازمة لترقية إصدارات Android Gradle Plugin. في ما يلي حالات الاستخدام الأكثر شيوعًا لـ "مساعد الترقية":

  • تغييرات في البنية: يحاول "مساعد الترقية" ترجمة ملفات الإصدارات القديمة من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" إلى ملفات الإصدارات الأحدث من المكوّن الإضافي. أثناء تطوير AGP، يتم تعديل ملفات الإصدارات لتتوافق مع الواجهات التي يتم استبدالها أو إيقافها نهائيًا أو التي تصبح غير متوافقة بمرور الوقت.

  • متطلبات التوافق بين AGP وGradle: يدرك "مساعد الترقية" متطلبات التوافق بين AGP وGradle ويساعد في التأكّد من استخدام إصدار Gradle المطلوب لإصدار AGP.

  • متطلبات التوافق بين مكوّن AGP الإضافي ومكوّنات Gradle الإضافية التابعة لجهات خارجية: يأخذ "مساعد الترقية" في الاعتبار متطلبات التوافق بين مكوّن AGP الإضافي وبعض مكوّنات Gradle الإضافية التابعة لجهات خارجية، ويساعد في التأكّد من استخدامك إصدارات مكوّنات Gradle الإضافية التابعة لجهات خارجية المطلوبة لإصدار مكوّن AGP الإضافي.

بشكل عام، يسهّل Upgrade Assistant تحديث ملفات الإصدارات وفهم رسائل الخطأ ذات الصلة بعد ترقية AGP. ويشرح "مساعد الترقية" أيضًا سبب ضرورة إجراء التغييرات المقترَحة.

كيفية استخدام "مساعِد ترقية AGP"

لاستخدام Upgrade Assistant، تأكَّد من أنّ بنية مشروعك تتوافق مع الأداة، ثم شغِّلها من "استوديو Android"، كما هو موضَّح في تشغيل Upgrade Assistant.

إعداد مشروعك

قبل تشغيل "مساعد الترقية"، تأكَّد من أنّ مشروعك منسَّق بشكل صحيح وتم الاحتفاظ بنسخة احتياطية منه. للتأكّد من إعداد "مساعد ترقية مكوّن Android Gradle الإضافي" بشكل صحيح، يُرجى قراءة الأقسام التالية.

تنظيم مشروعك باستخدام ملفات إصدار Gradle ولغة خاصة بالنطاق

للاستفادة إلى أقصى حدّ من "مساعِد ترقية AGP"، اتّبِع الخطوات التالية:

  • ضبط الإصدار باستخدام ملفات إصدار Gradle: تعتمد "مساعدة الترقية" على التحليل الثابت لملفات إصدار Gradle. للاستفادة إلى أقصى حد من "مساعِد الترقية"، اضبط عملية الإنشاء باستخدام ملفات الإنشاء هذه. استخدِم كتالوجات إصدارات Gradle للإشارة إلى التبعيات والمكوّنات الإضافية المحدّدة في ملف libs.versions.toml في الدليل الفرعي gradle لمشروعك.
  • استخدام لغة خاصة بالنطاق لإنشاء الإصدارات التعريفية: يتم التعبير عن ملفات إصدار Gradle بلغة Groovy أو Kotlin. ومع ذلك، كلما زاد التعبير التعريفي لإعدادات المشروع، زاد احتمال عثور "مساعد الترقية" على جميع الأماكن التي تحتاج إلى تعديل للترقية.

حتى إذا كان المشروع يتوافق مع هذه القيود، قد يتعذّر على "مساعد الترقية" إجراء ترقية نظيفة. يمكنك الاطّلاع على تحديد المشاكل وحلّها للحصول على إرشادات حول كيفية حلّ الأخطاء أو الإبلاغ عن الأخطاء.

الاحتفاظ بنسخة احتياطية من مشروعك

قبل استخدام "مساعد الترقية"، ننصحك بالتأكّد من أنّ مشروعك لا يتضمّن أي تغييرات غير مُثبَّتة، كما يظهر في نظام التحكّم في الإصدارات. إذا لم تكن تستخدم التحكم في الإصدارات، فاستخدم نسخة احتياطية من آخر إصدار جيد معروف في هذه المرحلة.

بعد تشغيل "مساعد الترقية" وإنشاء المشروع واختباره بنجاح، يمكنك إرسال الإصدار الجديد من المشروع إلى نظام التحكّم في الإصدارات.

تشغيل "مساعِد الترقية"

لتشغيل "مساعد الترقية"، اتّبِع الخطوات التالية:

  1. لتشغيل Upgrade Assistant، انتقِل إلى الأدوات > AGP Upgrade Assistant أو انقر على الإشعار، كما هو موضّح في الشكل 1.

    تعرض نافذة الأدوات التي تظهر تفاصيل الترقية التلقائية، بما في ذلك الإصدار الحالي من AGP في المشروع وأحدث إصدار متوافق مع هذا الإصدار من "استوديو Android".

    نافذة أدوات "مساعد ترقية AGP" عند تشغيلها، وإشعار الطلب
    الشكل 1: نافذة أداة AGP Upgrade Assistant عند تشغيلها من خلال إشعار

  2. اطّلِع على الخطوات المطلوبة والتي يُنصح بها.

    في اللوحة اليمنى، توضّح الشجرة التي تحتوي على مربّعات اختيار الخطوات الفردية في الترقية، ويتم تصنيفها حسب ما إذا كانت مطلوبة أو يُنصح بتعديلها وما إذا كانت متطلبات أساسية لخطوات أخرى. اختَر عناصر فردية في العرض التدرّجي لعرض المزيد من التفاصيل حول كل خطوة في اللوحة الرئيسية.

  3. لتشغيل الترقية، اختَر الخطوات المطلوبة وأي خطوات إضافية تريد تشغيلها وانقر على تشغيل الخطوات المحدّدة.

    يغيّر Upgrade Assistant ملفات إصدار المشروع ويحاول مزامنة إصدار المشروع الجديد مع "استوديو Android". قد يستغرق ذلك بعض الوقت إذا كان لديك العديد من الوحدات، حيث قد تحتاج إلى تنزيل إصدارات جديدة من المكونات الإضافية والمكتبات.

  4. راجِع تقرير ما بعد الترقية. يصف هذا التقرير الخطوات التي تم إكمالها وما إذا كانت الترقية ناجحة أم غير ناجحة. ويتضمّن أيضًا إجراءً للتراجع عن التغييرات التي أجراها مساعد الترقية في حال حدوث مشاكل في إنشاء المشروع أو اختباره بعد الترقية.

  5. بعد مزامنة المشروع بنجاح مع "استوديو Android"، أنشئ المشروع وشغِّل حِزم الاختبار للتأكّد من أنّ عملية الترقية لم تغيّر أي وظيفة.

  6. بعد التأكّد من أنّ مشروعك في حالة جيدة، يمكنك إرسال الإصدار الجديد من مشروعك إلى نظام التحكّم في الإصدارات.

تحري الأخطاء وإصلاحها

إذا اقترح "مساعد الترقية" ترقية ولكن تعذّر إجراؤها، يكون ذلك عادةً نتيجة إجراء تغييرات على ملفات الإصدار، ما يؤدي إلى تعذُّر المزامنة. اتّبِع الخطوات التالية للمساعدة في عزل الخطأ وإصلاحه:

  • أولاً، افحص الخطأ الذي أدى إلى تعذُّر المزامنة. في بعض الأحيان، يكون للخطأ سبب واضح يمكنك معالجته في ملفات إصدار المشروع.

  • إذا لم تكن رسالة الخطأ واضحة، أو لم يكن سبب المشكلة واضحًا، فأعِد المشروع إلى حالته الأصلية لتقسيم الترقية إلى خطوات أصغر. استعِد الحالة الأصلية من التحكّم في الإصدارات أو من النُسخ الاحتياطية، وتأكَّد من أنّ المشروع في حالته الأصلية ومتزامن مع "استوديو Android".

يمكنك التحقيق في الخطأ من خلال اتّباع نوعَين من تفاصيل الترقية:

  • الترقية إلى إصدار مختلف من AGP ليس الإصدار الأخير إذا كانت الترقية التي حدثت فيها المشكلة هي ترقية لعدد كبير من الإصدارات، فإن أفضل طريقة لعزل المشكلة هي إجراء سلسلة من الترقيات الأصغر، من إصدار إلى آخر، للعثور على الترقية الأولى التي تؤدي إلى حدوث المشكلة.

  • أثناء الترقية، نفِّذ الخطوات الفردية واحدة تلو الأخرى. بعد تحديد الترقية التي تؤدي إلى حدوث المشكلة، قد يكون من الممكن إيقاف خطوات فردية في الترقية. وإذا كان ذلك ممكنًا، جرِّب تنفيذ كل خطوة على حدة لمعرفة أي من هذه الخطوات هو المسؤول عن الخطأ. إذا لم تتمكّن من العثور على الخطوة المسؤولة، راجِع ملاحظات الإصدار لأي مكوّنات إضافية أخرى من Gradle تستخدمها بحثًا عن مشاكل التوافق مع Gradle أو AGP. في بعض الأحيان، يعالج الإصدار الجديد استخدام واجهات برمجة التطبيقات المهملة أو الداخلية.

  • الإبلاغ عن خطأ في بعض الأحيان، تنجح جميع الخطوات التحضيرية والمزامنة، ولكن تفشل خطوة الترقية النهائية. في هذه الحالة، يُرجى الإبلاغ عن الخطأ. حتى إذا نجحت في إصلاح الخطأ بنفسك، أبلِغ عن الخطأ الأصلي إلى أداة تتبُّع الأخطاء، حتى يتمكّن فريق التطوير من معالجة المشكلة.