دستیار ارتقاء افزونهی اندروید گریدل (AGP) ابزاری در اندروید استودیو است که به شما کمک میکند نسخه AGP مورد استفاده در پروژهتان را ارتقا دهید.
نسخههای مکرری برای تغییرات AGP مربوط به ویژگیهای جدید برای پیکربندی ساخت شما، APIهای جدید برای استفاده توسط سایر افزونههای Gradle و اصلاحاتی برای ادغام ساخت پروژه با اندروید استودیو وجود دارد. ارتقاء نسخه AGP مورد استفاده در پروژه شما به شما امکان میدهد از جدیدترین ویژگیها بهرهمند شوید.
برای اطلاعات بیشتر در مورد ساختار پروژه پیشنهادی برای دستیار ارتقا، به بخش تنظیمات در این صفحه مراجعه کنید.
موارد استفاده از دستیار ارتقاء AGP
دستیار ارتقاء AGP شما را در انجام تغییرات لازم برای ارتقاء نسخههای AGP راهنمایی میکند. موارد زیر رایجترین موارد استفاده از دستیار ارتقاء هستند:
تغییرات نحوی : دستیار ارتقا تلاش میکند فایلهای ساخت شما را برای نسخه قدیمیتر AGP به فایلهای مورد نیاز برای نسخه جدیدتر AGP ترجمه کند. همزمان با توسعه AGP، فایلهای ساخت برای پشتیبانی از رابطهایی که در طول زمان جایگزین، منسوخ یا پشتیبانی نمیشوند، بهروزرسانی میشوند.
الزامات سازگاری بین AGP و Gradle : دستیار ارتقا از الزامات سازگاری بین AGP و Gradle آگاه است و به شما کمک میکند تا مطمئن شوید که از نسخه Gradle مورد نیاز برای نسخه AGP خود استفاده میکنید.
الزامات سازگاری بین AGP و افزونههای Gradle شخص ثالث : دستیار ارتقا از الزامات سازگاری بین AGP و برخی از افزونههای Gradle شخص ثالث آگاه است و به شما کمک میکند تا مطمئن شوید که از نسخههایی از افزونههای Gradle شخص ثالث که برای نسخه AGP شما مورد نیاز است، استفاده میکنید.
به طور کلی، دستیار ارتقا، بهروزرسانی فایلهای ساخت و درک پیامهای خطای مرتبط پس از ارتقاء AGP را آسانتر میکند. دستیار ارتقا همچنین توضیح میدهد که چرا تغییرات پیشنهادی ضروری هستند.
نحوه استفاده از دستیار ارتقاء AGP
برای استفاده از Upgrade Assistant، مطمئن شوید که ساختار پروژه شما با این ابزار سازگار است و سپس آن را از اندروید استودیو، همانطور که در Run the Upgrade Assistant توضیح داده شده است، اجرا کنید.
پروژه خود را تنظیم کنید
قبل از اجرای Upgrade Assistant، مطمئن شوید که پروژه شما به درستی فرمت و پشتیبانگیری شده است. برای اطمینان از تنظیم صحیح AGP Upgrade Assistant، بخشهای زیر را مطالعه کنید.
پروژه خود را با استفاده از فایلهای ساخت Gradle و زبان خاص دامنه ساختاردهی کنید
برای استفاده بهینه از AGP Upgrade Assistant، موارد زیر را انجام دهید:
- پیکربندی ساخت با استفاده از فایلهای ساخت Gradle : دستیار ارتقا (Upgrade Assistant) بر تحلیل استاتیک فایلهای ساخت Gradle متکی است. برای بهرهمندی هرچه بیشتر از دستیار ارتقا، ساخت خود را با استفاده از این فایلهای ساخت پیکربندی کنید. از کاتالوگهای نسخه Gradle برای ارجاع به وابستگیها و افزونههای تعریفشده در فایل
libs.versions.tomlدر زیرشاخهgradleپروژه خود استفاده کنید.
- از زبان ساخت اعلانی مختص دامنه استفاده کنید : فایلهای ساخت Gradle با Groovy یا Kotlin بیان میشوند. با این حال، هرچه بیان پیکربندی پروژه اعلانیتر باشد، احتمال بیشتری وجود دارد که دستیار ارتقا با موفقیت تمام مکانهایی را که نیاز به تنظیم برای ارتقا دارند، پیدا کند.
حتی اگر یک پروژه با این محدودیتها مطابقت داشته باشد، دستیار ارتقا ممکن است همچنان در انجام یک ارتقا کامل شکست بخورد. برای راهنمایی در مورد نحوه رفع یا گزارش اشکالات، به بخش عیبیابی خطاها مراجعه کنید.
از پروژه خود نسخه پشتیبان تهیه کنید
قبل از استفاده از دستیار ارتقا، توصیه میکنیم که پروژه شما هیچ تغییر تایید نشدهای نداشته باشد، همانطور که توسط سیستم کنترل نسخه شما مشاهده میشود. اگر از کنترل نسخه استفاده نمیکنید، در این مرحله از یک نسخه پشتیبان از آخرین نسخه سالم شناخته شده استفاده کنید.
پس از اجرای دستیار ارتقا و ساخت و آزمایش موفقیتآمیز پروژه، میتوانید نسخه جدید پروژه را به سیستم کنترل نسخه خود ارسال کنید.
دستیار ارتقا را اجرا کنید
برای اجرای دستیار ارتقا، مراحل زیر را دنبال کنید:
برای اجرای دستیار ارتقا، به ابزارها > دستیار ارتقا AGP بروید یا همانطور که در شکل 1 نشان داده شده است، روی اعلان کلیک کنید.
پنجره ابزاری که ظاهر میشود، جزئیات ارتقاء پیشفرض، از جمله نسخه فعلی AGP پروژه و آخرین نسخه پشتیبانی شده توسط این نسخه از اندروید استودیو را نمایش میدهد.
شکل ۱. پنجره ابزار دستیار ارتقاء AGP هنگام راهاندازی با اعلان. مراحل مورد نیاز و توصیه شده را بررسی کنید.
در پنل سمت چپ، درختی با کادرهای انتخاب، جزئیات مراحل مختلف ارتقا را نشان میدهد که بر اساس اینکه آیا بهروزرسانی آنها الزامی است یا توصیه میشود و اینکه آیا پیشنیاز مراحل دیگر هستند، دستهبندی شدهاند. برای نمایش جزئیات بیشتر در مورد هر مرحله در پنل اصلی، موارد جداگانه را در درخت انتخاب کنید.
برای اجرای ارتقا، مراحل مورد نیاز و دلخواه را انتخاب کرده و روی اجرای مراحل انتخاب شده کلیک کنید.
دستیار ارتقا، فایلهای ساخت پروژه را تغییر میدهد و تلاش میکند تا ساخت پروژه جدید را با اندروید استودیو همگامسازی کند. اگر ماژولهای زیادی داشته باشید، این کار ممکن است کمی طول بکشد، زیرا ممکن است نیاز به دانلود نسخههای جدید افزونهها و کتابخانهها باشد.
گزارش پس از ارتقا را بررسی کنید. این گزارش مراحل انجام شده و موفقیتآمیز یا ناموفق بودن ارتقا را شرح میدهد. همچنین شامل اقدامی برای بازگرداندن تغییراتی است که توسط دستیار ارتقا ایجاد شده است، در صورتی که پس از ارتقا مشکلی در ساخت یا آزمایش پروژه وجود داشته باشد.
پس از اینکه پروژه با موفقیت با اندروید استودیو همگامسازی شد، پروژه را build کنید و مجموعههای آزمایشی را اجرا کنید تا تأیید کنید که عملیات ارتقا هیچ عملکردی را تغییر نداده است.
وقتی تأیید کردید که پروژهتان در وضعیت خوبی است، نسخه جدید پروژهتان را به سیستم کنترل نسخه خود ارسال کنید.
عیبیابی خطاها
اگر دستیار ارتقا، ارتقا را پیشنهاد میدهد اما ارتقا با شکست مواجه میشود، این معمولاً نتیجهی ایجاد تغییرات در فایلهای ساخت است که منجر به عدم هماهنگی میشود. برای کمک به شناسایی و رفع خطا، این مراحل را دنبال کنید:
ابتدا، خطایی که منجر به عدم موفقیت همگامسازی شده است را بررسی کنید. گاهی اوقات، خطا دلیل مشخصی دارد که میتوانید در فایلهای ساخت پروژه به آن بپردازید.
اگر پیام خطا واضح نیست، یا مشخص نیست چه چیزی باعث ایجاد مشکل شده است، پروژه را به حالت اولیه خود برگردانید تا ارتقا به مراحل کوچکتر تقسیم شود. حالت اولیه را از کنترل نسخه یا از پشتیبانها بازیابی کنید و مطمئن شوید که پروژه در حالت اولیه خود قرار دارد و با اندروید استودیو همگامسازی شده است.
با دنبال کردن دو نوع از مراحل ارتقاء، خطا را بررسی کنید:
به نسخه دیگری از AGP ارتقا دهید که آخرین نسخه نباشد. اگر ارتقاء ناموفق، ارتقاء تعداد زیادی از نسخهها بوده است، بهترین راه برای شناسایی مشکل، انجام مجموعهای از ارتقاءهای کوچکتر، از نسخهای به نسخه دیگر، برای یافتن اولین ارتقاءی است که باعث ایجاد مشکل شده است.
در طول یک ارتقا، مراحل را یکی یکی انجام دهید. پس از تعیین ارتقایی که باعث ایجاد مشکل شده است، ممکن است بتوانید مراحل ارتقا را غیرفعال کنید. در صورت امکان، سعی کنید هر مرحله را یکی یکی انجام دهید تا متوجه شوید کدام یک از آن مراحل مسئول خطا است. اگر نمیتوانید مرحله مسئول را پیدا کنید، یادداشتهای انتشار سایر افزونههای Gradle که استفاده میکنید را برای مشکلات سازگاری با Gradle یا AGP بررسی کنید. گاهی اوقات، یک نسخه جدید به استفاده از APIهای منسوخ یا داخلی میپردازد.
گزارش اشکال . گاهی اوقات تمام مراحل آمادهسازی و همگامسازی با موفقیت انجام میشود اما مرحله نهایی ارتقا همچنان با شکست مواجه میشود. در این صورت، لطفاً یک اشکال را گزارش دهید. حتی اگر خودتان در رفع خطا موفق شدید، مشکل اصلی را به ردیاب اشکال گزارش دهید تا مشکل توسط تیم توسعه برطرف شود.