Android API düzeylerini anlama

Xamarin.Android, uygulamanı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 geliyor, nasıl yapılandıracakları ve çalışma zamanında uygulamanız üzerinde ne gibi etkileri olduğu açık bir şekilde açık bir şekilde ve bu ayarların nasıl yapılandırıldığından emin olun.

Hızlı başlangıç

Xamarin.Android, üç Android API düzeyi proje ayarı gösterir:

• Hedef Çerçeve – Uygulamanızı inşa etmek için hangi çerçevenin kullanılamayacaklarını belirtir. Bu API düzeyi derleme zamanında Xamarin.Android tarafından kullanılır.

• En Düşük Android Sürümü – Uygulamanı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ın üzerinde çalışması 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ırmadan önce, bu API düzeyi için SDK platformu bileşenlerini yüklemeniz gerekir. Bu bileşenleri indirme ve yükleme hakkında daha fazla Android SDK için bkz. Android SDK kurulumu.

Uygulamanız birden çok Android sürümünü destekliyorsa, kodunuzun En Düşük Android sürümü ayarıyla birlikte çalıştırıla olduğundan emin olmak için kodun ç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). Kitaplıkları tüketiyor 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'a bakın.

Android sürümleri ve API düzeyleri

Android platformu geliştikçe ve yeni Android sürümleri yayınlandıkçe, her Android sürümüne API Düzeyi adlı 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 sürümlere hem de Android'in en son sürümlerine uygulama yükleyene kadar, gerçek dünya Android uygulamalarının birden çok Android API düzeyiyle çalışacak şekilde tasarlanmış olması gerekir.

Android sürümleri

Android'in her sürümü birden çok adla devam ediyor:

• Android 9.0 gibi Android sürümü
• Pasta gibi bir kod (veya pasta) adı
• API düzeyi 28 gibi karşılık gelen bir API düzeyi

Android kod adı birden çok sürüme ve API düzeyine karşılık gelir (aşağıdaki tabloda olduğu gibi) ama her Android sürümü tam olarak bir API düzeyine karşılık gelir.

Ayrıca Xamarin.Android, o anda bilinen Android API düzeyleriyle eşlene derleme sürümü kodları 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ı içinde tanımlanmıştır) arasında çeviriye yardımcı Android.OS olabilir:

Bu tabloda da olduğu gibi, yeni Android sürümleri sıklıkla (bazen yılda birden fazla yayın) yayımlar. Sonuç olarak, uygulamanızı çalıştıracak Android cihaz evreni çok çeşitli eski ve daha yeni Android sürümleri içerir. Android'in bu kadar farklı sürümlerinde uygulamanın tutarlı ve güvenilir bir şekilde çalışmasını nasıl garanti musunuz? Android'in API düzeyleri bu sorunu yönetmenize yardımcı olabilir.

Android API düzeyleri

Her Android cihazı tam olarak tek bir API düzeyinde çalışır; bu API düzeyinin Android platformu sürümüne göre benzersiz olması garantidir. API düzeyi, api kümesi sürümünü tam olarak tanımlar ve bu sürümde uygulamanın çağırabilirsiniz; Bildirim öğelerinin, izinlerin vb. birleşimini tanımlar ve geliştirici olarak kodlar. Android'in API düzeyleri sistemi, Android'in uygulamayı bir cihaza yüklemeden önce bir android sistem görüntüsüyle uyumlu olup olmadığını belirlemeye yardımcı olur.

Bir uygulama yerleşik olduğunda aşağıdaki API düzeyi bilgilerini içerir:

• Android'in uygulamanın üzerinde çalıştıracak şekilde yerleşik hedef API düzeyi.

• Bir Android cihazı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 olduğundan emin olmak için kullanılır. Çalışmıyorsa, uygulamanın o cihazda çalıştırması engellenir. Örneğin, bir Android cihazı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 önler.

Project API düzeyi ayarları

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

Android SDK platformları

Xamarin.Android'de Hedef veya En Düşük API düzeyini seçemeden önce, bu API düzeyine karşılık gelen Android SDK platform sürümünü yüklemeniz gerekir. Target Framework, En Düşük Android sürümü ve Hedef Android sürümü için kullanılabilir seçenekler, Android SDK sürümleri aralığıyla sınırlıdır. Gerekli SDK Yöneticisi sürümlerinin yük olduğunu doğrulamak için Android SDK ve bunu kullanarak uygulamanıza gereken yeni API düzeylerini eklemek için kullanabilirsiniz. API düzeylerini yükleme hakkında bilginiz yoksa bkz. Android SDK..

Hedef Çerçeve

