Android API düzeylerini anlama

Xamarin.Android, uygulamanızın birden çok Android sürümüyle uyumluluğunu belirleyen çeşitli Android API düzeyi ayarlarına sahiptir. Bu kılavuzda bu ayarların ne anlama geldiğinden, nasıl yapılandırıldığından ve çalışma zamanında uygulamanız üzerindeki etkisi açıklanmaktadır.

Hızlı başlangıç

Xamarin.Android üç Android API düzeyinde proje ayarı sunar:

• Hedef Çerçeve – Uygulamanızı oluştururken hangi çerçevenin kullanılacağını belirtir. Bu API düzeyi, Xamarin.Android tarafından derleme zamanında kullanılır.

• En Düşük Android Sürümü – Uygulamanızın desteklemesini istediğiniz en eski Android sürümünü belirtir. Bu API düzeyi, Android tarafından çalışma zamanında kullanılır.

• Hedef Android Sürümü – Uygulamanızın üzerinde çalıştırılması amaçlanan Android sürümünü belirtir. Bu API düzeyi, Android tarafından çalışma zamanında kullanılır.

Projeniz için bir API düzeyi yapılandırabilmeniz için önce bu API düzeyi için SDK platformu bileşenlerini yüklemeniz gerekir. Android SDK bileşenlerini indirme ve yükleme hakkında daha fazla bilgi için bkz . Android SDK Kurulumu.

Uygulamanız birden çok Android sürümünü destekliyorsa, uygulamanızın En Düşük Android sürüm ayarıyla çalıştığından emin olmak için kodunuzun çalışma zamanı denetimleri içermesi gerekir (ayrıntılar için aşağıdaki Android Sürümleri için Çalışma Zamanı Denetimleri bölümüne bakın). Kitaplık kullanıyor veya oluşturuyorsanız, kitaplıklar için API düzeyi ayarlarını yapılandırmaya yönelik en iyi yöntemler için aşağıdaki API Düzeyleri ve Kitaplıklar bölümüne bakın.

Android sürümleri ve API düzeyleri

Android platformu geliştikçe ve yeni Android sürümleri yayımlandıkçe, her Android sürümüne API Düzeyi adı verilen benzersiz bir tamsayı tanımlayıcısı atanır. Bu nedenle, her Android sürümü tek bir Android API Düzeyine karşılık gelir. Kullanıcılar hem eski hem de Android'in en son sürümlerine uygulama yüklediğinden, gerçek dünyadaki Android uygulamaları birden çok Android API düzeyiyle çalışacak şekilde tasarlanmalıdır.

Android sürümleri

Android'in her sürümü birden çok adla gösterilir:

• Android 9.0 gibi Android sürümü
• Pasta gibi bir kod (veya tatlı) adı
• Api düzeyi 28 gibi ilgili BIR API düzeyi

Android kod adı birden çok sürüme ve API düzeyine karşılık gelebilir (aşağıdaki tabloda görüldüğü gibi), ancak her Android sürümü tam olarak bir API düzeyine karşılık gelir.

Ayrıca Xamarin.Android, şu anda bilinen Android API düzeylerine eşleyen derleme sürümü kodlarını tanımlar. Aşağıdaki tablo API düzeyi, Android sürümü, kod adı ve Xamarin.Android derleme sürümü kodu (derleme sürümü kodları ad alanında Android.OS tanımlanır) arasında çeviri yapmaya yardımcı olabilir:

Bu tabloda da belirtildiği gibi, yeni Android sürümleri sık sık yayınlanmaktadır ve bazen yılda birden fazla sürüm yayınlanmaktadır. Sonuç olarak, uygulamanızı çalıştırabilecek Android cihazların evreni çok çeşitli eski ve daha yeni Android sürümleri içerir. Uygulamanızın Android'in bu kadar farklı sürümünde tutarlı ve güvenilir bir şekilde çalışacağını nasıl garanti edebilirsiniz? Android'in API düzeyleri bu sorunu yönetmenize yardımcı olabilir.

Android API düzeyleri

Her Android cihazı tam olarak bir API düzeyinde çalışır. Bu API düzeyinin Android platform sürümü başına benzersiz olacağı garanti edilir. API düzeyi, uygulamanızın çağırabileceği API kümesinin sürümünü tam olarak tanımlar; geliştirici olarak kodladığınız bildirim öğelerinin, izinlerin vb. birleşimini tanımlar. Android'in API düzeyleri sistemi, Android'in uygulamayı bir cihaza yüklemeden önce bir uygulamanın Android sistem görüntüsüyle uyumlu olup olmadığını belirlemesine yardımcı olur.

Bir uygulama oluşturulduğunda aşağıdaki API düzeyi bilgilerini içerir:

• Uygulamanın üzerinde çalıştırılacak şekilde derlenmiş hedef Android API düzeyi.

