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

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

android skills add agp-9-upgrade

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

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

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

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

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

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

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

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

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

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

إعداد مشروعك

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

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

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

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

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

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

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

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

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

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

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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