Android Gradle eklentisi Yükseltme Asistanı'nı kullanma

Android Gradle eklentisi (AGP) Yükseltme Asistanı, projenizde kullanılan AGP sürümünü yükseltmenize yardımcı olan bir Android Studio aracıdır.

Derlemenizi yapılandırmaya yönelik yeni özelliklere, diğer Gradle eklentileri tarafından kullanılacak yeni API'lere ve proje derlemesinin Android Studio ile entegrasyonuna yönelik iyileştirmelerle ilgili olarak sık sık AGP değişiklikleri yayınları yapılır. Projenizde kullanılan AGP sürümünü yükseltmek, en yeni özelliklerden yararlanmanızı sağlar.

Yükseltme Asistanı için önerilen proje yapısı hakkında daha fazla bilgiyi bu sayfadaki Kurulum bölümünde bulabilirsiniz.

AGP Yükseltme Asistanı kullanım alanları

AGP Yükseltme Asistanı, AGP sürümlerini yükseltmek için gereken değişikliklerde size yol gösterir. Aşağıda, Yükseltme Asistanı'nın en yaygın kullanım alanları verilmiştir:

• Söz dizimi değişiklikleri: Yükseltme Asistanı, eski bir AGP sürümüne ait derleme dosyalarınızı, daha yeni bir AGP sürümü için gerekenlere çevirmeye çalışır. AGP geliştirildikçe derleme dosyaları, değiştirilen, kullanımdan kaldırılan veya zaman içinde desteklenmeyen arayüzleri destekleyecek şekilde güncellenir.

• AGP ve Gradle arasındaki uyumluluk gereksinimleri: Yükseltme Asistanı, AGP ile Gradle arasındaki uyumluluk gereksinimlerinin farkındadır ve AGP sürümünüz için gereken Gradle sürümünü kullandığınızdan emin olmanıza yardımcı olur.

• AGP ve üçüncü taraf Gradle eklentileri arasındaki uyumluluk gereksinimleri: Yükseltme Asistanı, AGP ile bazı üçüncü taraf Gradle eklentileri arasındaki uyumluluk gereksinimlerinin farkındadır ve AGP sürümünüz için gerekli olan üçüncü taraf Gradle eklentilerinin sürümlerini kullandığınızdan emin olmanıza yardımcı olur.

Genel olarak, Yükseltme Asistanı, AGP yükseltmesinden sonra derleme dosyalarını güncellemeyi ve ilgili hata mesajlarını anlamayı kolaylaştırır. Yükseltme Asistanı, önerilen değişikliklerin neden gerekli olduğunu da açıklar.

AGP Yükseltme Asistanı nasıl kullanılır?

Yükseltme Asistanı'nı kullanmak için proje yapınızın araca uygun olduğundan emin olun ve ardından, Yükseltme Asistanı'nı çalıştırma bölümünde açıklandığı gibi, aracı Android Studio'dan çalıştırın.

Projenizi oluşturun

Yükseltme Asistanı'nı çalıştırmadan önce projenizin doğru şekilde biçimlendirildiğinden ve yedeklendiğinden emin olun. AGP Yükseltme Asistanı'nın doğru ayarlandığından emin olmak için aşağıdaki bölümleri okuyun.

Gradle derleme dosyalarını ve alana özgü dili kullanarak projenizi yapılandırın

AGP Yükseltme Asistanından en iyi şekilde yararlanmak için aşağıdakileri yapın:

• Derlemeyi Gradle derleme dosyalarını kullanarak yapılandırın: Yükseltme Asistanı, Gradle derleme dosyalarının statik analizinden yararlanır. Yükseltme Asistanı'ndan en iyi şekilde yararlanmak için bu derleme dosyalarını kullanarak derlemenizi yapılandırın.

• Bildirim temelli derleme alanına özgü dili kullanın: Gradle derleme dosyaları Groovy veya Kotlin'de ifade edilir. Bununla birlikte, proje yapılandırmasının ifadesi ne kadar beyancı olursa Yükseltme Asistanı'nın yükseltme için ayarlanması gereken tüm yerleri başarıyla bulma olasılığı da o kadar yüksek olur.

Proje bu sınırlamalara uysa bile Yükseltme Asistanı temiz bir yükseltme gerçekleştiremeyebilir. Hataların nasıl çözüleceği veya bildirileceği konusunda yol gösterici bilgiler için Hataları giderme bölümüne bakın.

Projenizi yedekleyin

Yükseltme Asistanı'nı kullanmadan önce, sürüm kontrol sisteminiz tarafından görüldüğü gibi projenizde kaydedilmemiş değişiklik olmamasını öneririz. Sürüm kontrolünü kullanmıyorsanız bu noktada bilinen son iyi sürümün yedeğini kullanın.

