استفاده از «دستیار ارتقا» افزایه Android Gradle

«دستیار ارتقای» افزایه Android Gradle (AGP) ابزاری در Android Studio است که به شما کمک می‌کند نسخه AGP مورداستفاده در پروژه‌تان را ارتقا دهید.

android skills add agp-9-upgrade

نسخه‌های متعددی برای تغییرات AGP مربوط به ویژگی‌های جدید برای پیکربندی ساخت شما، میاناهای برنامه‌سازی کاربردی جدید برای استفاده توسط سایر افزایه‌های Gradle، و اصلاحات در ادغام ساخت پروژه با «استودیو Android» منتشر می‌شود. ارتقا دادن نسخه AGP مورداستفاده پروژه‌تان به شما امکان می‌دهد از جدیدترین ویژگی‌ها بهره‌مند شوید.

برای کسب اطلاعات بیشتر درباره ساختار پروژه توصیه‌شده برای «دستیار ارتقا»، به راه‌اندازی در این صفحه مراجعه کنید.

موارد استفاده «دستیار ارتقای AGP»

«دستیار ارتقای AGP» شما را در تغییرات لازم برای ارتقای نسخه‌های AGP راهنمایی می‌کند. رایج‌ترین موارد استفاده از «دستیار ارتقا» در زیر آمده است:

• تغییرات نحو: «دستیار ارتقا» تلاش می‌کند فایل‌های ساخت شما را برای نسخه قدیمی‌تر AGP به فایل‌های موردنیاز برای نسخه جدیدتر AGP ترجمه کند. با توسعه AGP، فایل‌های ساخت به‌روز می‌شوند تا از میاناهای جدید پشتیبانی کنند، زیرا میاناهای قدیمی به‌مرور زمان جایگزین، منسوخ، یا غیرقابل‌پشتیبانی می‌شوند.

• الزامات سازگاری بین AGP و Gradle: «دستیار ارتقا» از الزامات سازگاری بین AGP و Gradle مطلع است و کمک می‌کند مطمئن شوید از نسخه Gradle موردنیاز برای نسخه AGP خود استفاده می‌کنید.

• الزامات سازگاری بین AGP و افزایه‌های Gradle شخص ثالث: «دستیار ارتقا» از الزامات سازگاری بین AGP و برخی‌از افزایه‌های Gradle شخص ثالث مطلع است و کمک می‌کند مطمئن شوید از نسخه‌هایی از افزایه‌های Gradle شخص ثالث استفاده می‌کنید که برای نسخه AGP شما لازم است.

به‌طور کلی، «دستیار ارتقا» به‌روزرسانی فایل‌های ساخت و درک پیام‌های خطای مربوطه را پس‌از ارتقای AGP آسان‌تر می‌کند. «دستیار ارتقا» همچنین توضیح می‌دهد که چرا تغییرات پیشنهادی ضروری هستند.

نحوه استفاده از «دستیار ارتقای AGP»

برای استفاده از «دستیار ارتقا»، مطمئن شوید ساختار پروژه‌تان با این ابزار سازگار است، سپس آن را از Android Studio اجرا کنید، همان‌طور که در اجرای «دستیار ارتقا» شرح داده شده است.

راه‌اندازی پروژه

قبل‌از اجرای «دستیار ارتقا»، مطمئن شوید پروژه‌تان به‌درستی قالب‌بندی و پشتیبان‌گیری شده باشد. برای اطمینان از اینکه «دستیار ارتقای AGP» به‌درستی راه‌اندازی شده است، بخش‌های زیر را بخوانید.

پروژه‌تان را بااستفاده از فایل‌های ساخت Gradle و زبان مختص دامنه ساختاردهی کنید

برای استفاده بهینه از «دستیار ارتقای AGP»، کارهای زیر را انجام دهید:

• پیکربندی ساخت بااستفاده از فایل‌های ساخت Gradle: «دستیار ارتقا» به تحلیل آماری فایل‌های ساخت Gradle متکی است. برای بهره‌مندی حداکثری از «دستیار ارتقا»، ساخت خود را بااستفاده از این فایل‌های ساخت پیکربندی کنید. از کاتالوگ‌های نسخه Gradle برای ارجاع به وابستگی‌ها و افزایه‌های تعریف‌شده در فایل libs.versions.toml در زیرفهرست راهنمای gradle پروژه‌تان استفاده کنید.

• از زبان ساخت اعلانی مختص دامنه استفاده کنید: فایل‌های ساخت Gradle به زبان Groovy یا Kotlin بیان می‌شوند. بااین‌حال، هرچه بیان پیکربندی پروژه اعلانی‌تر باشد، احتمال اینکه «دستیار ارتقا» همه جاهایی را که برای ارتقا نیاز به اصلاح دارند با موفقیت پیدا کند بیشتر است.

حتی اگر پروژه‌ای با این محدودیت‌ها مطابقت داشته باشد، «دستیار ارتقا» ممکن است همچنان نتواند ارتقای تمیزی انجام دهد. برای راهنمایی درباره نحوه حل یا گزارش کردن اشکالات، عیب‌یابی خطاها را ببینید.

پشتیبان‌گیری از پروژه

قبل‌از استفاده از «دستیار ارتقا»، توصیه می‌کنیم پروژه‌تان تغییرات تأییدنشده نداشته باشد، همان‌طور که در سیستم کنترل نسخه شما دیده می‌شود. اگر از کنترل نسخه استفاده نمی‌کنید، در این مرحله از نسخه پشتیبان آخرین نسخه خوب شناخته‌شده استفاده کنید.

پس‌از اجرای «دستیار ارتقا» و ساخت و آزمایش موفقیت‌آمیز پروژه، می‌توانید نسخه جدید پروژه را به سیستم کنترل نسخه خود ارسال کنید.