Hedef Çerçeve (olarak da bilinir), uygulamanın derleme zamanında derlenmiş olduğu belirli Android çerçeve sürümüdür (API düzeyi). Bu ayar, uygulamanın çalıştırıldıkları zaman hangi API'leri kullanmayı bekleyişini belirtir, ancak hangi API'ler yüklenirken uygulamanıza 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ıza hangi kitaplık sürümlerinin bağlı olduğunu belirler. Bu ayar, uygulamanıza hangi API'leri kullanabileceğinizi belirler. Örneğin, Android 5.0 Lollipop'ta tanıtılan NotificationBuilder.SetCategory yöntemini kullanmak için Hedef Çerçeve'yi API Düzeyi 21 (Lollipop) veya sonraki bir sürüme ayarlamalısınız. Projenizin Hedef Çerçevesini API Düzeyi 19 (KitKat) gibi bir API düzeyine ayarp kodunda yöntemini çağırmayı dener ve derleme hatası alırsınız.

Her zaman en son kullanılabilir Hedef Çerçeve sürümüyle derlemenizi öneririz. Bunu yapmak, kodunuz tarafından çağrılmış tüm kullanım dışı API'ler için size yararlı uyarı iletileri sağlar. En son Target Framework sürümünü kullanmak özellikle en son destek kitaplığı yayınlarını kullanırken önemlidir. Her kitaplık, uygulamanı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 da bilinir), android işletim sisteminizin en eski sürümüdür (en düşük API düzeyi) ve bu sürüm, uygulamalarınızı yükp çalıştırabilirsiniz. Varsayılan olarak, bir uygulama yalnızca Hedef Çerçeve ayarıyla eşleşen cihazlara veya daha üst bir cihaza yüklenebilirsiniz; 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ışmasına neden olabilir. Örneğin, Target Framework'ü Android 7.1 (Nookat) olarak ve Minimum Android sürümünü Android 4.0.3 (Ice Cream Sandwich)olarak ayarsanız, uygulamanız API düzeyi 15'den API düzeyi 25'e kadar herhangi bir platforma (dahil) yükleyebilir.

Uygulamanız bu çeşitli platformlarda başarıyla derleme ve yükleme yapasa da, tüm bu platformlarda başarıyla çalıştırılamayacaktır. Örneğin, uygulamanız Android 5.0 'a (Lollipop) yüklendiyse ve kodunuz yalnızca Android 7.1 (No bitmapt) ve daha yeni sürümlerde kullanılabilen bir API'yi çağırıyorsa, uygulama bir çalışma zamanı hatası alır ve büyük olasılıkla kilitlenmeye neden olur. Bu nedenle, kodunuzun çalışma zamanında yalnızca üzerinde çalıştırmış olduğu Android cihazı tarafından desteklenen API'leri çağırması gerekir. Başka bir deyişle, kodunuzun yalnızca bunları desteklemek için yeterince yeni olan cihazlarda daha yeni API'ler kullandığından emin olmak için açık çalışma zamanı denetimleri içermesi gerekir. Android Sürümleri için Çalışma Zamanı Denetimleri, bu kılavuzun devamlarında, bu çalışma zamanı denetimlerini kodunuza nasıl ekleyeceğiz?

Hedef Android Sürümü