• Bir Android cihazının uygulamanızı çalıştırmak için sahip olması gereken en düşük Android API düzeyi.

Bu ayarlar, uygulamayı doğru çalıştırmak için gereken işlevselliğin yükleme zamanında Android cihazında kullanılabilir olmasını sağlamak için kullanılır. Aksi takdirde uygulamanın bu cihazda çalışması engellenir. Örneğin, bir Android cihazının API düzeyi uygulamanız için belirttiğiniz en düşük API düzeyinden düşükse, Android cihazı kullanıcının uygulamanızı yüklemesini engeller.

Proje API düzeyi ayarları

Aşağıdaki bölümlerde, geliştirme ortamınızı hedeflemek istediğiniz API düzeylerine hazırlamak için SDK Yöneticisi'nin nasıl kullanılacağı açıklanır ve ardından Xamarin.Android'de Hedef Çerçeve, En Düşük Android sürümü ve Hedef Android sürümü ayarlarını yapılandırma hakkında ayrıntılı açıklamalar yer alır.

Android SDK platformları

Xamarin.Android'de Hedef veya En Düşük API düzeyini seçebilmeniz için önce bu API düzeyine karşılık gelen Android SDK platform sürümünü yüklemeniz gerekir. Hedef Çerçeve, En Düşük Android sürümü ve Hedef Android sürümü için kullanılabilen seçenekler, yüklediğiniz Android SDK sürümleri aralığıyla sınırlıdır. Gerekli Android SDK sürümlerinin yüklendiğini doğrulamak için SDK Yöneticisi'ni kullanabilir ve uygulamanız için ihtiyacınız olan tüm yeni API düzeylerini eklemek için bunu kullanabilirsiniz. API düzeylerini yükleme hakkında bilginiz yoksa bkz . Android SDK Kurulumu.

Hedef Çerçeve

Hedef Çerçeve (olarak compileSdkVersionda bilinir), uygulamanızın derleme zamanında derlenmiş olduğu belirli Android çerçevesi sürümüdür (API düzeyi). Bu ayar, uygulamanızın çalıştırıldığında hangi API'leri kullanmasını beklediğini belirtir, ancak yüklendiğinde uygulamanız için hangi API'lerin gerçekten kullanılabilir olduğu üzerinde hiçbir etkisi yoktur. Sonuç olarak, Hedef Çerçeve ayarının değiştirilmesi çalışma zamanı davranışını değiştirmez.

Hedef Çerçeve, uygulamanızın hangi kitaplık sürümlerine bağlandığını belirler; bu ayar, uygulamanızda hangi API'leri kullanabileceğinizi belirler. Örneğin, Android 5.0 Lollipop'ta kullanıma sunulan NotificationBuilder.SetCategory yöntemini kullanmak istiyorsanız, Hedef Çerçeve'yi API Düzeyi 21 (Lollipop) veya üzeri olarak ayarlamanız gerekir. Projenizin Hedef Çerçevesini API Düzeyi 19 (KitKat) gibi bir API düzeyine ayarlar ve kodunuzda yöntemini çağırmaya SetCategory çalışırsanız, derleme hatası alırsınız.

Her zaman en son kullanılabilir Target Framework sürümüyle derlemenizi öneririz. Bunu yapmak, kodunuz tarafından çağrılabilecek kullanım dışı API'ler için size yararlı uyarı iletileri sağlar. En son Destek Kitaplığı sürümlerini kullandığınızda en son Target Framework sürümünün kullanılması özellikle önemlidir. Her kitaplık uygulamanızın bu destek kitaplığının en düşük API düzeyinde veya daha yüksek bir düzeyde derlenmiş olmasını bekler.

En Düşük Android Sürümü

En Düşük Android sürümü (olarak minSdkVersionda bilinir), Android işletim sisteminin uygulamanızı yükleyip çalıştırabilen en eski sürümüdür (en düşük API düzeyi). Varsayılan olarak, bir uygulama yalnızca Hedef Çerçeve ayarı veya üzeri ile eşleşen cihazlara yüklenebilir; En düşük Android sürüm ayarı Hedef Çerçeve ayarından düşükse , uygulamanız Android'in önceki sürümlerinde de çalıştırılabilir. Örneğin, Hedef Çerçeve'yi Android 7.1 (Nougat) olarak ve En Düşük Android sürümünü Android 4.0.3 (Ice Cream Sandwich) olarak ayarlarsanız, uygulamanız API düzeyi 15'ten API düzeyi 25'e (dahil) herhangi bir platforma yüklenebilir.