اجرای «دستیار ارتقا»

برای اجرای «دستیار ارتقا»، این مراحل را دنبال کنید:

1. برای راه‌اندازی «دستیار ارتقا»، به ابزارها > دستیار ارتقای AGP بروید یا روی پیام‌واره اعلان کلیک کنید، همان‌طور که در شکل ۱ نشان داده شده است.

   پنجره ابزاری که ظاهر می‌شود جزئیات ارتقای پیش‌فرض را نمایش می‌دهد، ازجمله نسخه فعلی AGP پروژه و جدیدترین نسخه پشتیبانی‌شده توسط این نسخه Android Studio.

   

2. مراحل الزامی و توصیه‌شده را بررسی کنید.

   در پانل سمت راست، درخت با کادرهای انتخاب جزئیات مراحل فردی در ارتقا را نشان می‌دهد، که براساس اینکه آیا برای به‌روزرسانی لازم یا توصیه شده‌اند و اینکه آیا پیش‌نیازهای مراحل دیگر هستند یا نه، دسته‌بندی شده‌اند. موارد تکی را در درخت انتخاب کنید تا جزئیات بیشتری درباره هر مرحله در پانل اصلی نمایش داده شود.

3. برای اجرای ارتقا، مراحل لازم و موردنظر را انتخاب کنید و روی اجرای مراحل انتخاب‌شده کلیک کنید.

   «دستیار ارتقا» فایل‌های ساخت پروژه را تغییر می‌دهد و تلاش می‌کند ساخت پروژه جدید را با «استودیو Android» همگام‌سازی کند. اگر ماژول‌های متعددی داشته باشید، ممکن است این کار مدتی طول بکشد، زیرا ممکن است لازم باشد نسخه‌های جدید افزایه‌ها و کتابخانه‌ها بارگیری شوند.

4. گزارش پس‌از ارتقا را مرور کنید. این گزارش مراحلی را که تکمیل شده‌اند و اینکه ارتقا موفقیت‌آمیز بوده است یا نه شرح می‌دهد. همچنین شامل کنش‌هایی برای برگرداندن تغییراتی است که توسط دستیار ارتقا ایجاد شده‌اند، درصورتی‌که مشکلاتی در ساخت یا آزمایش پروژه پس‌از ارتقا وجود داشته باشد.

5. وقتی پروژه باموفقیت با Android Studio همگام‌سازی شد، پروژه را بسازید و مجموعه آزمون‌ها را اجرا کنید تا تأیید کنید که عملیات ارتقا هیچ عملکردی را تغییر نداده است.

6. وقتی مطمئن شدید که پروژه‌تان در وضعیت خوبی قرار دارد، نسخه جدید پروژه‌تان را به سیستم کنترل نسخه خود ارسال کنید.

عیب‌یابی خطاها

اگر «دستیار ارتقا» ارتقایی را پیشنهاد دهد اما ارتقا ناموفق باشد، معمولاً نتیجه ایجاد تغییرات در فایل‌های ساخت است که منجر به ناموفق بودن همگام‌سازی می‌شود. برای کمک به جداسازی و رفع خطا، این مراحل را دنبال کنید:

• ابتدا خطایی را که منجر به ناموفق بودن همگام‌سازی شده است بررسی کنید. گاهی اوقات، خطا علت مشخصی دارد که می‌توانید آن را در فایل‌های ساخت پروژه برطرف کنید.

• اگر پیام خطا واضح نیست یا مشخص نیست چه چیزی باعث بروز مشکل شده است، پروژه را به حالت اصلی‌اش برگردانید تا ارتقا را به مراحل کوچک‌تری تقسیم کنید. وضعیت اصلی را از کنترل نسخه یا از نسخه‌های پشتیبان بازیابی کنید و مطمئن شوید پروژه در وضعیت اصلی خود قرار دارد و با Android Studio همگام‌سازی شده است.

با دنبال کردن دو نوع خرابی ارتقا، خطا را بررسی کنید:

• به نسخه دیگری از AGP که جدیدترین نسخه نیست ارتقا دهید. اگر ارتقایی که با مشکل مواجه شده است ارتقای تعداد زیادی نسخه باشد، بهترین راه برای جداسازی مشکل این است که مجموعه‌ای از ارتقاهای کوچک‌تر را نسخه به نسخه انجام دهید تا اولین ارتقایی را که باعث بروز مشکل می‌شود پیدا کنید.

• در ارتقا، مراحل را یکی‌یکی انجام دهید. وقتی مشخص کردید کدام ارتقا باعث بروز مشکل شده است، شاید بتوانید مراحل ارتقا را به‌صورت جداگانه خاموش کنید. اگر امکان‌پذیر است، هر مرحله را به‌صورت جداگانه انجام دهید تا ببینید کدام مرحله باعث بروز خطا می‌شود. اگر نمی‌توانید مرحله مسئول را پیدا کنید، یادداشت‌های انتشار هر افزایه Gradle دیگری را که استفاده می‌کنید برای مشکلات سازگاری با Gradle یا AGP بررسی کنید. گاهی اوقات، نسخه جدید به استفاده از میاناهای برنامه‌سازی کاربردی منسوخ‌شده یا داخلی می‌پردازد.

• گزارش کردن اشکال. گاهی اوقات همه مراحل آماده‌سازی و همگام‌سازی با موفقیت انجام می‌شود اما مرحله نهایی ارتقا همچنان ناموفق است. در این صورت، لطفاً اشکال را گزارش کنید. حتی اگر خودتان موفق به رفع خطا شدید، خرابی اصلی را به ردیاب اشکال گزارش دهید تا تیم توسعه بتواند به مشکل رسیدگی کند.