Hedef Android Sürümü (olarak da bilinir), uygulamanın çalışması beklenilen Android cihazın API düzeyidir. Android, herhangi bir uyumluluk davranışının etkinleştirip etkinleştirilene olmadığını belirlemek için bu ayarı kullanır. Bu, uygulamanın beklediğiniz gibi çalışmaya devam eder. Android, uygulamanıza kesmeden hangi davranış değişikliklerinin uygulana olduğunu (Android'in ileriye dönük uyumluluk sağladığı) için uygulamanın Hedef Android sürüm ayarını kullanır.

Hedef Çerçeve ve Hedef Android sürümü, çok benzer adlara sahipken aynı şey değildir. Hedef Çerçeve ayarı, hedef API düzeyi bilgilerini derleme zamanında kullanmak üzere Xamarin.Android'e iletir. Hedef Android sürümü ise hedef API düzeyindeki bilgileri çalışma zamanında kullanmak üzere Android'e iletir (uygulama bir cihazda yüklü olduğunda ve çalışırken).

Genel olarak, Hedef Android Sürümü En Düşük Android Sürümü ve Hedef Çerçeve ile sınırlandı. 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 Geliştirici uses-sdk belgelerine bakın.

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

Android'in her yeni sürümü yayınlandıkça, çerçeve API'si yeni veya değiştirme işlevselliği sağlayacak şekilde güncelleştirilir. Birkaç özel durum dışında, önceki Android sürümlerine göre API işlevselliği değişiklik yapılmadan daha yeni Android sürümlerine iletildi. Sonuç olarak, uygulamanız belirli bir Android API düzeyinde çalışıyorsa, genellikle değişiklik yapmadan daha sonraki bir Android API düzeyinde çalışır. Peki ya uygulamalarınızı android'in önceki sürümlerinde çalıştırmak da istiyorsanız?

Hedef Çerçeve ayarından daha düşük bir En Düşük Android sürümü seçerseniz bazı API'ler çalışma zamanında uygulamanıza sağlanmaz. Ancak, uygulamanız daha önceki bir cihazda yine de çalışmasına rağmen işlevselliği azaltılmıştır. En Düşük Android sürüm ayarınıza karşılık gelen Android platformlarında mevcut olmayan her API için, kodunuzun uygulamanın üzerinde çalıştır olduğu platformun API düzeyini belirlemek için özelliğin değerini açıkça Android.OS.Build.VERSION.SdkInt denetlemesi gerekir. API düzeyi, çağrısı yapmak istediğiniz API'yi destekleyen En Düşük Android sürümünden düşükse, kodunuzun bu API çağrısı yapmadan düzgün bir şekilde çalışması için bir yol bulması gerekir.

Örneğin, Android 5.0 Lollipop (ve sonrası) üzerinde çalıştırılan bir bildirimi kategorilere ayırmak için NotificationBuilder.SetCategory yöntemini kullanmak istediğinize ancak yine de uygulamamızın Android 4.1 Veya Sonraki Bean (burada kullanılamaz) gibi android'in önceki sürümlerinde çalışmasına izin vermek istediğinizi varsayalım. Bu kılavuzun başındaki Android sürüm tablosuna bakarak, Android 5.0 Lollipop için derleme sürümü kodunun olduğunu görüyoruz. Mevcut olmayan Eski Android sürümlerini desteklemek için, kodumuz çalışma zamanında API düzeyini algılanabilir ve koşullu olarak yalnızca API düzeyi Lollipop derleme sürüm kodundan büyük veya ona eşit olduğunda SetCategorySetCategory çağırabilir:

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) ve En Düşük Android sürümü Android 4.1 (API Düzeyi 16)olarak ayarlanmıştır. API düzeyinde ve daha sonra kullanılabilir olduğundan, bu örnek kod yalnızca gerçekten kullanılabilir olduğunda çağıracak; API düzeyi SetCategoryAndroid.OS.BuildVersionCodes.LollipopSetCategorySetCategorySetCategory 16, 17, 18, 19 veya 20 olduğunda çağırmayı denemez. İşlevsellik, bu önceki Android sürümlerinde yalnızca bildirimlerin düzgün bir şekilde sıralanmayacak şekilde (türe göre kategorilere ayrılmış değil) kapsamına azaltıldı, ancak kullanıcıya uyarı sağlamak için bildirimler 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 bir şey yapmakla eski yol arasında karar vermesini sağlar. Örnek:

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ıştır çalıştırarak uygulamanı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), kullanılabilir durumda değilken SetCategory API çağrısını atlarsınız. Ancak, diğer durumlarda, uygulamanıza en uygun deneyimi sunmak için gereken API düzeyinden daha düşük olduğu algılandığında alternatif Android.OS.Build.VERSION.SdkInt işlevler uygulamanız gerekir.

API düzeyleri ve kitaplıkları

En Düşük Android sürümü ve Hedef Android sürümü ayarları kullanılamaz çünkü sonuçta elde edilen kitaplık tek başına bir uygulama değildir; kitaplık, paketlenin olduğu uygulamaya bağlı olarak herhangi bir Android sürümünde çalıştırabilirsiniz. Kitaplığın nasıl derlen olacağını belirtebilirsiniz,ancak kitaplığın hangi platform API düzeyinde çalıştır olacağını tahmin etmek mümkün olmayacaktır. Bu nedenle, kitaplıkları tüketen veya oluştururken aşağıdaki en iyi yöntemler gözlemlenmeli:

• Android kitaplığını tüketenler – Uygulamanıza bir Android kitaplığını tüketıyorsanız, uygulamanın Hedef Çerçeve ayarını kitaplığın Hedef Çerçeve ayarı kadar yüksek bir API düzeyine ayarsanız emin olun.

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

Bu en iyi yöntemler, bir kitaplığın çalışma zamanında mevcut olan bir API'yi çağırmaya çalışmaması (uygulamanın kilitlenmesini neden olabilir) önlemeye yardımcı olmak için önerilir. Bir kitaplık geliştiricisiyseniz, API çağrılarının kullanımını toplam API yüzey alanı için küçük ve iyi kurulmuş bir alt kümeyle kısıtlamaya çalışmanız gerekir. Bunu yapmak, kitaplığınızı daha geniş bir Yelpazedeki Android sürümlerinde güvenli bir şekilde kullanamanıza yardımcı olur.

Özet

Bu kılavuzda, Android API düzeylerinin farklı Android sürümleri arasında uygulama uyumluluğunu yönetmek için nasıl kullanıldıkları açıklanmıştır. Xamarin.Android HedefÇerçevesi, En Düşük Android sürümü ve Hedef Androidsürümü proje ayarlarını yapılandırmak için ayrıntılı adımlar sağlanmıştır. Sdk paketlerini yüklemek için Android SDK Yöneticisi kullanma yönergeleri, çalışma zamanında farklı API düzeyleriyle başa baş etmek için kod yazma örnekleri ve Android kitaplıklarını oluştururken veya kullanırken API düzeylerini yönetmeyi açıkladı. Ayrıca API düzeylerini Android sürüm numaralarıyla (Android 4.4 gibi), Android sürüm adları (Kitkat gibi) ve Xamarin.Android derleme sürüm kodlarıyla ilgili kapsamlı bir liste de sağlanmıştır.

İlişkili Bağlantılar

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