Uygulamanız bu platform aralığında başarıyla derlenip yüklense de, bu, tüm bu platformlarda başarıyla çalışacağını garanti etmez. Örneğin, uygulamanız Android 5.0'da (Lollipop) yüklüyse ve kodunuz yalnızca Android 7.1 (Nougat) ve daha yeni sürümlerde kullanılabilen bir API çağırırsa, uygulamanız çalışma zamanı hatası alır ve büyük olasılıkla kilitlenir. Bu nedenle kodunuzun çalışma zamanında yalnızca üzerinde çalıştığı Android cihazı tarafından desteklenen API'leri çağırmasını sağlaması gerekir. Başka bir deyişle, uygulamanızın yalnızca bunları destekleyecek kadar yeni olan cihazlarda daha yeni API'ler kullandığına emin olmak için kodunuzun açık çalışma zamanı denetimleri içermesi gerekir. Bu kılavuzun devamında yer alan Android Sürümleri için Çalışma Zamanı Denetimleri, bu çalışma zamanı denetimlerinin kodunuza nasıl ekleneceğini açıklar.

Hedef Android Sürümü

Hedef Android Sürümü (olarak targetSdkVersionda bilinir), uygulamanın çalışmasını beklediği Android cihazının API düzeyidir. Android herhangi bir uyumluluk davranışının etkinleştirilip etkinleştirilmeyeceğini belirlemek için bu ayarı kullanır; bu, uygulamanızın beklediğiniz şekilde çalışmaya devam etmesini sağlar. Android, uygulamanızı bozmadan uygulamanıza hangi davranış değişikliklerinin uygulanabileceğini bulmak için uygulamanızın Hedef Android sürüm ayarını kullanır (Android, ileriye dönük uyumluluk sağlar).

Hedef Çerçeve ve Hedef Android sürümü, çok benzer adlara sahip olsa da aynı şey değildir. Hedef Çerçeve ayarı, derleme zamanında kullanılmak üzere hedef API düzeyi bilgilerini Xamarin.Android'e iletirken Hedef Android sürümü, hedef API düzeyi bilgilerini çalışma zamanında kullanılmak üzere Android'e iletir (uygulama bir cihazda yüklendiğinde ve çalıştığında).

Genel olarak, Hedef Android Sürümü En Düşük Android Sürümü ve Hedef Çerçeve ile sınırlanmalıdır. Bunun anlamı:

En Düşük Android Sürümü <= Hedef Android Sürümü <= Hedef Çerçeve

SDK düzeyleri hakkında daha fazla bilgi için Android Developer uses-sdk belgelerine bakın.

Android sürümleri için çalışma zamanı denetimleri

Android'in her yeni sürümü yayımlandıkçe çerçeve API'si yeni veya değiştirme işlevselliği sağlayacak şekilde güncelleştirilir. Birkaç istisna dışında, önceki Android sürümlerindeki API işlevselliği, değişiklik yapılmadan daha yeni Android sürümlerine taşınır. Sonuç olarak, uygulamanız belirli bir Android API düzeyinde çalışıyorsa, genellikle daha sonraki bir Android API düzeyinde değişiklik yapmadan çalıştırılabilir. Peki uygulamanızı Android'in önceki sürümlerinde de çalıştırmak istiyorsanız ne olacak?

Hedef Çerçeve ayarınızdan daha düşük bir En Düşük Android sürümü seçerseniz bazı API'ler çalışma zamanında uygulamanız tarafından kullanılamayabilir. Ancak, uygulamanız daha önceki bir cihazda çalışmaya devam edebilir, ancak işlevselliği azaltılabilir. En Düşük Android sürüm ayarınıza karşılık gelen Android platformlarında bulunmayan her API için kodunuzun, uygulamanın üzerinde çalıştığı platformun Android.OS.Build.VERSION.SdkInt API düzeyini belirlemek için özelliğin değerini açıkça denetlemesi gerekir. API düzeyi , çağırmak istediğiniz API'yi destekleyen En Düşük Android sürümünden düşükse kodunuzun bu API çağrısını yapmadan düzgün çalışması için bir yol bulması gerekir.

Örneğin, Android 5.0 Lollipop 'ta (ve üzeri) çalışırken bir bildirimi kategorilere ayırmak için NotificationBuilder.SetCategory yöntemini kullanmak istediğimizi, ancak yine de uygulamamızın Android 4.1 Jelly Bean gibi Android'in önceki sürümlerinde çalışmasını istediğimizi varsayalım (burada SetCategory kullanılamaz). Bu kılavuzun başındaki Android sürüm tablosuna bakarak, Android 5.0 Lollipop için derleme sürümü kodunun olduğunu Android.OS.BuildVersionCodes.Lollipopgörüyoruz. Android'in kullanılamayan SetCategory eski sürümlerini desteklemek için kodumuz çalışma zamanında API düzeyini algılayabilir ve yalnızca API düzeyi Lollipop derleme sürümü kodundan büyük veya buna eşit olduğunda koşullu olarak çağrı SetCategory yapabilir:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