Yükseltme Asistanı çalıştırıldıktan ve proje başarıyla derlenip test edildikten sonra projenin yeni sürümünü sürüm kontrol sisteminize kaydedebilirsiniz.

Yükseltme Asistanı'nı çalıştırın

Yükseltme Asistanı'nı çalıştırmak için aşağıdaki adımları uygulayın:

1. Yükseltme Asistanı'nı başlatmak için Araçlar > AGP Yükseltme Asistanı'na gidin veya Şekil 1'de gösterildiği gibi bildirim istemini tıklayın.

   Açılan araç penceresinde projenin geçerli AGP sürümü ve Android Studio'nun bu sürümü tarafından desteklenen en son sürüm de dahil olmak üzere varsayılan yükseltme işleminin ayrıntıları görüntülenir.

   

2. Zorunlu ve önerilen adımlara göz atın.

   Sol taraftaki panelde, onay kutuları bulunan ağaçta, yükseltmedeki her bir adım, güncellemenin gerekli olup olmadığına veya önerilip önerilmediğine ve diğer adımların ön koşulları olup olmadığına göre kategorilere ayrılır. Ana paneldeki her adımla ilgili daha fazla ayrıntı görüntülemek için ağaçta öğeleri tek tek seçin.

3. Yükseltmeyi çalıştırmak için gerekli ve istenen adımları seçip Seçilen adımları çalıştır'ı tıklayın.

   Yükseltme Asistanı, proje derleme dosyalarını değiştirir ve yeni proje derlemesini Android Studio ile senkronize etmeye çalışır. Çok sayıda modülünüz varsa eklentilerin ve kitaplıkların yeni sürümlerinin indirilmesi gerekebileceğinden bu işlem biraz zaman alabilir.

4. Yükseltme sonrası raporu inceleyin. Bu raporda, tamamlanan adımlar ve yükseltmenin başarılı mı yoksa başarısız mı olduğu açıklanmaktadır. Ayrıca, yükseltme sonrasında projeyi oluştururken veya test ederken sorunlar yaşanırsa yükseltme asistanı tarafından yapılan değişiklikleri geri almak için bir işlem de içerir.

5. Proje, Android Studio ile başarıyla senkronize edildikten sonra projeyi derleyip test paketlerini çalıştırarak yükseltme işleminin hiçbir işlevi değiştirmediğini doğrulayın.

6. Projenizin iyi durumda olduğunu doğruladıktan sonra projenizin yeni sürümünü sürüm kontrol sisteminize kaydedin.

Hataları giderme

Yükseltme Asistanı yükseltmeyi önerirse ancak yükseltme başarısız olursa bunun nedeni genellikle derleme dosyalarında değişiklik yapılmasıdır ve senkronizasyon hatasına neden olur. Hatanın tespit edilip düzeltilmesine yardımcı olması için aşağıdaki adımları uygulayın:

• Öncelikle senkronizasyon hatasına neden olan hatayı inceleyin. Bazen hatanın açık bir nedeni vardır. Bu nedeni projenin derleme dosyalarında giderebilirsiniz.

• Hata mesajı net değilse veya soruna neyin neden olduğu belli değilse yükseltme işlemini daha küçük adımlara bölmek için projeyi ilk haline döndürün. Sürüm kontrolünden veya yedeklerden orijinal durumu geri yükleyin ve projenin orijinal durumunda olduğundan ve Android Studio ile senkronize edildiğinden emin olun.

İki tür yükseltme dökümünü izleyerek hatayı araştırın:

• AGP'nin en son sürüm olmayan farklı bir sürümüne geçin. Hataya neden olan yükseltme işlemi çok sayıda sürümün yükseltilmesiyse sorunu çözmenin en iyi yolu, sürümden sürüme daha küçük yükseltmeler yaparak sorunu tetikleyen ilk yükseltmeyi bulmaktır.

• Yükseltme sırasında bireysel adımları tek tek uygulayın. Sorunu tetikleyen yükseltmeyi belirledikten sonra, yükseltme sırasındaki adımları tek tek devre dışı bırakabilirsiniz. Mümkünse hatadan sorumlu adımları bulmak için her adımı teker teker uygulamayı deneyin. Sorumlu adımı bulamıyorsanız, kullandığınız diğer Gradle eklentilerinin Gradle veya AGP ile uyumluluk sorunları için sürüm notlarını kontrol edin. Bazen yeni bir sürüm, kullanımdan kaldırılmış veya dahili API'lerin kullanımını ele alır.

• Hata bildirin. Bazen tüm hazırlık adımları ve senkronizasyon başarılı olsa da son yükseltme adımı başarısız olur. Bu durumda lütfen hata bildiriminde bulunun. Hatayı kendiniz düzeltmeyi başarsanız bile, geliştirme ekibinin bu sorunu ele alabilmesi için orijinal hatayı hata izleyiciye bildirin.