"مساعد ترقية المكوّن الإضافي لنظام Gradle المتوافق مع Android" (AGP) هو أداة في "استوديو Android" تساعدك في ترقية إصدار AGP الذي يستخدمه مشروعك.
يتم إصدار تغييرات متكررة على "مكوّن Android الإضافي لبرنامج Gradle" (AGP) تتعلّق بالميزات الجديدة لإعداد عملية الإنشاء، وواجهات برمجة التطبيقات الجديدة التي يمكن أن تستخدمها المكوّنات الإضافية الأخرى لبرنامج Gradle، والتحسينات على عملية دمج إنشاء المشروع مع "استوديو Android". تتيح لك ترقية إصدار Android Gradle Plugin المستخدَم في مشروعك الاستفادة من أحدث الميزات.
لمزيد من المعلومات حول بنية المشروع المقترَحة لـ "مساعِد الترقية"، يُرجى الاطّلاع على الإعداد في هذه الصفحة.
حالات استخدام "مساعد ترقية AGP"
يرشدك "مساعد ترقية" Android Gradle Plugin إلى التغييرات اللازمة لترقية إصدارات المكوّن الإضافي. في ما يلي حالات الاستخدام الأكثر شيوعًا لأداة Upgrade Assistant:
تغييرات في البنية: تحاول "أداة الترقية" ترجمة ملفات الإصدار من إصدار قديم من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" إلى الملفات المطلوبة لإصدار أحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android". أثناء تطوير "مكوّن Android Gradle الإضافي"، يتم تعديل ملفات الإنشاء لتتوافق مع الواجهات عند استبدالها أو إيقافها نهائيًا أو عدم توفّرها بمرور الوقت.
متطلبات التوافق بين المكوّن الإضافي لنظام Gradle المتوافق مع Android وGradle: يدرك "مساعد الترقية" متطلبات التوافق بين المكوّن الإضافي لنظام Gradle المتوافق مع Android وGradle ويساعد في ضمان استخدام إصدار Gradle المطلوب لإصدار المكوّن الإضافي لنظام Gradle المتوافق مع Android.
متطلبات التوافق بين "مكوّن Android الإضافي في Gradle" ومكوّنات Gradle الإضافية التابعة لجهات خارجية: يدرك "مساعد الترقية" متطلبات التوافق بين "مكوّن Android الإضافي في Gradle" وبعض مكوّنات Gradle الإضافية التابعة لجهات خارجية، ويساعد في ضمان استخدامك لإصدارات مكوّنات Gradle الإضافية التابعة لجهات خارجية المطلوبة لإصدار "مكوّن Android الإضافي في Gradle".
بشكل عام، يسهّل "مساعد الترقية" تعديل ملفات الإصدار وفهم رسائل الخطأ ذات الصلة بعد ترقية "مكوّن Android الإضافي في Gradle". ويوضّح "مساعد الترقية" أيضًا سبب ضرورة إجراء التغييرات المقترَحة.
كيفية استخدام "أداة ترقية حزمة Android Gradle"
لاستخدام "أداة الترقية"، تأكَّد من أنّ بنية مشروعك تتوافق مع الأداة، ثم شغِّلها من "استوديو Android"، كما هو موضّح في تشغيل "أداة الترقية".
إعداد مشروعك
قبل تشغيل "أداة الترقية"، تأكَّد من تنسيق مشروعك بشكل صحيح ومن الاحتفاظ بنسخة احتياطية منه. لضمان إعداد "مساعِد ترقية AGP" بشكل صحيح، يُرجى قراءة الأقسام التالية.
تنظيم مشروعك باستخدام ملفات تصميم Gradle ولغة خاصة بالمجال
لتحقيق أقصى استفادة من "مساعِد ترقية Android Gradle"، اتّبِع الخطوات التالية:
- ضبط الإصدار باستخدام ملفات إصدار Gradle: يعتمد "مساعد الترقية" على التحليل الثابت لملفات إصدار Gradle. للاستفادة إلى أقصى حدّ من
أداة Upgrade Assistant، اضبط إصدارك باستخدام ملفات الإصدار هذه. استخدِم كتالوجات إصدارات Gradle للإشارة إلى التبعيات والمكوّنات الإضافية المحدّدة في ملف
libs.versions.tomlضمن الدليل الفرعيgradleفي مشروعك.
- استخدام لغة خاصة بالنطاق لإنشاء البيانات التعريفية: يتم التعبير عن ملفات الإصدار في Gradle باستخدام Groovy أو Kotlin. ومع ذلك، كلما كان التعبير عن إعدادات المشروع أكثر تعريفًا، زادت احتمالية أن يعثر "مساعد الترقية" على جميع الأماكن التي تحتاج إلى تعديل للترقية.
حتى إذا كان المشروع يتوافق مع هذه القيود، قد يتعذّر على "مساعد الترقية" إجراء ترقية سلسة. راجِع مقالة تحديد المشاكل وحلّها للحصول على إرشادات حول كيفية حلّ الأخطاء أو الإبلاغ عنها.
الاحتفاظ بنسخة احتياطية من مشروعك
قبل استخدام "مساعد الترقية"، ننصحك بالتأكّد من أنّ مشروعك لا يتضمّن أي تغييرات لم يتم حفظها، كما يظهر في نظام التحكّم في الإصدارات. إذا لم تكن تستخدم التحكم في الإصدارات، استخدِم نسخة احتياطية من آخر إصدار خالٍ من الأخطاء.
بعد تشغيل "مساعد الترقية" وإنشاء المشروع واختباره بنجاح، يمكنك إرسال الإصدار الجديد من المشروع إلى نظام التحكّم في الإصدار.
تشغيل "أداة الترقية"
لتشغيل "أداة الترقية"، اتّبِع الخطوات التالية:
لتشغيل "أداة ترقية المكوّن الإضافي لنظام Android"، انتقِل إلى الأدوات > أداة ترقية المكوّن الإضافي لنظام Android أو انقر على طلب الإشعار، كما هو موضّح في الشكل 1.
تعرض نافذة الأدوات التي تظهر تفاصيل الترقية التلقائية، بما في ذلك الإصدار الحالي من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) في المشروع وأحدث إصدار متوافق مع هذا الإصدار من "استوديو Android".
الشكل 1. نافذة أدوات مساعد ترقية AGP عند تشغيلها باستخدام طلب الإذن من الإشعار راجِع الخطوات المطلوبة والمُقترَحة.
في اللوحة اليمنى، تعرض الشجرة التي تتضمّن مربّعات الاختيار تفاصيل الخطوات الفردية في عملية الترقية، ويتم تصنيفها حسب ما إذا كانت مطلوبة أو يُنصح بتعديلها وما إذا كانت من المتطلبات الأساسية لخطوات أخرى. اختَر عناصر فردية في العرض التدرّجي لعرض المزيد من التفاصيل حول كل خطوة في اللوحة الرئيسية.
لتنفيذ عملية الترقية، اختَر الخطوات المطلوبة والمرغوب فيها، ثم انقر على تنفيذ الخطوات المحدّدة.
يغيّر "مساعِد الترقية" ملفات تصميم المشروع ويحاول مزامنة تصميم المشروع الجديد مع "استوديو Android". قد تستغرق هذه العملية بعض الوقت إذا كان لديك العديد من الوحدات، لأنّه قد يلزم تنزيل إصدارات جديدة من المكوّنات الإضافية والمكتبات.
راجِع تقرير ما بعد الترقية. يصف هذا التقرير الخطوات التي تم إكمالها وما إذا كانت عملية الترقية ناجحة أم لا. وتتضمّن أيضًا إجراءً للتراجع عن التغييرات التي أجراها مساعد الترقية في حال حدوث مشاكل في إنشاء المشروع أو اختباره بعد الترقية.
بعد مزامنة المشروع بنجاح مع "استوديو Android"، أنشئ المشروع وشغِّل حِزم الاختبار للتأكّد من أنّ عملية الترقية لم تغيّر أي وظيفة.
بعد التأكّد من أنّ مشروعك في حالة جيدة، عليك إرسال الإصدار الجديد من مشروعك إلى نظام التحكّم في الإصدار.
تحديد الأخطاء وحلّها
إذا اقترحت "أداة الترقية" إجراء ترقية ولكن تعذّر إجراؤها، يكون ذلك عادةً نتيجة إجراء تغييرات على ملفات الإصدار، ما يؤدي إلى تعذُّر المزامنة. اتّبِع الخطوات التالية للمساعدة في تحديد الخطأ وإصلاحه:
أولاً، افحص الخطأ الذي أدّى إلى تعذُّر المزامنة. في بعض الأحيان، يكون للخطأ سبب واضح يمكنك معالجته في ملفات إنشاء المشروع.
إذا كانت رسالة الخطأ غير واضحة أو لم يكن سبب المشكلة واضحًا، أعِد المشروع إلى حالته الأصلية لتقسيم عملية الترقية إلى خطوات أصغر. استعادة الحالة الأصلية من نظام التحكّم بالإصدارات أو من النُسخ الاحتياطية، والتأكّد من أنّ المشروع في حالته الأصلية وتمت مزامنته مع "استوديو Android"
يمكنك التحقيق في الخطأ باتّباع نوعَين من تفاصيل الترقية:
الترقية إلى إصدار مختلف من "مكوّن Android الإضافي لبرنامج Gradle" ليس هو الأحدث إذا كانت الترقية التي حدثت فيها مشكلة تتضمّن عددًا كبيرًا من الإصدارات، فإنّ أفضل طريقة لتحديد المشكلة هي إجراء سلسلة من الترقيات الأصغر، من إصدار إلى إصدار، للعثور على الترقية الأولى التي تؤدي إلى حدوث المشكلة.
في عملية الترقية، نفِّذ الخطوات الفردية واحدة تلو الأخرى. بعد تحديد الترقية التي تتسبّب في المشكلة، قد يكون من الممكن إيقاف الخطوات الفردية في الترقية. وإذا كان ذلك ممكنًا، جرِّب تنفيذ كل خطوة على حدة لمعرفة أي من هذه الخطوات مسؤول عن الخطأ. إذا لم تتمكّن من العثور على الخطوة المسؤولة، راجِع ملاحظات الإصدار الخاصة بأي مكوّنات إضافية أخرى من Gradle تستخدمها بحثًا عن مشاكل في التوافق مع Gradle أو AGP. في بعض الأحيان، يتناول الإصدار الجديد استخدام واجهات برمجة التطبيقات المتوقّفة نهائيًا أو الداخلية.
الإبلاغ عن خطأ في بعض الأحيان، تنجح جميع خطوات الإعداد والمزامنة، ولكن لا تزال خطوة الترقية النهائية غير ناجحة. في هذه الحالة، يُرجى الإبلاغ عن الخطأ. حتى إذا نجحت في حلّ الخطأ بنفسك، يُرجى الإبلاغ عن المشكلة الأصلية في أداة تتبُّع الأخطاء، ليتمكّن فريق التطوير من معالجة المشكلة.