Bu örnekte, uygulamamızın Hedef Çerçevesi Android 5.0 (API Düzeyi 21) olarak, En Düşük Android sürümü ise Android 4.1 (API Düzeyi 16) olarak ayarlanmıştır. SetCategory API düzeyinde Android.OS.BuildVersionCodes.Lollipop ve sonraki sürümlerde kullanılabildiğinden, bu örnek kod yalnızca gerçekten kullanılabilir olduğunda çağırırSetCategory; API düzeyi 16, 17, 18, 19 veya 20 olduğunda çağırmaya SetCategory çalışmaz. İşlev, bu önceki Android sürümlerinde yalnızca bildirimlerin düzgün sıralanmadığı (türe göre kategorilere ayrılmadığı için) azaltılır, ancak bildirim yine de kullanıcıyı uyarmak için yayımlanır. Uygulamamız hala çalışıyor, ancak işlevselliği biraz azaldı.

Genel olarak derleme sürümü denetimi, kodunuzun çalışma zamanında yeni ve eski yöntemle bir şeyler yapma arasında karar vermesine yardımcı olur. Örneğin:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

Bir veya daha fazla API'ye sahip olmayan eski Android sürümlerinde çalışırken uygulamanızın işlevselliğini azaltmayı veya değiştirmeyi açıklayan hızlı ve basit bir kural yoktur. Bazı durumlarda (yukarıdaki örnekte olduğu gibi SetCategory ) kullanılabilir olmadığında API çağrısını atlamak yeterlidir. Ancak, diğer durumlarda, uygulamanızın en iyi deneyimini sunması için gereken API düzeyinden daha az olduğu algılandığında Android.OS.Build.VERSION.SdkInt alternatif işlevler uygulamanız gerekebilir.

API düzeyleri ve kitaplıkları

Sonuçta elde edilen kitaplık tek başına bir uygulama olmadığından En Düşük Android sürümü ve Hedef Android sürüm ayarları kullanılamaz. Kitaplık, paketlenmiş olduğu uygulamaya bağlı olarak herhangi bir Android sürümünde çalıştırılabilir. Kitaplığın nasıl derleneceğini belirtebilirsiniz, ancak kitaplığın hangi platform API düzeyinde çalıştırılacağını tahmin edebilirsiniz. Bunu göz önünde bulundurarak, kitaplıkları kullanırken veya oluştururken aşağıdaki en iyi yöntemler gözlenmelidir:

• Android kitaplığını kullanırken – Uygulamanızda bir Android kitaplığı kullanıyorsanız, uygulamanızın Hedef Çerçeve ayarını en az kitaplığın Hedef Çerçeve ayarı kadar yüksek bir API düzeyine ayarladığınızdan emin olun.

• Android kitaplığı oluştururken – Diğer uygulamalar tarafından kullanılmak üzere bir Android kitaplığı oluşturuyorsanız, Hedef Çerçeve ayarını derlemek için gereken en düşük API düzeyine ayarladığınızdan emin olun.

Kitaplığın çalışma zamanında kullanılamayan bir API'yi çağırmaya çalıştığı (uygulamanın kilitlenmesine neden olabilecek) durumu önlemeye yardımcı olması için bu en iyi yöntemler önerilir. Kitaplık geliştiricisiyseniz, API çağrıları kullanımınızı toplam API yüzey alanının küçük ve iyi oluşturulmuş bir alt kümesiyle kısıtlamaya çalışmanız gerekir. Bunu yapmak, kitaplığınızın daha geniş bir Android sürümü yelpazesinde güvenle kullanılabilmesini sağlamaya yardımcı olur.

Özet

Bu kılavuzda, Android'in farklı sürümlerinde uygulama uyumluluğunu yönetmek için Android API düzeylerinin nasıl kullanıldığı açıklanmıştır. Xamarin.Android Target Framework, Minimum Android sürümü ve Hedef Android sürümü proje ayarlarını yapılandırmak için ayrıntılı adımlar sağladı. Android SDK Yöneticisi'ni kullanarak SDK paketlerini yüklemeye yönelik yönergeler sağladı, çalışma zamanında farklı API düzeyleriyle başa çıkmak için kod yazma örnekleri ve Android kitaplıkları oluştururken veya kullanırken API düzeylerinin nasıl yönetileceğini açıkladı. Ayrıca API düzeylerini Android sürüm numaralarıyla (Android 4.4 gibi), Android sürüm adlarıyla (Kitkat gibi) ve Xamarin.Android derleme sürüm kodlarıyla ilişkilendiren kapsamlı bir liste de sağladı.

İlişkili Bağlantılar

• Android SDK Kurulumu
• SDK CLI Araç Değişiklikleri
• compileSdkVersion, minSdkVersion ve targetSdkVersion'ınızı seçme
• API Düzeyi nedir?
• Kod adları, Etiketler ve Derleme Numaraları