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

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

نسخه‌های متعددی برای تغییرات 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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